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

# Event

> Every call to your endpoint carries one event in this envelope. `data` depends on `type`:

| `type` | `data` |
|---|---|
| `email.new`, `email.new.bounce`, `email.update`, `email.delete`, `email.draft.new`, `email.draft.delete` | `{ "email": Email }` |
| `email.folder.create`, `email.folder.update`, `email.folder.delete` | `{ "folder": Folder }` |
| `tracking.open`, `tracking.click` | `{ tracking_id, label, message_id, email_id, date, ip, user_agent, url }` (`url` on clicks) |
| `account.add`, `account.reconnect` | `{ "account": Account, "state": "…" }` |
| `account.remove` | `{ "account": { id, user_id, name, provider } }` |
| `account.status.running`, `.errored`, `.disconnected` | `{ status, previous_status, status_detail }` |
| `account.initial_sync.running`, `.completed`, `.failed` | `{ "initial_sync": InitialSync }` |

Headers: `X-Email-Engine-Signature` (`sha256=` + hex HMAC-SHA256 of the raw body, keyed
with the endpoint's secret), `X-Email-Engine-Event` (the type), `X-Email-Engine-Delivery`
(the same on every retry).




## OpenAPI

````yaml /api-reference/openapi.yaml webhook event
openapi: 3.1.0
info:
  title: PigeonPost API
  version: 1.0.0
  description: >
    Connect your users' mailboxes (Gmail with an app password, and any IMAP/SMTP
    provider), read, send and manage their email, and

    receive webhooks when something changes. The API follows Unipile's v2
    conventions (ids, lists,

    events); its own version is v1.


    **Authentication:** every request needs your access token in the `X-API-KEY`
    header. Create

    tokens in your dashboard under **API keys**, or with `POST
    /api/v1/api-keys`.


    **Base URL:** `https://{your DSN}/api/v1`. Your DSN is shown in your
    dashboard.


    **Ids** carry their type: `acc_…` (account), `email_…`, `att_…`
    (attachment), `fld_…`

    (folder), `drf_…` (draft), `we_…` (webhook endpoint), `evt_…` (event),
    `pk_…` (API key).


    **Lists** are `{ "object": "<Plural>", "data": [...], "has_more": true|false
    }`. Accounts,

    webhook endpoints, conversations and API keys page with `offset` and
    `limit`. Emails, drafts

    and contacts page with a `cursor`: pass the `cursor` of a response back to
    get the next page.


    **Errors** always have the same JSON shape: `status`, `type`, `title`,
    `detail`.
servers:
  - url: https://{dsn}/api/v1
    description: Your workspace's DSN, from your dashboard
    variables:
      dsn:
        default: mail-api.example.com
        description: Your DSN, for example mail-api.example.com
security:
  - apiKey: []
tags:
  - name: Auth
    description: Connect a mailbox from your app (IMAP/SMTP).
  - name: Accounts
    description: The mailboxes connected to your workspace.
  - name: Emails
    description: Read, search, send, change and delete emails.
  - name: Attachments
    description: Download the files attached to an email.
  - name: Drafts
    description: Drafts saved in the user's mailbox.
  - name: Folders
    description: Folders (Gmail labels appear as folders over IMAP).
  - name: Contacts
    description: The people an account has emailed with.
  - name: Webhooks
    description: Get notified when something happens in a mailbox.
  - name: API keys
    description: Access tokens for this API.
paths: {}
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Your access token, from your dashboard under **API keys**.

````

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