# How Agent Account mailboxes work

Source: https://developer.nylas.com/docs/v3/agent-accounts/mailboxes/

Every Agent Account has a real mailbox with a real address -- something like `sales-agent@yourcompany.com` or `voice-agent@agents.yourcompany.com`. It sends outbound mail, receives inbound mail, maintains folders, and has its own deliverability reputation. To anyone interacting with it over SMTP, it's indistinguishable from a human-operated mailbox.

This page walks through what actually happens when an Agent Account sends a message, what happens when mail arrives, and how the mailbox surface maps onto Nylas's existing [Email API](/docs/v3/email/). If you're looking for the complete endpoint list, see [Supported endpoints](/docs/v3/agent-accounts/supported-endpoints/).

## The mailbox at a glance

When you [provision an Agent Account](/docs/v3/agent-accounts/provisioning/), Nylas creates a hosted mailbox on one of your registered domains and returns a `grant_id`. That grant ID is the only identifier you need -- the existing [Messages](/docs/reference/api/messages/), [Threads](/docs/reference/api/threads/), [Folders](/docs/reference/api/folders/), [Drafts](/docs/reference/api/drafts/), and [Attachments](/docs/reference/api/attachments/) endpoints all work against `/v3/grants/{grant_id}/...` the same way they do for any other grant.

Every mailbox comes with:

- **A primary email address** on a domain you've verified, or on a Nylas-provided `*.nylas.email` trial domain.
- **Six system folders** provisioned automatically: `inbox`, `sent`, `drafts`, `trash`, `junk`, and `archive`. You can create custom folders alongside them with [`POST /folders`](/docs/reference/api/folders/post-folder/). System folder names are reserved.
- **A thread index** built from standard RFC 5322 headers so replies group into conversations. See [Email threading for agents](/docs/v3/agent-accounts/email-threading/) for the full details.
- **An optional `app_password`** on the grant for IMAP and SMTP submission, so end users can connect Outlook or Apple Mail alongside the API. See [Mail client access](/docs/v3/agent-accounts/mail-clients/).

Inbound and outbound mail use the same Nylas-hosted infrastructure whether you drive the mailbox through the API, through IMAP/SMTP, or through both at once. Anything sent via IMAP/SMTP appears as a message in the API; anything sent via the API appears in the Sent folder in the mail client.

## Receiving email

An inbound message goes through this lifecycle:

1. **The remote sender delivers to Nylas over SMTP.** The sending server looks up the MX record for the Agent Account's domain and opens an SMTP connection to Nylas's inbound infrastructure.
2. **Nylas runs policy checks.** If the grant has a [policy](/docs/v3/agent-accounts/policies-rules-lists/) attached, any [rules](/docs/reference/api/rules/) that match inbound conditions run here -- `block` rejects the message at the SMTP layer, `mark_as_spam` routes it to `junk`, `assign_to_folder` routes it to a named folder, and so on. [Rule evaluations](/docs/reference/api/rules/list-rule-evaluations/) are logged for audit.
3. **The message is stored and delivered to a folder.** Default destination is `inbox`; rules or the sender's address can route it elsewhere.
4. **The webhook fires.** If you've subscribed to the [`message.created`](/docs/reference/notifications/messages/message-created/) webhook, you'll receive a payload identical in shape to `message.created` for any other grant. If the body exceeds ~1 MB, the trigger name becomes `message.created.truncated` and the body is omitted -- fetch the full message with [`GET /messages/{id}`](/docs/reference/api/messages/get-messages-id/) in that case.
5. **The message is added to a thread.** Nylas reads the `In-Reply-To` and `References` headers to attach it to an existing thread, or creates a new thread if this is the first message in a conversation. The webhook payload's `thread_id` is the key your agent uses to reconstruct conversation state.

Inbound attachments count against the limits set by your plan and the grant's [policy](/docs/v3/agent-accounts/policies-rules-lists/) -- the configurable `limit_attachment_size_limit`, `limit_attachment_count_limit`, and `limit_attachment_allowed_types` settings control what's accepted. Attachments that exceed these caps are dropped from the message; the message itself is still delivered and `message.created` still fires.

If you'd rather poll than subscribe to webhooks, [`GET /messages`](/docs/reference/api/messages/get-messages/) with `received_after` works fine for batch workflows. Webhooks are preferred for near-real-time agent loops because delivery typically lands within seconds of the SMTP handoff.

## Sending email

Outbound from the API uses [`POST /v3/grants/{grant_id}/messages/send`](/docs/reference/api/messages/send-message/). The body is JSON, or multipart for attachments, and takes the same shape as sending from any other grant -- `to`, `cc`, `bcc`, `subject`, `body`, and optional `reply_to_message_id`, `tracking_options`, and `custom_headers`.

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "to": [{ "email": "alice@example.com" }],
    "subject": "Following up on your demo request",
    "body": "Hi Alice, thanks for your interest..."
  }'
