Skip to content
Skip to main content

How Agent Account mailboxes work

Last updated:

Every Agent Account has a real mailbox with a real address — something like [email protected] or [email protected]. 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. If you’re looking for the complete endpoint list, see Supported endpoints.

The mailbox at a glance

Section titled “The mailbox at a glance”

When you provision an Agent Account, 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, Threads, Folders, Drafts, and 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. System folder names are reserved.
  • A thread index built from standard RFC 5322 headers so replies group into conversations. See Email threading for agents 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.

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

Section titled “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 attached, any 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 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 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} 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 — 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 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

Section titled “Sending email”

Outbound from the API uses POST /v3/grants/{grant_id}/messages/send. 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.

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": "[email protected]" }],
    "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.
  • 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.
  • 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. 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:

TriggerWhen it fires
message.deliveredThe message was successfully delivered to the recipient’s mail server.
message.bouncedThe message was not delivered because of a hard bounce.
message.complaintThe message was delivered, but the recipient marked it as spam.
message.rejectedThe 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 when you’re rolling out a new custom domain at scale.

Drafts

Section titled “Drafts”

Drafts are supported with full CRUD at /v3/grants/{grant_id}/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

Section titled “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:

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.

Keep in mind

Section titled “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 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

Section titled “What’s next”