# Connect Outlook or Apple Mail to an Agent Account

> Source: <https://dev.to/qasim157/connect-outlook-or-apple-mail-to-an-agent-account-2akf>
> Published: 2026-06-15 14:59:08+00:00

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](https://developer.nylas.com/docs/v3/agent-accounts/mail-clients/) (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.

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.

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

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:

`message.created`

.`unread`

field flips, firing `message.updated`

.`message.created`

— identical to a send through `POST /messages/send`

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

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.

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

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](https://developer.nylas.com/docs/v3/agent-accounts/mail-clients/).