# Connect mail clients to an Agent Account

Source: https://developer.nylas.com/docs/v3/agent-accounts/mail-clients/

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.

> **Info:** 
> **New to Agent Accounts?** Start with the [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) to create your first account. Come back here once you have a `grant_id` and want to enable protocol access on it.

## Before you begin

You need an Agent Account grant and its `grant_id`. You can create the account from the [Nylas Dashboard](https://dashboard-v3.nylas.com/), the [Nylas CLI](/docs/v3/getting-started/cli/) (`nylas agent account create`), or the API ([`POST /v3/connect/custom`](/docs/reference/api/manage-grants/byo_auth/) with `"provider": "nylas"`). See [Provisioning Agent Accounts](/docs/v3/agent-accounts/provisioning/) 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](https://dashboard-v3.nylas.com/) and set its app password from the account's settings.

**CLI.** Pass `--app-password` when you create the account with the [Nylas CLI](/docs/v3/getting-started/cli/):

```bash
nylas agent account create agent@yourdomain.com --app-password "MySecureP4ssword!2024"
```

**API, at creation.** Include `app_password` in `settings` on [`POST /v3/connect/custom`](/docs/reference/api/manage-grants/byo_auth/):

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

**API, on an existing account.** Set or rotate the password with [`PATCH /v3/grants/{grant_id}`](/docs/reference/api/manage-grants/patch_grant_by_id/). A `PATCH` replaces the entire `settings` object, so send the account's `email` alongside the new `app_password`:

```bash
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": "agent@yourdomain.com",
      "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., `agent@yourdomain.com`)        |
| 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`](/docs/reference/api/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](/docs/v3/getting-started/agent-accounts/) for an end-to-end setup using the API
- [Provisioning Agent Accounts](/docs/v3/agent-accounts/provisioning/) to create Agent Accounts on a registered domain
- [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) to configure limits, spam, and inbound filtering
- [BYO Auth reference for the `nylas` provider](/docs/reference/api/manage-grants/byo_auth/) for every setting accepted on the grant, including `app_password`
- [Webhooks](/docs/v3/notifications/) to receive notifications when IMAP and SMTP clients change the mailbox