curl --request POST \
  --url https://{dsn}/api/v1/auth/intent \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "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"
}
'

{
  "$ref": "#/components/examples/ImapAccount/value"
}

{
  "$ref": "#/components/examples/ImapAccount/value"
}

{
  "status": 400,
  "type": "errors/invalid_parameters",
  "title": "Invalid parameters",
  "detail": "limit must be between 1 and 250"
}

{
  "status": 401,
  "type": "errors/invalid_credentials",
  "title": "Invalid credentials",
  "detail": "the mail provider rejected the credentials: invalid_grant"
}

{
  "status": 404,
  "type": "errors/not_found",
  "title": "Not found",
  "detail": "email email_94a0d77db739407e932c3b97fef44aac not found"
}

{
  "status": 409,
  "type": "errors/already_exists",
  "title": "Already exists",
  "detail": "ana@fastmail.com is already connected"
}

Auth

Start an auth intent

Connects a mailbox from your own app: your app collects the email address and password (an app password for Gmail) and sends them here. The server settings are filled in for well-known providers.

provider: "imap" with the IMAP/SMTP settings: the engine signs in to both servers, then connects the account at once and returns it (201). Wrong settings give 401 errors/invalid_credentials and nothing is stored.

Pass account_id to reconnect an existing account instead (200 for IMAP).

By default only email that arrives after connecting is synced. Add config: { "initial_sync_enable": true } to also import the mail already in the mailbox (the last 30 days; initial_sync_days 1 to 30), without email.new events: see the Initial sync guide (/accounts/initial-sync). Encryption, when left out, follows the port: 143, 587 and 25 use STARTTLS, other ports SSL.

POST

auth

intent

curl --request POST \
  --url https://{dsn}/api/v1/auth/intent \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "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"
}
'

{
  "$ref": "#/components/examples/ImapAccount/value"
}

{
  "$ref": "#/components/examples/ImapAccount/value"
}

{
  "status": 400,
  "type": "errors/invalid_parameters",
  "title": "Invalid parameters",
  "detail": "limit must be between 1 and 250"
}

{
  "status": 401,
  "type": "errors/invalid_credentials",
  "title": "Invalid credentials",
  "detail": "the mail provider rejected the credentials: invalid_grant"
}

{
  "status": 404,
  "type": "errors/not_found",
  "title": "Not found",
  "detail": "email email_94a0d77db739407e932c3b97fef44aac not found"
}

{
  "status": 409,
  "type": "errors/already_exists",
  "title": "Already exists",
  "detail": "ana@fastmail.com is already connected"
}

Authorizations

X-API-KEY

string

header

required

Your access token, from your dashboard under API keys.

Body

application/json

provider

enum<string>

required

imap: Gmail, Google Workspace and every other provider through IMAP/SMTP.

Available options:

imap

account_id

string

Reconnect this account.

state

string

Sent back in the redirect and the account.add / account.reconnect event.

string<email>

IMAP: the mailbox's address (defaults to imap_user).

name

string

IMAP: display name.

password

string

IMAP: one password for IMAP and SMTP.

imap_host

string

Filled in from the address for Gmail, Yahoo, iCloud, AOL, Zoho, GMX and Fastmail; otherwise required.

imap_port

integer

993 (SSL) or 143 (STARTTLS).

imap_user

string

imap_password

string

imap_encryption

enum<string>

Available options:

SSL,

STARTTLS,

NONE

smtp_host

string

smtp_port

integer

465 (SSL), 587 (STARTTLS) or 25.

smtp_user

string

smtp_password

string

smtp_encryption

enum<string>

Available options:

SSL,

STARTTLS,

NONE

smtp_save_to_sent

boolean

default:true

connection_params

object

The same IMAP/SMTP settings

config

object

One provider's initial sync settings.

Show child attributes

Response

Reconnect: the account with its new settings.

object

string

Allowed value: "Account"

string

acc_…

user_id

string

The mailbox's email address.

name

string

provider

enum<string>

imap: Gmail, Google Workspace and every other provider through IMAP/SMTP.

Available options:

imap

status

enum<string>

running: connected and syncing.
errored: syncing keeps failing (server down, network); the engine retries by itself.
disconnected: the provider rejected the password or token (reconnect it), or the account is paused in the dashboard (is_locked: true).

Available options:

running,

errored,

disconnected

status_detail

string

The last error message

is_locked

boolean

Paused from the dashboard: not syncing.

initial_sync

object

Only on accounts connected with initial_sync_enable: true: the import of the mail already in the mailbox.

Show child attributes

metadata

object

Your own key-value data.

Show child attributes

connection_params

object

Connection settings, never passwords.

created_at

string<date-time>

last_synced_at

string<date-time> | null

Auth

Accounts

Emails

Attachments

Drafts

Folders

Contacts

Webhooks

API keys

Start an auth intent

Authorizations

Body

Response