> ## Documentation Index
> Fetch the complete documentation index at: https://pigeonpost-developer.27communication.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect a mailbox
> Connect Gmail and any other IMAP and SMTP mailbox from your app with the API, or from the dashboard.
Connect any mailbox that offers IMAP and SMTP (Gmail, Yahoo, iCloud, Zoho, hosting providers, company mail servers) with `POST /api/v1/auth/intent`. Your app shows its own form, collects the address and password, and sends them to the engine. To connect a mailbox without code, for example to test, use the [dashboard](#from-the-dashboard).
For **well-known providers you only need the address and password**: the servers are filled in for you ([below](#common-providers)). For Gmail, see the step-by-step [Gmail guide](/accounts/gmail).
The engine checks the settings against both servers **before** saving the account, so a wrong password or host fails right away, and nothing is stored.
## Request
```bash Flat fields theme={null}
curl -X POST "$EE_URL/api/v1/auth/intent" \
-H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
-d '{
"provider": "imap",
"email": "ana@fastmail.com",
"name": "Ana Lee",
"imap_host": "imap.fastmail.com", "imap_port": 993, "imap_password": "app-password-here",
"smtp_host": "smtp.fastmail.com", "smtp_port": 465,
"state": "user-42"
}'
```
```bash Nested settings theme={null}
curl -X POST "$EE_URL/api/v1/auth/intent" \
-H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
-d '{
"provider": "imap",
"email": "ana@fastmail.com", "password": "app-password-here",
"connection_params": { "imap_host": "imap.fastmail.com", "imap_port": 993, "smtp_host": "smtp.fastmail.com", "smtp_port": 587 }
}'
```
`imap`.
The mailbox address. Defaults to `imap_user` when omitted.
One password for both servers. `imap_password` and `smtp_password` override it.
Top level, or inside `connection_params` (top-level values win). `imap_host` is required, except for the [providers filled in automatically](#common-providers). `imap_user` defaults to `email`.
`smtp_host` is required, except for the [providers filled in automatically](#common-providers). `smtp_user` and `smtp_password` default to the IMAP ones.
Copy sent mail into the Sent folder. Turn it off for servers that do it themselves. For `smtp.gmail.com` it's off by default.
A display name for the account. Defaults to the address.
Your own value, sent back in the `account.add` event.
An `acc_…` id, to [change the settings](#reconnect-or-change-settings) of an existing IMAP account instead.
`{ "initial_sync_enable": true, "initial_sync_days": 30 }` imports the mail already in the mailbox: the last 1 to 30 days (default and maximum 30), without `email.new` events. See [Initial sync](/accounts/initial-sync). Without it, only new mail is synced.
### Encryption
`imap_encryption` and `smtp_encryption` take `SSL`, `STARTTLS` or `NONE`. When omitted, the engine uses the standard one for the port:
| Port | Encryption |
| - | - |
| IMAP 993, SMTP 465 | `SSL` |
| IMAP 143, SMTP 587 / 25 | `STARTTLS` |
## Response
```json 201 Created theme={null}
{
"object": "Account",
"id": "acc_3c9e4f1a7b2d4e8f9a6c1d2e3f4a5b6c",
"user_id": "ana@fastmail.com",
"name": "Ana Lee",
"provider": "imap",
"status": "running",
"status_detail": "",
"is_locked": false,
"metadata": {},
"connection_params": {
"mail": {
"imap_host": "imap.fastmail.com", "imap_port": 993, "imap_user": "ana@fastmail.com", "imap_encryption": "SSL",
"smtp_host": "smtp.fastmail.com", "smtp_port": 465, "smtp_user": "ana@fastmail.com", "smtp_encryption": "SSL"
}
},
"created_at": "2026-10-06T09:20:00Z",
"last_synced_at": null
}
```
The account is connected at once, and an `account.add` event is sent with your `state`. Passwords are never returned. With `config.initial_sync_enable`, the account also has an `initial_sync` object (`"status": "pending"`) and the import starts within seconds: see [Initial sync](/accounts/initial-sync).
| Error | When |
| - | - |
| `401 errors/invalid_credentials` | The server rejected the username or password |
| `409 errors/already_exists` | This mailbox is already connected |
| `400 errors/invalid_parameters` | A required setting is missing or invalid |
| `502 errors/provider_error` | The server couldn't be reached |
## Common providers
For these addresses you can **leave the servers out**: the engine fills them in from the domain. Most of them need an **app password**, because the account's normal password is refused.
| Provider | Domains | IMAP | SMTP | Password |
| - | - | - | - | - |
| [Gmail](/accounts/gmail) | `gmail.com`, `googlemail.com` | `imap.gmail.com:993` SSL | `smtp.gmail.com:465` SSL | App password (2-Step Verification) |
| Yahoo Mail | `yahoo.com`, `ymail.com`, `rocketmail.com`, `yahoo.co.uk`, … | `imap.mail.yahoo.com:993` SSL | `smtp.mail.yahoo.com:465` SSL | App password |
| iCloud Mail | `icloud.com`, `me.com`, `mac.com` | `imap.mail.me.com:993` SSL | `smtp.mail.me.com:587` STARTTLS | App-specific password |
| AOL Mail | `aol.com` | `imap.aol.com:993` SSL | `smtp.aol.com:465` SSL | App password |
| Zoho Mail | `zoho.com`, `zohomail.com` | `imap.zoho.com:993` SSL | `smtp.zoho.com:465` SSL | IMAP turned on in Zoho; app password with two-factor sign-in |
| GMX | `gmx.com`, `gmx.net`, `gmx.de` | `imap.gmx.com:993` SSL | `mail.gmx.com:587` STARTTLS | IMAP turned on in GMX settings |
| Fastmail | `fastmail.com`, `fastmail.fm` | `imap.fastmail.com:993` SSL | `smtp.fastmail.com:465` SSL | App password |
**Google Workspace** (Gmail on a company domain) and other custom domains aren't recognised from the address: pass the servers, for example `imap.gmail.com` / `smtp.gmail.com` for Workspace.
When a known provider rejects the password, the `401 errors/invalid_credentials` detail says what that provider needs, for example: "Gmail needs an app password: turn on 2-Step Verification, then create one at [https://myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords) …".
Outlook.com, Hotmail and Live addresses are refused with `400`: Microsoft doesn't allow password sign-in for them. They can't be connected yet.
## Reconnect or change settings
To change the password or servers of an account, send the same request with the account's `account_id`:
```bash theme={null}
curl -X POST "$EE_URL/api/v1/auth/intent" \
-H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
-d '{
"provider": "imap",
"account_id": "acc_3c9e4f1a7b2d4e8f9a6c1d2e3f4a5b6c",
"email": "ana@fastmail.com",
"imap_host": "imap.fastmail.com", "imap_password": "new-app-password",
"smtp_host": "smtp.fastmail.com"
}'
```
The new settings are checked, then saved. The response is the account (`200`), it keeps its id and its emails, and an `account.reconnect` event is sent.
Use this to **reconnect** an account whose status is `disconnected`, for example after the user changed their password or revoked the app password. See [Account status](/accounts/status).
## From the dashboard
A workspace admin can also connect a mailbox in the dashboard, without code:
1. Open **Accounts → Add account**.
2. Enter the email address and the password (an app password for Gmail, Yahoo, iCloud and AOL).
3. For providers that aren't [filled in automatically](#common-providers), open the server settings and enter the IMAP and SMTP servers.
4. Optionally, turn on [initial sync](/accounts/initial-sync) to import recent mail.
The engine checks the settings the same way as the API. To give an account a new password or new settings, open the account's page and click **Update connection**.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.