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 end users (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 end user without giving up the API automation layered on top.

Before you begin

You need:

An Agent Account grant, created via POST /v3/connect/custom with "provider": "nylas". See Provisioning and domains.
An app_password set on the grant — the credential mail clients use for IMAP LOGIN and SMTP AUTH. Without it, both protocols reject authentication.

Set an app password

The app_password is an optional setting on the grant. You set it either at creation time or by updating settings.app_password later. Nylas validates it on write and stores a bcrypt hash — you can’t retrieve it afterwards, only reset it.

App 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).

Set it at grant creation

From the Nylas CLI:

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

Or through the API:

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"
    }
  }'

Rotate or add it later

Update the grant’s settings.app_password to change or reset the password. Any active IMAP or SMTP client needs to reauthenticate with 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 port 993 and 465, and “STARTTLS” for port 587.

What syncs bidirectionally

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.

SMTP submission

SMTP submission uses the same credentials as IMAP. Both ports accept the full MIME message; Nylas preserves the original Message-ID, In-Reply-To, and References headers so that replies thread correctly for the recipient.

Port	Encryption	When to use
`465`	Implicit TLS (SMTPS). The connection starts encrypted.	Most modern clients — simpler, no STARTTLS negotiation.
`587`	STARTTLS. The connection starts plaintext and upgrades to TLS.	Clients that only support the submission port with STARTTLS.

A message sent via SMTP submission lands in the Agent Account’s Sent folder and fires a message.created webhook, identical to a message sent with POST /v3/grants/{grant_id}/messages/send.

Limits and server behavior

Limit	Default	Notes
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.

If app_password isn’t set on the grant, both IMAP and SMTP submission reject authentication with a clear error — set or reset the password through the API to unlock access.

Keep in mind

IMAP and the API share state. Changes through either surface are durable and trigger webhooks. 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 path. There’s no need to pick one for deliverability — both use the same outbound pipeline and trigger the same notifications.

What’s next

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