> ## 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.

# Account status

> Know when a mailbox is syncing, and what to do when it isn't.

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](/accounts/imap#reconnect-or-change-settings)), 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](/accounts/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](/webhooks/overview) 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` |

```json account.status.disconnected theme={null}
{
  "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](/webhooks/events#account-events).

## Accounts API

| Request | What it does |
| - | - |
| `GET /api/v1/accounts` | All accounts, newest first. Paged with `offset` and `limit` ([pagination](/reference/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](/accounts/imap#reconnect-or-change-settings).

### Find accounts

<ParamField query="status" type="string">`running`, `errored` or `disconnected`.</ParamField>
<ParamField query="provider" type="string">`imap`.</ParamField>
<ParamField query="search" type="string">Part of the name or address, or an exact `acc_…` id.</ParamField>
<ParamField query="limit" type="integer" default="50">1 to 250.</ParamField>
<ParamField query="offset" type="integer" default="0">How many accounts to skip.</ParamField>

```bash theme={null}
curl "$EE_URL/api/v1/accounts?status=disconnected" -H "X-API-KEY: $EE_KEY"
```

```json Response theme={null}
{ "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.

```bash theme={null}
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

```bash theme={null}
curl -X POST "$EE_URL/api/v1/accounts/acc_ba1fa6938d8548298e8ce62e4b4b4e99/sync" -H "X-API-KEY: $EE_KEY"
```

```json Response theme={null}
{ "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

```bash theme={null}
curl -X DELETE "$EE_URL/api/v1/accounts/acc_ba1fa6938d8548298e8ce62e4b4b4e99" -H "X-API-KEY: $EE_KEY"
```

```json Response theme={null}
{ "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

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.