The grant_id: One Handle for Mail, Calendar, and Webhooks

Anyone who's wired an autonomous agent into email and calendar the traditional way knows the identifier sprawl: an OAuth client ID, a refresh token per user, a Gmail-specific message ID format, a Microsoft Graph calendar ID, and a webhook subscription ID for each — all with different lifetimes, all able to break independently. Half your "integration" code is really identifier bookkeeping. Nylas Agent Accounts collapse all of that into one value. When you create an account (the feature's in beta), the response hands you a grant_id , and that single string is the handle for everything the agent does — mail, calendar, contacts, attachments, and the webhooks reporting on all of them. One ID, the whole surface Every operation addresses the same path family, /v3/grants/{grant_id}/* : POST /v3/grants/{grant_id}/messages/send # send mail GET /v3/grants/{grant_id}/messages # read the inbox GET /v3/grants/{grant_id}/threads/{thread_id} # full conversation GET /v3/grants/{grant_id}/attachments/{id}/download POST /v3/grants/{grant_id}/events # host a meeting POST /v3/grants/{grant_id}/events/{id}/send-rsvp # respond to one GET /v3/grants/{grant_id}/contacts GET /v3/grants/{grant_id}/rule-evaluations # audit trail This isn't an abstraction invented for agents — an Agent Account is literally just another grant, the same primitive used for connected Gmail and Outlook accounts. The supported endpoints reference puts it as "same endpoints, same auth, same payloads." Anything you built for connected accounts works against an agent's grant unchanged. And the resources behind the ID are real: six system folders provisioned automatically ( inbox , sent , drafts , trash , junk , archive ), a primary calendar that speaks standard iCalendar, and outbound messages capped at 40 MB total. Webhooks route by it too The inbound side completes the picture. You subscribe once at the application level, and every notification — message.created , event.updated , message.bounce_detected , and the rest