```

A few things to know about how sends work:

- **Send happens from the Agent Account's address.** Nylas stamps the `From` header with the grant's primary address. Agent Accounts can't spoof other identities. If you omit the `from` field entirely, the API defaults it to the grant's address and uses the grant's `name` as the display name when one is set; a `from` you provide -- including an email-only one -- is preserved as-is.
- **Threading is automatic on replies.** Pass `reply_to_message_id` and Nylas populates `Message-ID`, `In-Reply-To`, and `References` so the reply threads in every recipient's mail client. Details in [Email threading for agents](/docs/v3/agent-accounts/email-threading/).
- **Enabled outbound rules can block or rewrite sends.** When your application has enabled rules with `outbound.type` or recipient matchers, Nylas evaluates them before the message hits SMTP. Policies link inbound rules; outbound evaluation uses the application's enabled outbound rules. See [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/).
- **Send quota is tracked per account.** On the free plan the default limit is 200 messages per account per day; paid plans have no daily cap by default. You can set a stricter quota per account through a [policy](/docs/v3/agent-accounts/policies-rules-lists/). Sends over the limit return an error on the API call.
- **Outbound messages are capped at 25 MB.** Nylas enforces a 25 MB total message size limit on every outbound path -- API sends, draft sends, and SMTP submission. Some recipient servers enforce even lower limits, so a message under this cap can still be rejected by the remote MX.

After Nylas hands the message to the recipient's server, deliverability signals come back as webhooks:

| Trigger | When it fires |
| --- | --- |
| [`message.delivered`](/docs/reference/notifications/agent-accounts/message-delivered/) | The message was successfully delivered to the recipient's mail server. |
| [`message.bounced`](/docs/reference/notifications/agent-accounts/message-bounced/) | The message was not delivered because of a hard bounce. |
| [`message.complaint`](/docs/reference/notifications/agent-accounts/message-complaint/) | The message was delivered, but the recipient marked it as spam. |
| [`message.rejected`](/docs/reference/notifications/agent-accounts/message-rejected/) | The message was rejected because one or more attachments contained a virus. |

Because Nylas owns the SMTP path end-to-end for Agent Accounts, these triggers give you send-side visibility on every outbound message. Sender reputation is shared across every Agent Account on a given domain, so treat outbound hygiene as a domain-level concern. See [Domain warming](/docs/v3/agent-accounts/domain-warming/) when you're rolling out a new custom domain at scale.

### Drafts

Drafts are supported with full CRUD at [`/v3/grants/{grant_id}/drafts`](/docs/reference/api/drafts/). Create one, update it, then POST to `/drafts/{draft_id}` to send -- the send action on an existing draft behaves the same as `POST /messages/send`. This is useful for human-in-the-loop flows where an agent proposes a reply and a reviewer approves it before delivery.

## Threading replies

Replies group into conversations using the standard `Message-ID`, `In-Reply-To`, and `References` headers. Every `message.created` webhook payload includes a `thread_id` -- fetch the thread to reconstruct what's been said before your agent decides how to respond:

```bash
curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/threads/<THREAD_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
```

To send a reply that threads correctly, pass `reply_to_message_id` on `POST /messages/send`. Nylas sets the threading headers on the outbound message automatically.

For the full protocol-level explanation and the state-mapping pattern for multi-turn conversations, see [Email threading for agents](/docs/v3/agent-accounts/email-threading/).

## Keep in mind

- **Fetch the thread before responding.** An agent that drafts replies needs the full thread history to avoid repeating itself or contradicting earlier messages. Don't reply off the single-message payload from the webhook alone.
- **Inbound filtering is cheaper than reacting to noise.** Use [rules](/docs/reference/api/rules/) to drop obvious spam, loops, and mailer-daemon replies before `message.created` fires. It keeps the agent from reacting to auto-replies.
- **Mail clients see the same mailbox as the API.** Anything sent via IMAP/SMTP appears in the Messages API; anything sent via the API appears in the Sent folder in the mail client. There's no separation between protocol traffic and API traffic.

## What's next

- [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) to send and receive your first message in under 5 minutes
- [Email threading for agents](/docs/v3/agent-accounts/email-threading/) for how replies group into threads and how to reply in-thread
- [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) to apply policy-linked inbound rules and application-scoped outbound rules
- [Mail client access (IMAP & SMTP)](/docs/v3/agent-accounts/mail-clients/) to expose the mailbox to Outlook, Apple Mail, and other clients
- [Supported endpoints](/docs/v3/agent-accounts/supported-endpoints/) for the full reference of Messages, Threads, Folders, Drafts, and Attachments endpoints
- [Handle email replies](/docs/cookbook/agent-accounts/handle-replies/) and [multi-turn conversations](/docs/cookbook/agent-accounts/multi-turn-conversations/) for reply-loop patterns
- [Messages API](/docs/v3/email/messages/) and [Send email](/docs/v3/email/send-email/) for the general Email API surface these endpoints share with connected grants