Connect Outlook or Apple Mail to an Agent Account

Before: the only way to see what your AI agent was emailing customers was to query the API and squint at JSON. After: your support lead opens Outlook, and the agent's mailbox sits in the sidebar next to their own — every thread readable, every draft reviewable, replies sendable from the agent's address when a human needs to step in.

That's what protocol-level access gives you. Nylas Agent Accounts (currently in beta) are primarily API-driven mailboxes for agents, but you can also expose any account over IMAP and SMTP submission. The killer detail: IMAP and the API read and write the same mailbox. A flag change, folder move, or delete through either surface shows up on the other within seconds.

Step one: set an app password

Mail clients can't authenticate with your API key, and they shouldn't. Instead, you set an app_password on the grant — the credential clients use for IMAP LOGIN and SMTP AUTH. Without it, both protocols reject authentication entirely, which is a sensible default: protocol access stays off until you opt in.

You can set it at creation time:

nylas agent account create [e-mail] --app-password "MySecureP4ssword!2024"

Or via 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": "[e-mail]",
      "app_password": "MySecureP4ssword!2024"
    }
  }'

The requirements are strict: 18 to 40 characters, printable ASCII only, with at least one uppercase letter, one lowercase letter, and one digit. The password is stored as a bcrypt hash — you can't retrieve it later, only reset it by updating settings.app_password. Rotating it disconnects active clients on their next authenticated command, which doubles as a clean kill switch if a credential leaks.

Step two: point the client at the server

Every mainstream client — Outlook, Apple Mail, Thunderbird — takes the same five fields:

Setting	Value
IMAP server	mail.us.nylas.email (US) or mail.eu.nylas.email (EU)
IMAP port	993 (implicit TLS)
SMTP server	same hosts as IMAP
SMTP port	465 (implicit TLS) or 587 (STARTTLS)
Username / password	the agent's email address / the app_password

TLS is required on every port. The mailbox advertises IMAP SPECIAL-USE attributes, so clients automatically map the six system folders — INBOX, Sent, Drafts, Trash, Junk, Archive — to the right places, and custom folders created through the API appear as additional IMAP mailboxes (and vice versa).

What syncs both ways

This is where the single-mailbox design pays off. Every action flows through the same storage and fires the same webhooks no matter which surface initiated it:

• A new inbound message appears in the API and pushes to mail clients via IMAP IDLE, firing message.created.
• Mark a message read in Apple Mail, and the API's unread field flips, firing message.updated.
• Send from Thunderbird over SMTP, and the message lands in the Sent folder, visible via the API, firing message.created — identical to a send through POST /messages/send.
• Your agent updates a flag via the API, and the change pushes to the open mail client through IDLE.

The full mapping is worth scanning, because it's the part that makes the human-oversight story credible — everything a person does in a client becomes an event your application can observe:

Action	Visible in	Webhook fires
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
Create folder via IMAP	API GET /folders	folder.created
Update message via API	IMAP (flags update, IDLE push)	message.updated

There's even dedup at the protocol layer: IMAP APPEND checks the MIME Message-ID header, so a message just sent over SMTP doesn't get duplicated when the client appends it to Sent. And both send paths use the same outbound pipeline, so there's no deliverability reason to prefer one over the other.

Threading survives the protocol hop too. SMTP submission preserves the original Message-ID, In-Reply-To, and References headers exactly as the client set them — so when a human replies from Thunderbird inside a conversation the agent started over the API, the recipient sees one coherent thread, and so does the agent the next time it fetches it.

465 or 587?

Both SMTP ports take the same credentials and the same full MIME message; they differ only in how the TLS session starts:

Port	Encryption	When to use
465	Implicit TLS — the connection starts encrypted	Most modern clients; simpler, no STARTTLS negotiation
587	STARTTLS — starts plaintext, upgrades to TLS	Clients that only support the submission port with STARTTLS

If your client asks you to choose an encryption mode, pick "SSL/TLS" for ports 993 and 465, and "STARTTLS" for 587.

The server limits you'll actually hit

Limit	Default
Max outbound message size	40 MB, enforced at the SMTP DATA command
Concurrent IMAP connections per grant	20
IDLE timeout	30 minutes (client re-issues IDLE)
Idle connection timeout	5 minutes outside of IDLE
Storage quota	per grant, reported via the IMAP QUOTA extension

The 20-connection cap matters if a whole team supervises one agent mailbox — modern clients open multiple connections each, so five or six simultaneous users can brush against it.

Why this pattern matters for agent oversight

Autonomous email agents need a human escape hatch, and "build a custom review UI" is a tax most teams shouldn't pay on day one. A mail client is a review UI — battle-tested, familiar, and already on everyone's machine. The hybrid workflow the docs describe is exactly this: the agent handles routine messages via the API while a human reviews edge cases or replies from a familiar client, with webhooks keeping your application informed of everything the human does. It's also the fastest debugging tool you'll find — when the agent misfiles a message, you can watch it happen live in Thunderbird.

Try it this week: add an app_password to one existing agent grant, connect Apple Mail or Thunderbird with the settings table above, and move a message between folders from each side. Watching the other surface update in real time makes the shared-mailbox model click. Full details in the mail client access guide.