Account status

Every account has a status:

Status	Meaning	What to do
`running`	Connected and syncing	Nothing
`errored`	Syncing keeps failing for a reason other than credentials (server down, network)	The engine retries by itself (30 s to 15 min apart). Look at `status_detail` if it lasts
`disconnected`	The provider rejected the credentials: password changed or app password revoked. Or the account is paused	Ask the user for the new password and send it with the account’s `account_id` (reconnect), or use Update connection on the account’s page in the dashboard. If `is_locked` is `true`, resume it from the dashboard instead

Three more fields help:

Field
`status_detail`	The last error message, for example `invalid_grant: Token has been expired or revoked.` Empty when all is well
`is_locked`	`true` when the account is paused from the dashboard. A paused account doesn’t sync, and its status is `disconnected`
`initial_sync`	Only on accounts connected with initial sync: the import of existing mail, `{ status, started_at, completed_at, days, imported }`. `status` is `pending`, `running`, `completed` or `failed`. Absent on other accounts

Get notified

Subscribe a webhook endpoint to the status events. Each one is sent when the status changes:

Event	Sent when the status becomes
`account.status.running`	`running`
`account.status.errored`	`errored`
`account.status.disconnected`	`disconnected`

account.status.disconnected

{
  "object": "Event",
  "id": "evt_2b3c4d5e6f7a48b9c0d1e2f3a4b5c6d7",
  "type": "account.status.disconnected",
  "created_at": "2026-10-06T11:02:16Z",
  "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
  "endpoint_id": "we_e3f1a2b4c5d64e7f8a9b0c1d2e3f4a5b",
  "data": {
    "status": "disconnected",
    "previous_status": "running",
    "status_detail": "invalid_grant: Token has been expired or revoked."
  }
}

After the user reconnects, you receive account.reconnect with the account, and account.status.running because it’s running again. See Events.

Accounts API

Request	What it does
`GET /api/v1/accounts`	All accounts, newest first. Paged with `offset` and `limit` (pagination)
`GET /api/v1/accounts/{acc_id}`	One account
`PATCH /api/v1/accounts/{acc_id}`	Set your own `metadata` (below)
`POST /api/v1/accounts/{acc_id}/sync`	Check the mailbox now. An `errored` account is retried at once
`DELETE /api/v1/accounts/{acc_id}`	Disconnect the mailbox; its emails disappear from the API

To change an account’s settings (for example a new app password), see Reconnect or change settings.

Find accounts

string

running, errored or disconnected.

string

imap.

string

Part of the name or address, or an exact acc_… id.

integer

default:"50"

1 to 250.

integer

default:"0"

How many accounts to skip.

curl "$EE_URL/api/v1/accounts?status=disconnected" -H "X-API-KEY: $EE_KEY"

Response

{ "object": "Accounts", "data": [ { "object": "Account", "id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99", "status": "disconnected", "…": "…" } ], "has_more": false }

Save your own data

metadata holds your own key-value data, for example the user’s id in your app. Values must be strings. The object you send replaces the current metadata.

curl -X PATCH "$EE_URL/api/v1/accounts/acc_ba1fa6938d8548298e8ce62e4b4b4e99" \
  -H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
  -d '{ "metadata": { "crm_id": "42", "team": "sales" } }'

The response is the updated account.

Sync now

curl -X POST "$EE_URL/api/v1/accounts/acc_ba1fa6938d8548298e8ce62e4b4b4e99/sync" -H "X-API-KEY: $EE_KEY"

Response

{ "object": "AccountSyncRequested", "id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99" }

The sync runs in the background. You rarely need it: IMAP Inboxes (Gmail included) are watched all the time, and other folders are checked every 30 seconds.

Remove an account

curl -X DELETE "$EE_URL/api/v1/accounts/acc_ba1fa6938d8548298e8ce62e4b4b4e99" -H "X-API-KEY: $EE_KEY"

Response

{ "object": "AccountDeleted", "id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99" }

The engine stops syncing the mailbox, and its emails, folders and attachments disappear from the API. An account.remove event is sent. Nothing is deleted in the user’s real mailbox.

The account object

{
  "object": "Account",
  "id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
  "user_id": "ana@acme.com",
  "name": "ana@acme.com",
  "provider": "imap",
  "status": "running",
  "status_detail": "",
  "is_locked": false,
  "metadata": { "crm_id": "42" },
  "connection_params": {
    "mail": {
      "imap_host": "imap.acme.com", "imap_port": 993, "imap_user": "ana@acme.com", "imap_encryption": "SSL",
      "smtp_host": "smtp.acme.com", "smtp_port": 465, "smtp_user": "ana@acme.com", "smtp_encryption": "SSL"
    }
  },
  "created_at": "2026-10-01T08:00:00Z",
  "last_synced_at": "2026-10-06T09:15:02Z"
}

Field
`id`	The account’s `acc_…` id
`user_id`	The mailbox’s email address
`name`	A display name. The address, unless you set one when connecting an IMAP mailbox
`provider`	`imap` (Gmail and every other provider)
`status`, `status_detail`, `is_locked`, `initial_sync`	See above
`metadata`	Your own key-value data
`connection_params.mail`	The server settings (`imap_host`, `imap_port`, `imap_user`, `imap_encryption`, `smtp_host`, …)
`created_at`	When it was connected
`last_synced_at`	The last successful sync, or `null`

Passwords and tokens are never returned.

Getting started

Accounts

Emails

Webhooks

Reference

Get notified

Accounts API

Find accounts

Save your own data

Sync now

Remove an account

The account object

​Get notified

​Accounts API

​Find accounts

​Save your own data

​Sync now

​Remove an account

​The account object

Get notified

Accounts API

Find accounts

Save your own data

Sync now

Remove an account

The account object