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

# Core concepts

> Accounts, emails, folders, threads, ids, lists and events.

## Account

An **account** is one connected mailbox, such as `ana@example.com`. It has a provider, a status, and everything the engine synced from it.

| `provider` | Mailbox |
| - | - |
| `imap` | Gmail, Google Workspace and every other provider, through IMAP and SMTP |

The account's `status` tells you whether it's syncing (`running`) or needs attention (`errored`, `disconnected`). See [Account status](/accounts/status).

## Email

An **email** is one message in an account, as the engine synced it: sender, recipients, subject, HTML and text bodies, folders, flags and attachments. See [Retrieve an email](/emails/retrieve) for every field.

The engine syncs **from the moment the account connects**: every new email and every change (read, starred, moved, deleted). Mail that was already in the mailbox isn't imported, unless you turn on [initial sync](/accounts/initial-sync) when connecting: it imports the last 30 days at most.

## Folder and role

**Folders** are the mailbox's folders (Gmail's labels appear as folders over IMAP). Each has a **role** when it has a standard purpose, so you can work across providers without knowing their folder names:

| Role | Gmail (IMAP) | Other IMAP |
| - | - | - |
| `INBOX` | INBOX | INBOX |
| `SENT` | \[Gmail]/Sent Mail | Sent |
| `DRAFTS` | \[Gmail]/Drafts | Drafts |
| `TRASH` | \[Gmail]/Trash | Trash |
| `SPAM` | \[Gmail]/Spam | Junk / Spam |
| `ARCHIVE` | — | Archive |

Anywhere the API takes a folder, you can pass its `fld_…` id, its provider id, or a role such as `INBOX`.

## Ids

Every id the engine creates starts with its type, so you can't mix them up:

| Prefix | Type | Example |
| - | - | - |
| `acc_` | Account | `acc_ba1fa6938d8548298e8ce62e4b4b4e99` |
| `email_` | Email | `email_94a0d77db739407e932c3b97fef44aac` |
| `att_` | Attachment | `att_6f2e8c1a0d4b4f7e9a512c3b8d7e1f00` |
| `fld_` | Folder | `fld_0b7e2d4c1a3f4e5b8c9d7f6e5d4c3b2a` |
| `drf_` | Draft (`drf_` plus the provider's draft id) | `drf_r-4419383208612875012` |
| `trk_` | Open and click tracking | `trk_5d0c3e2f1a4b4c6d8e7f9a0b1c2d3e4f` |
| `we_` | Webhook endpoint | `we_e3f1a2b4c5d64e7f8a9b0c1d2e3f4a5b` |
| `evt_` | Webhook event | `evt_7c1d2e3f4a5b46c7d8e9f0a1b2c3d4e5` |
| `whc_` | Webhook call (conversation) | `whc_5a6b7c8d9e0f41a2b3c4d5e6f7a8b9c0` |
| `pk_` | API key | `pk_0f1e2d3c4b5a69788796a5b4c3d2e1f0` |

Always pass ids exactly as the API returns them. An id with the wrong prefix, or a plain UUID, is refused: in the URL path you get `404`, in a query or body you get `400`.

An email also has ids that come from its provider:

| Field | What it is |
| - | - |
| `id` | The engine's `email_…` id. Stable: it stays the same when an email moves. Use it in API calls. |
| `provider_id` | The provider's own id: IMAP `uidvalidity:uid:folder`. |
| `message_id` | The `Message-ID` header: the same in every mailbox that has the email. |
| `thread_id` | The conversation: the first `Message-ID` of the thread. |

## Lists

Every list has the same shape:

```json theme={null}
{ "object": "Emails", "data": [ … ], "has_more": true, "cursor": "eyJkIjoi…" }
```

`object` names the list (`Accounts`, `Emails`, `Folders` …), `data` holds the items and `has_more` says whether there is a next page. See [Pagination](/reference/pagination).

## Attendee

Senders and recipients are **attendees**:

```json theme={null}
{ "display_name": "Ana Lee", "identifier": "ana@example.com" }
```

`identifier` is the email address, always lowercase.

## Events

When something changes, the engine sends a **webhook event** to your app, for example `email.new`, `email.update` or `account.status.disconnected`. See [Events](/webhooks/events).


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