Skip to content
Skip to main content

Give your agent its own email

Give your AI agent a real, independent [email protected] mailbox it fully owns — not a borrowed seat in a human’s inbox. Messages the agent sends come from the agent’s own address, replies land in a dedicated inbox, and every interaction is isolated from any human account. This is what a Nylas Agent Account is for: a Nylas-hosted mailbox you create and control entirely through the API.

Use this pattern when you want:

  • An agent identity that sends from [email protected], [email protected], or any other address you control.
  • Replies that stay in the agent’s inbox instead of clogging a human’s.
  • Persistent threaded conversations the agent owns — CRM outreach, support triage, scheduling negotiation, automated follow-ups.
  • Multi-agent deployments where each agent has its own mailbox, domain, and sender reputation.

If you’d rather have the agent act on your personal inbox, see Share your email with your agent instead.

Prerequisites

Section titled “Prerequisites”

Create the Agent Account

Section titled “Create the Agent Account”

The fastest path is the Nylas CLI:

nylas agent account create [email protected]

The CLI prints the new grant ID — save it, because the agent uses it on every subsequent call. nylas agent account list shows every Agent Account on the application, and nylas auth list includes them alongside connected grants.

Prefer the API? Use POST /v3/connect/custom with "provider": "nylas". You only need the email address — there’s no OAuth refresh token to manage.

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "nylas",
    "settings": {
      "email": "[email protected]"
    }
  }'

The response contains a grant_id. Save it — from this point on, the agent can drive the account with any Nylas grant-scoped endpoint, exactly like a connected grant.

Send email as the agent

Section titled “Send email as the agent”

Your agent sends outbound with POST /v3/grants/{grant_id}/messages/send. Recipients see a normal message from the agent’s address — no relay footer, no “sent via” branding.

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 '{
    "subject": "Following up on our demo",
    "body": "Hi Alice — great talking with you yesterday. A few next steps...",
    "to": [{ "email": "[email protected]", "name": "Alice" }]
  }'

Receive replies the agent can act on

Section titled “Receive replies the agent can act on”

Register a message.created webhook and your agent gets notified as soon as a reply arrives. The payload shape is identical to message.created for any other grant — your agent can branch on grant.provider == "nylas" if it also handles human inboxes.

From the Nylas CLI:

nylas webhook create \
  --url https://youragent.example.com/webhooks/nylas \
  --triggers "message.created,message.updated"

Or through the API:

curl --request POST \
  --url "https://api.us.nylas.com/v3/webhooks" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "trigger_types": ["message.created", "message.updated"],
    "callback_url": "https://youragent.example.com/webhooks/nylas"
  }'

If your agent polls instead of listening, list the mailbox on a cadence:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?unread=true&limit=20" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

Apply limits and filtering

Section titled “Apply limits and filtering”

Every endpoint for connected grants works against an Agent Account. On top of that, three admin APIs let you configure how each mailbox behaves:

  • Policies bundle send quotas, attachment limits, retention, and spam settings you can reuse across agents.
  • Rules block, mark as spam, or auto-route inbound messages based on from.address, from.domain, or from.tld.
  • Lists hold typed collections of domains or addresses that rules match against with in_list.

Attach a policy to a grant at creation by passing settings.policy_id, or inherit one from the nylas connector.

Multi-agent patterns

Section titled “Multi-agent patterns”

One Nylas application can run any number of Agent Accounts across any number of registered domains. Common setups:

  • Per-customer identity — each customer gets agent@<their-domain>.com, provisioned programmatically.
  • Per-workflow identity — sales-agent@..., support-agent@..., scheduling-agent@... on the same domain, each with its own policy.
  • Reputation isolation — high-volume outbound split across a.yourdomain.com, b.yourdomain.com so issues on one don’t contaminate the others.

Handle replies and threading

Section titled “Handle replies and threading”

The agent’s mailbox is bidirectional — it sends email and receives replies on the same address, in the same thread. When someone replies to a message the agent sent, Nylas groups it into the same thread automatically using In-Reply-To and References headers. The message.created webhook includes a thread_id you can use to match the reply to the original conversation without parsing headers yourself.

For the full pattern — detecting replies, restoring conversation context, replying in-thread, and managing multi-turn state — see these guides:

Let humans connect to the mailbox too

Section titled “Let humans connect to the mailbox too”

If you want humans — the agent’s human collaborator, an ops team, a customer — to access the agent’s mailbox from Outlook, Apple Mail, or another standard client, set an app_password on the grant. IMAP + SMTP submission stream the same mailbox the API reads and writes. See Mail client access (IMAP & SMTP) for the full setup.

What’s next

Section titled “What’s next”