Connect mail clients to an Agent Account

Agent Accounts are primarily API-driven, but you can also expose an account over IMAP and SMTP submission so people (or you, for debugging) can connect a standard mail client like Outlook, Apple Mail, or Thunderbird. IMAP and the API read and write the same mailbox: a flag change, folder move, or delete through either surface is visible to the other within seconds.

Use protocol-level access when you want:

A hybrid workflow where an AI agent handles some messages via the API while a human reviews or replies from a familiar mail client.
Direct debugging of an Agent Account with a regular IMAP/SMTP client.
A traditional mail experience for the person using the mailbox, with the API automation layered on top.

Before you begin

You need an Agent Account grant and its grant_id. You can create the account from the Nylas Dashboard, the Nylas CLI (nylas agent account create), or the API (POST /v3/connect/custom with "provider": "nylas"). See Provisioning Agent Accounts for the full walkthrough.

Set an app password

A mail client signs in to an Agent Account with the account’s email address as the username and an app password as the password. This password is required for protocol access: until you set one, Nylas rejects every IMAP LOGIN and SMTP AUTH attempt. Set it before you hand connection details to a client. The password must be 18 to 40 characters and meet the complexity rules below.

Password requirements

All of the following must be true:

18 to 40 characters long.
Printable ASCII only (character codes 33–126). No spaces or control characters.
At least one uppercase letter (A–Z).
At least one lowercase letter (a–z).
At least one digit (0–9).

Nylas validates the password on write and stores it as a bcrypt hash. You can’t retrieve it afterwards, only reset it.

Set the password

You can set the app password three ways. The Dashboard and CLI set it when you create the account; the API sets it either at creation or on an account that already exists.

Dashboard. Open the Agent Account in the Nylas Dashboard and set its app password from the account’s settings.

CLI. Pass --app-password when you create the account with the Nylas CLI:

nylas agent account create [email protected] --app-password "MySecureP4ssword!2024"

API, at creation. Include app_password in settings on POST /v3/connect/custom:

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]",
      "app_password": "MySecureP4ssword!2024"
    }
  }'

API, on an existing account. Set or rotate the password with PATCH /v3/grants/{grant_id}. A PATCH replaces the entire settings object, so send the account’s email alongside the new app_password:

curl --request PATCH \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "settings": {
      "email": "[email protected]",
      "app_password": "MySecureP4ssword!2024"
    }
  }'

Rotating the password disconnects any active IMAP or SMTP client; each one reconnects after the user supplies the new value.

Connect your mail client

Use the Agent Account’s email address as the username and the app_password as the password. Point the client at the Nylas IMAP and SMTP servers for your region.

Setting	Value
IMAP server	`mail.us.nylas.email` (US) · `mail.eu.nylas.email` (EU)
IMAP port	`993` (implicit TLS)
SMTP server	`mail.us.nylas.email` (US) · `mail.eu.nylas.email` (EU)
SMTP port	`465` (implicit TLS) or `587` (STARTTLS)
Username	The Agent Account email (e.g., `[email protected]`)
Password	The `app_password` you set on the grant
Encryption	TLS required on all ports

Most mail clients auto-detect SSL/TLS. If yours asks, pick “SSL/TLS” for ports 993 and 465, and “STARTTLS” for port 587.

What syncs between IMAP and the API

IMAP and the API operate on one mailbox. Every user-visible action flows through the same storage and fires the same webhooks, regardless of which surface initiated it.

Action	Visible in	Webhook fires
New inbound message arrives	API + IMAP (via IDLE push)	`message.created`
Mark read/unread via IMAP STORE	API `unread` field	`message.updated`
Star via IMAP STORE	API `starred` field	`message.updated`
Move message via IMAP	API `folders` field	`message.updated`
Delete via IMAP EXPUNGE	API (message moved to trash)	`message.updated`
Send via SMTP submission	API + IMAP Sent folder	`message.created`
Send via API	IMAP Sent folder	`message.created`
Create folder via IMAP	API `GET /folders`	`folder.created`
Update message via API	IMAP (flags update, IDLE push)	`message.updated`

IMAP APPEND deduplicates on the MIME Message-ID header. If a message with the same Message-ID already exists in the mailbox (for example, because it was just sent via SMTP submission), APPEND won’t create a duplicate.

Folder mapping

Agent Accounts expose six system folders plus any custom folders you create. IMAP advertises the SPECIAL-USE attributes so mail clients can pick the right folder automatically.

IMAP mailbox	API folder ID	SPECIAL-USE attribute
`INBOX`	`inbox`	`\Inbox`
`Sent`	`sent`	`\Sent`
`Drafts`	`drafts`	`\Drafts`
`Trash`	`trash`	`\Trash`
`Junk`	`junk`	`\Junk`
`Archive`	`archive`	`\Archive`

Custom folders created via POST /v3/grants/{grant_id}/folders appear as additional IMAP mailboxes, and folders created via IMAP appear in the API response.

Limits and server behavior

A few server-side limits apply to protocol access. The outbound size cap is enforced at SMTP submission; the rest govern IMAP connections.

Limit	Default	Notes
Max outbound message size	25 MB	Enforced at the SMTP `DATA` command on submission. Messages over the limit are rejected with an error naming the maximum size.
Max concurrent IMAP connections per grant	20	Configurable per deployment.
IDLE timeout	30 minutes	The server sends a response and the client re-issues IDLE.
Connection timeout	5 minutes	Applies to idle TCP connections outside of IDLE.
Storage quota	Per-grant	Reported via the IMAP `QUOTA` extension.

Keep in mind

IMAP and the API share state. Changes through either surface are durable and trigger webhooks, so your application can integrate with both at once without conflict.
Clients stay live with IDLE. Nylas supports IMAP IDLE so mail clients see new messages without polling.
Rotating the password disconnects clients. Active sessions fail on their next authenticated command and reconnect when the user supplies the new password.
SMTP submission and the API send through the same pipeline. Both deliver over the same outbound path and fire the same message.created notification, so there’s no deliverability reason to prefer one.

What’s next

Agent Accounts quickstart for an end-to-end setup using the API
Provisioning Agent Accounts to create Agent Accounts on a registered domain
Policies, Rules, and Lists to configure limits, spam, and inbound filtering
BYO Auth reference for the nylas provider for every setting accepted on the grant, including app_password
Webhooks to receive notifications when IMAP and SMTP clients change the mailbox