One GET request tells you most of what an agent mailbox is made of:
curl --request GET \
--url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/folders" \
--header "Authorization: Bearer $NYLAS_API_KEY"
Run that against a freshly created Nylas Agent Account — the hosted-mailbox product currently in beta — and you get six system folders back before you've sent a single message: inbox
, sent
, drafts
, trash
, junk
, and archive
. They're provisioned automatically, their names are reserved, and you can create custom folders alongside them with POST /folders
. That structure isn't decoration; it shapes how an agent's whole workflow gets organized.
Provision an account and the returned grant_id
unlocks a complete mailbox, not just a send endpoint:
*.nylas.email
trial domain), with its own deliverability reputation.escalations
and invoices
and route mail into them with rules.app_password
, so a human can watch the same mailbox from Outlook or Apple Mail.The Messages, Threads, Folders, Drafts, and Attachments endpoints all work against /v3/grants/{grant_id}/...
exactly as they do for any connected grant.
The mailboxes doc traces five stages between a stranger hitting "send" and your agent reacting:
block
rejects at the SMTP layer (the message never exists in the mailbox), mark_as_spam
routes to junk
, assign_to_folder
routes to a named folder. Every evaluation is logged for audit.inbox
, unless a rule said otherwise.message.created
goes out with the standard payload shape. One edge case: bodies over ~1 MB flip the trigger name to message.created.truncated
and omit the body — fetch the full message by ID in that case.In-Reply-To
and References
headers attach the message to an existing thread or start a new one; the webhook's thread_id
is your key for reconstructing conversation state.Step 2 is the underrated one for agent builders. Filtering at the SMTP stage means mailer-daemon noise, auto-replies, and obvious spam can be dropped before message.created
fires — which means before your LLM spends tokens reading them.
Attachments have their own gate: policy limits (limit_attachment_size_limit
, limit_attachment_count_limit
, limit_attachment_allowed_types
) control what's accepted. Oversized attachments get dropped from the message, but the message itself still delivers and the webhook still fires.
Outbound goes through POST /v3/grants/{grant_id}/messages/send
, with a few hard behaviors worth knowing before you ship:
From
header is stamped with the grant's primary address; omit from
and it defaults to the grant's address with the grant's display name.outbound.type
or recipients are evaluated before the message leaves.After handoff, three webhooks report what happened:
| Trigger | When it fires |
|---|---|
message.send_success |
|
| The recipient server accepted the message | |
message.send_failed |
|
| The send failed before reaching the recipient — an outbound rule block, a policy limit, a deliverability gate | |
message.bounce_detected |
|
| Hard or soft bounce returned by the remote server |
Because the platform owns the SMTP path end to end, you get send-side visibility on every message — and since sender reputation is shared across every account on a domain, outbound hygiene is a domain-level concern, not a per-mailbox one. One absence to plan around: native open and click tracking (message.opened
, message.link_clicked
) isn't emitted for API sends from an Agent Account, so deliverability is what you observe through the three triggers above, not engagement pixels.
The drafts
folder isn't vestigial. Full CRUD lives at /v3/grants/{grant_id}/drafts
, and a POST to an existing draft sends it. That turns the folder into a natural human-in-the-loop mechanism — the agent writes, a human approves, and the approval is one call:
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts" \
--header "Authorization: Bearer $NYLAS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"to": [{ "email": "alice@example.com" }],
"subject": "Re: Refund request for order #4821",
"body": "Hi Alice, I can process that refund today..."
}'
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts/<DRAFT_ID>" \
--header "Authorization: Bearer $NYLAS_API_KEY"
The reviewer can read the pending draft through the API, or — because the same mailbox is exposable over IMAP with an app_password
— straight from Outlook or Apple Mail. Sending the draft behaves exactly like POST /messages/send
, quota and outbound rules included. No custom review-queue infrastructure required.
The mailbox layout suggests an agent architecture: rules sort inbound into folders by type, the agent processes folder by folder, drafts hold anything needing human eyes, and archive
marks what's done. State lives in the mailbox itself, inspectable by any IMAP client.
If your agent runs on a schedule rather than reacting to webhooks, the structure supports that too — poll GET /messages
with received_after
for batch workflows, then walk folders in priority order. Webhooks remain the better fit for conversational loops, since delivery typically lands within seconds of the SMTP handoff. Either way, budget for the free plan's 3 GB of storage per organization and 30-day inbox retention; an agent that archives aggressively and lets old mail age out fits comfortably inside both.
Next step: create an account, list its folders, then add one custom folder and an assign_to_folder
rule — and watch your inbound mail start sorting itself before your agent reads a word. The supported endpoints reference has the complete folder and message API surface.