Quickstart: Agent Accounts (Beta)

Agent Accounts are in beta. The API and features may change before general availability.

Nylas Agent Accounts are fully functional email and calendar identities — real [email protected] mailboxes that Nylas hosts for you. You create and manage them entirely through the API, and they behave exactly like human-operated accounts to anyone interacting with them.

This quickstart walks through creating your first Agent Account and sending and receiving a message. For the full concept guide, see What are Agent Accounts.

Use an Agent Account when you want to:

• Give an AI agent a real email address it can send from, receive on, and RSVP to meetings with
• Run a system mailbox (sales@, support@, scheduling@) that your application owns end-to-end — no OAuth flow, no user’s inbox to connect
• Spin up ephemeral mailboxes for workflows, projects, or individual customers

Before you begin

You need a Nylas API key. If you haven’t set up your account yet:

• Get started with the CLI — run nylas init to create an account and generate an API key in one command
• Get started with the Dashboard — the same steps through the web UI

Pick a domain

Every Agent Account lives on a domain. You have two options:

• Use a Nylas trial domain — Nylas provides *.nylas.email subdomains for immediate testing. Register one from the Dashboard and you can create accounts like test@<your-application>.nylas.email right away.
• Use your own domain — register it in Organization Settings → Domains, add the MX and TXT records Nylas gives you to your DNS provider, and Nylas verifies it automatically.

We recommend a dedicated subdomain for production use (for example, agents.yourcompany.com). See Provisioning and domains for the full flow, or Managing domains for API-driven DNS setup.

Create an Agent Account

From the CLI

The quickest path is the Nylas CLI. After nylas init you get a single command for creating Agent Accounts:

nylas agent account create [email protected]

The CLI prints the new grant ID alongside the status and connector details. You can list everything with nylas agent account list or confirm the connector is ready with nylas agent status. Agent Accounts also show up in nylas auth list alongside connected grants.

From the Dashboard

On the left navigation, open Agent Accounts → Accounts and click Create account. Pick a registered domain and an alias — the account is live immediately.

Programmatically

Use POST /v3/connect/custom with "provider": "nylas". Unlike OAuth providers, you don’t need a refresh token — just the email address on a registered domain.

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 — you’ll use it in every subsequent call. From this point on, the Agent Account works with every existing Nylas endpoint.

(Optional) Apply a policy at creation

If you’ve created a policy to configure limits, spam detection, or inbound rules, pass policy_id in settings:

{
  "provider": "nylas",
  "settings": {
    "email": "[email protected]",
    "policy_id": "<POLICY_ID>"
  }
}

Receive a message

Agent Accounts use the same messages API as any other Nylas grant.

Option 1 — Poll the Messages endpoint

List the account’s inbox with GET /v3/grants/{grant_id}/messages:

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

To fetch a specific message including its body:

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

Option 2 — Receive webhooks

Register a message.created webhook and Nylas will call your URL as soon as a message arrives. The payload is identical in shape to message.created for any other grant — branch on the grant’s provider ("nylas") if you need to distinguish Agent Account deliveries from connected-grant deliveries.

From the Nylas CLI:

nylas webhook create \
  --url https://yourapp.example.com/webhooks/nylas \
  --triggers message.created

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"],
    "callback_url": "https://yourapp.example.com/webhooks/nylas"
  }'

Example message.created payload for an Agent Account:

Example

{
  "specversion": "1.0",
  "type": "message.created",
  "id": "<WEBHOOK_ID>",
  "time": 1723821985,
  "webhook_delivery_attempt": 1,
  "data": {
    "application_id": "<NYLAS_APPLICATION_ID>",
    "object": {
      "object": "message",
      "id": "<MESSAGE_ID>",
      "grant_id": "<NYLAS_GRANT_ID>",
      "subject": "Hello from Nylas",
      "from": [{ "email": "[email protected]", "name": "Sender" }],
      "to": [{ "email": "[email protected]", "name": "" }],
      "date": 1723821981,
      "snippet": "This is a sample message"
    }
  }
}

For the full schema, see the message.created webhook reference.

Handle attachments

Inbound attachment limits are set by your plan and the grant’s policy — tune limit_attachment_size_limit, limit_attachment_count_limit, and limit_attachment_allowed_types on the policy as needed. Attachment IDs come through on the message object; download with GET /v3/grants/{grant_id}/attachments/{attachment_id}/download:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachments/<ATTACHMENT_ID>/download?message_id=<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

Send a message

Send outbound mail with the same POST /v3/grants/{grant_id}/messages/send endpoint you use for any connected grant:

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": "Hello from my Agent Account",
    "body": "This message was sent by a Nylas Agent Account.",
    "to": [{ "email": "[email protected]", "name": "You" }]
  }'

The recipient sees a normal message from your Agent Account’s address — no “sent via” branding, no relay footer.

Use the calendar

Every Agent Account comes with a primary calendar. You can list events, create events, and RSVP to invitations through the same endpoints you use for any other grant:

• GET /v3/grants/{grant_id}/events — list events
• POST /v3/grants/{grant_id}/events — create an event and invite others
• POST /v3/grants/{grant_id}/events/{id}/send-rsvp — accept or decline a received invitation; the RSVP is visible to every participant

Invitations arrive over standard iCalendar/ICS, so Google Calendar, Microsoft 365, and Apple Calendar all treat the Agent Account as a normal participant.

Test it end-to-end

1. Send an email from any client (Gmail, your phone, etc.) to your Agent Account’s address.
2. Confirm it arrives — either through the message.created webhook or by listing /messages.
3. Send a reply from the Agent Account using the /send endpoint above and verify it lands back in your client.

What’s next

• What are Agent Accounts — the full concept guide, capabilities, and architecture
• Provisioning and domains — custom domains, multi-tenant patterns, and programmatic account creation
• Policies, Rules, and Lists — configure limits, spam detection, and inbound filtering
• BYO Auth reference — nylas provider — the full request body for programmatic creation
• Webhooks — full webhook configuration and notification schemas
• Messages API reference — complete endpoint documentation