DEV Community

Qasim Muhammad
Qasim Muhammad

Posted on

Under the Hood: An Agent Account Is Just a Grant

#architecture #api #email #agents

The best feature of Agent Accounts is the API they didn't build.

When Nylas shipped hosted mailboxes for AI agents (currently in beta), the obvious move would've been a new resource: /v3/agents/{agent_id}/messages, a new SDK module, new webhook shapes, new auth. Instead, an Agent Account is just another grant. It gets a grant_id, and that ID addresses the exact same /v3/grants/{grant_id}/* endpoints as a connected Gmail or Outlook account. No separate client, no URL prefix, no new payload schemas.

That one design decision does a surprising amount of work. Let's trace it.

A grant is an identity handle

In the v3 API, a grant represents an authenticated mailbox — normally created when a user completes OAuth. Every email and calendar operation hangs off it: GET /v3/grants/{grant_id}/messages, POST /v3/grants/{grant_id}/events, and so on.

An Agent Account slots into that abstraction with "provider": "nylas". The mailbox is Nylas-hosted, so there's no OAuth dance and no refresh token — you create the grant directly:

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer $NYLAS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "nylas",
    "settings": { "email": "agent@agents.yourcompany.com" }
  }'
Enter fullscreen mode Exit fullscreen mode

From the rest of the platform's perspective, the result is indistinguishable from any other grant. Which means everything downstream works for free.

Everything that works unchanged

The supported endpoints reference reads less like a feature list and more like an inventory of inherited behavior:

  • Messages — list with the full filter set (thread_id, from, unread, received_after...), fetch with fields=raw_mime, update flags, send, plus PUT /messages/clean to extract display-ready content from up to 20 messages at a time.
  • Threads, Folders, Drafts, Attachments — full CRUD where it applies. Six system folders (inbox, sent, drafts, trash, junk, archive) are provisioned automatically; custom folders sit alongside them.
  • Calendars and Events — a primary calendar per account, free/busy lookups, event CRUD, and send-rsvp with yes/no/maybe over standard iCalendar/ICS, so Google Calendar, Microsoft 365, and Apple Calendar treat the agent as a normal participant.
  • Contacts — CRUD with filtering by email, phone_number, or source.
  • Webhooks — message.created, message.updated, the deliverability triggers (message.send_success, message.send_failed, message.bounce_detected), event and contact triggers, grant lifecycle triggers. Payload shapes match the existing schemas exactly. One quirk worth knowing: when a message body exceeds ~1 MB, the trigger name becomes message.created.truncated and the body is omitted.

If you've already built against connected accounts, your message parser, your webhook handler, your SDK calls, your retry logic — all of it applies. Need to tell agent traffic apart from human traffic in a shared handler? Branch on the grant's provider field. That's the entire integration cost.

One grant_id, three subsystems

To make the claim concrete, here's a single agent handling mail and calendar with the same handle. Check for unread replies:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/$GRANT_ID/messages?unread=true&limit=20" \
  --header "Authorization: Bearer $NYLAS_API_KEY"
Enter fullscreen mode Exit fullscreen mode

Check the agent's own availability before proposing a meeting slot:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/$GRANT_ID/calendars/free-busy" \
  --header "Authorization: Bearer $NYLAS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "start_time": 1718000000, "end_time": 1718086400, "emails": ["agent@agents.yourcompany.com"] }'
Enter fullscreen mode Exit fullscreen mode

Accept an invitation someone sent the agent:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/$GRANT_ID/events/$EVENT_ID/send-rsvp?calendar_id=$CALENDAR_ID" \
  --header "Authorization: Bearer $NYLAS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "status": "yes" }'
Enter fullscreen mode Exit fullscreen mode

Three subsystems — messages, calendars, events — one identity, one auth header. The RSVP goes out as an ICS REPLY to every participant; creating an event with notify_participants=true sends an ICS REQUEST, and deleting one the agent organized sends an ICS CANCEL. The other side never knows it's talking to an API.

Small print worth knowing

A few inherited behaviors come with inherited quirks:

  • Sending a draft is a POST against the draft itself (POST /v3/grants/{grant_id}/drafts/{draft_id}) — there's no separate "send draft" endpoint. And while draft.created and draft.updated webhooks fire, deleting a draft fires no draft.deleted event.
  • System folders are reserved and immutable. You can create and rename custom folders freely, but the six system folder names can't be reused and system folders can't be modified.
  • The primary calendar can't be deleted while other calendars exist — plan teardown order accordingly.
  • Message deletes are soft. DELETE on a message or thread moves it to Trash rather than destroying it.

What's genuinely new

The reuse isn't total, and the additions are telling: they're all admin surfaces, not mailbox surfaces.

Resource What it adds
Policies Bundle send limits, spam detection, and retention; attach one policy to a workspace and it governs every Agent Account in it
Rules Match inbound mail or outbound sends on from.*, recipient.*, or outbound.type, then block, mark_as_spam, assign_to_folder, and more
Lists Typed collections of domains, TLDs, or addresses that rules reference via in_list
Rule evaluations GET /v3/grants/{grant_id}/rule-evaluations — an audit trail of which rules ran and what they did
IMAP/SMTP Protocol access via an app_password, so humans can supervise from a mail client

A few things from the connected-grant world don't carry over: Smart Compose, Templates and Workflows, contact groups, provider-native search syntax (there's no Gmail underneath), and open/click tracking on API sends. The docs call these out explicitly rather than letting you discover them in production.

Why this matters beyond convenience

Reusing the grant abstraction is what makes Agent Accounts cheap to adopt and cheap to operate. Limits live in one mental model (200 messages per account per day on the free plan, enforced like any other grant-level behavior). Monitoring is one pipeline — grant lifecycle webhooks fire for agents too, though Agent Accounts rarely expire because there's no OAuth token to refresh. And multi-provider apps get hybrid architectures almost by accident: human inboxes and agent inboxes flowing through one codebase.

There's a general lesson for API design here. When you add a new noun to your platform, the real cost isn't building it — it's every integration that now needs a second code path. The grant-shaped Agent Account avoids that tax almost entirely.

If you want to verify the claim yourself, the Agent Accounts overview links a quickstart that goes from nothing to a working mailbox in under 5 minutes — using endpoints you may have already written code against. Take whatever grant-based integration you have today and point it at an Agent Account grant_id. How much of it just works?

Top comments (0)