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 agent@yourdomain.com --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": "agent@yourdomain.com",
      "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:

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:

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:

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

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.