Inside an Agent Mailbox: Folders, Storage, and Structure

Nylas's Agent Mailbox product, currently in beta, provides a full hosted mailbox with system folders (inbox, sent, drafts, trash, junk, archive) and custom folders, accessible via standard API endpoints. Inbound mail is filtered through configurable rules at the SMTP level before triggering webhooks, and outbound sends are tracked with success, failure, and bounce notifications. The platform also supports draft CRUD for human-in-the-loop workflows.

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 https://developer.nylas.com/docs/v3/agent-accounts/mailboxes/ — 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 https://developer.nylas.com/docs/v3/agent-accounts/mailboxes/ 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: Agent proposes a reply 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..." }' Reviewer approves — sending an existing draft is a POST to the draft itself 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 https://developer.nylas.com/docs/v3/agent-accounts/supported-endpoints/ has the complete folder and message API surface.