# Inside an Agent Mailbox: Folders, Storage, and Structure > Source: > Published: 2026-06-15 14:59:13+00:00 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//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//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//drafts/" \ --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.