{"slug": "inside-an-agent-mailbox-folders-storage-and-structure", "title": "Inside an Agent Mailbox: Folders, Storage, and Structure", "summary": "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.", "body_md": "One GET request tells you most of what an agent mailbox is made of:\n\n```\ncurl --request GET \\\n  --url \"https://api.us.nylas.com/v3/grants/<GRANT_ID>/folders\" \\\n  --header \"Authorization: Bearer $NYLAS_API_KEY\"\n```\n\nRun 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`\n\n, `sent`\n\n, `drafts`\n\n, `trash`\n\n, `junk`\n\n, and `archive`\n\n. They're provisioned automatically, their names are reserved, and you can create custom folders alongside them with `POST /folders`\n\n. That structure isn't decoration; it shapes how an agent's whole workflow gets organized.\n\nProvision an account and the returned `grant_id`\n\nunlocks a complete mailbox, not just a send endpoint:\n\n`*.nylas.email`\n\ntrial domain), with its own deliverability reputation.`escalations`\n\nand `invoices`\n\nand route mail into them with rules.`app_password`\n\n, 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}/...`\n\nexactly as they do for any connected grant.\n\nThe [mailboxes doc](https://developer.nylas.com/docs/v3/agent-accounts/mailboxes/) traces five stages between a stranger hitting \"send\" and your agent reacting:\n\n`block`\n\nrejects at the SMTP layer (the message never exists in the mailbox), `mark_as_spam`\n\nroutes to `junk`\n\n, `assign_to_folder`\n\nroutes to a named folder. Every evaluation is logged for audit.`inbox`\n\n, unless a rule said otherwise.`message.created`\n\ngoes out with the standard payload shape. One edge case: bodies over ~1 MB flip the trigger name to `message.created.truncated`\n\nand omit the body — fetch the full message by ID in that case.`In-Reply-To`\n\nand `References`\n\nheaders attach the message to an existing thread or start a new one; the webhook's `thread_id`\n\nis 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`\n\nfires — which means before your LLM spends tokens reading them.\n\nAttachments have their own gate: policy limits (`limit_attachment_size_limit`\n\n, `limit_attachment_count_limit`\n\n, `limit_attachment_allowed_types`\n\n) control what's accepted. Oversized attachments get dropped from the message, but the message itself still delivers and the webhook still fires.\n\nOutbound goes through `POST /v3/grants/{grant_id}/messages/send`\n\n, with a few hard behaviors worth knowing before you ship:\n\n`From`\n\nheader is stamped with the grant's primary address; omit `from`\n\nand it defaults to the grant's address with the grant's display name.`outbound.type`\n\nor recipients are evaluated before the message leaves.After handoff, three webhooks report what happened:\n\n| Trigger | When it fires |\n|---|---|\n`message.send_success` |\nThe recipient server accepted the message |\n`message.send_failed` |\nThe send failed before reaching the recipient — an outbound rule block, a policy limit, a deliverability gate |\n`message.bounce_detected` |\nHard or soft bounce returned by the remote server |\n\nBecause 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`\n\n, `message.link_clicked`\n\n) isn't emitted for API sends from an Agent Account, so deliverability is what you observe through the three triggers above, not engagement pixels.\n\nThe `drafts`\n\nfolder isn't vestigial. Full CRUD lives at `/v3/grants/{grant_id}/drafts`\n\n, 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:\n\n```\n# Agent proposes a reply\ncurl --request POST \\\n  --url \"https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts\" \\\n  --header \"Authorization: Bearer $NYLAS_API_KEY\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"to\": [{ \"email\": \"alice@example.com\" }],\n    \"subject\": \"Re: Refund request for order #4821\",\n    \"body\": \"Hi Alice, I can process that refund today...\"\n  }'\n\n# Reviewer approves — sending an existing draft is a POST to the draft itself\ncurl --request POST \\\n  --url \"https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts/<DRAFT_ID>\" \\\n  --header \"Authorization: Bearer $NYLAS_API_KEY\"\n```\n\nThe reviewer can read the pending draft through the API, or — because the same mailbox is exposable over IMAP with an `app_password`\n\n— straight from Outlook or Apple Mail. Sending the draft behaves exactly like `POST /messages/send`\n\n, quota and outbound rules included. No custom review-queue infrastructure required.\n\nThe 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`\n\nmarks what's done. State lives in the mailbox itself, inspectable by any IMAP client.\n\nIf your agent runs on a schedule rather than reacting to webhooks, the structure supports that too — poll `GET /messages`\n\nwith `received_after`\n\nfor 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.\n\nNext step: create an account, list its folders, then add one custom folder and an `assign_to_folder`\n\nrule — 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.", "url": "https://wpnews.pro/news/inside-an-agent-mailbox-folders-storage-and-structure", "canonical_source": "https://dev.to/qasim157/inside-an-agent-mailbox-folders-storage-and-structure-201b", "published_at": "2026-06-15 14:59:13+00:00", "updated_at": "2026-06-15 15:07:00.143364+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-infrastructure"], "entities": ["Nylas", "Nylas Agent Account", "SMTP", "API"], "alternates": {"html": "https://wpnews.pro/news/inside-an-agent-mailbox-folders-storage-and-structure", "markdown": "https://wpnews.pro/news/inside-an-agent-mailbox-folders-storage-and-structure.md", "text": "https://wpnews.pro/news/inside-an-agent-mailbox-folders-storage-and-structure.txt", "jsonld": "https://wpnews.pro/news/inside-an-agent-mailbox-folders-storage-and-structure.jsonld"}}