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.

For well-known providers you only need the address and password: the servers are filled in for you (below). For Gmail, see the step-by-step Gmail guide.

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

Flat fields

curl -X POST "$EE_URL/api/v1/auth/intent" \
  -H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
  -d '{
    "provider": "imap",
    "email": "[e-mail]",
    "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"
  }'

provider · string · required

imap.

email · string · required

The mailbox address. Defaults to imap_user when omitted.

password · string

One password for both servers. imap_password and smtp_password override it.

imap_host, imap_port, imap_user, imap_password, imap_encryption · IMAP settings

Top level, or inside connection_params (top-level values win). imap_host is required, except for the providers filled in automatically. imap_user defaults to email.

smtp_host, smtp_port, smtp_user, smtp_password, smtp_encryption · SMTP settings

smtp_host is required, except for the providers filled in automatically. smtp_user and smtp_password default to the IMAP ones.

smtp_save_to_sent · boolean · default: "true"

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.

name · string

A display name for the account. Defaults to the address.

state · string

Your own value, sent back in the account.add event.

account_id · string

An acc_… id, to change the settings of an existing IMAP account instead.

config · object

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

201 Created

{
  "object": "Account",
  "id": "acc_3c9e4f1a7b2d4e8f9a6c1d2e3f4a5b6c",
  "user_id": "[e-mail]",
  "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": "[e-mail]", "imap_encryption": "SSL",
      "smtp_host": "smtp.fastmail.com", "smtp_port": 465, "smtp_user": "[e-mail]", "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.

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

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:

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": "[e-mail]",
    "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.

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, open the server settings and enter the IMAP and SMTP servers.
4. Optionally, turn on 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.