DEV Community

Qasim Muhammad
Qasim Muhammad

Posted on • Originally published at developer.nylas.com

Inside an Agent Mailbox: Folders, Storage, and Structure

#architecture #api #email #agents

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"
Enter fullscreen mode Exit fullscreen mode

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.

What every mailbox ships with

Provision an account and the returned grant_id unlocks a complete mailbox, not just a send endpoint:

  • A real address on a verified domain (or a *.nylas.email trial domain), with its own deliverability reputation.
  • The six system folders, plus room for custom ones — a triage agent might add escalations and invoices and route mail into them with rules.
  • A thread index built from standard RFC 5322 headers, so replies group into conversations automatically.
  • Optional IMAP/SMTP access via an 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 life of an inbound message

The mailboxes doc traces five stages between a stranger hitting "send" and your agent reacting:

  1. SMTP delivery. The sender's server looks up the domain's MX record and hands the message to the hosted inbound infrastructure.
  2. Policy checks. If the grant's workspace carries a policy, inbound rules run here — 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.
  3. Storage and folder delivery. Default destination is inbox, unless a rule said otherwise.
  4. Webhook fire. 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.
  5. Thread indexing. 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.

What the send path enforces

Outbound goes through POST /v3/grants/{grant_id}/messages/send, with a few hard behaviors worth knowing before you ship:

  • No identity spoofing. The 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.
  • Quota per account. 200 messages per account per day on the free plan; paid plans have no daily cap by default, and a policy can set a stricter quota. Over-limit sends fail with an error on the API call.
  • 40 MB outbound cap on every send path — API, draft sends, and SMTP submission alike. Recipient servers often enforce less (typically ~25 MB), so staying under the cap doesn't guarantee acceptance.
  • Outbound rules run pre-SMTP. Enabled application rules matching 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.

Drafts as an approval queue

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"
Enter fullscreen mode Exit fullscreen mode

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.

Designing around the structure

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.

Top comments (0)