# PigeonPost

> One API for Gmail and IMAP mailboxes: connect accounts, sync, read, send, and get webhooks for new mail.

- [Introduction](https://pigeonpost-developer.27communication.com/index.md): One API for Gmail and IMAP mailboxes.
- [Quickstart](https://pigeonpost-developer.27communication.com/quickstart.md): Create your account, get your DSN and access token, and make your first calls.
- [Authentication](https://pigeonpost-developer.27communication.com/authentication.md): Your DSN, access tokens, API keys, and which endpoints are public.
- [Core concepts](https://pigeonpost-developer.27communication.com/concepts.md): Accounts, emails, folders, threads, ids, lists and events.
- [Connect a mailbox](https://pigeonpost-developer.27communication.com/accounts/imap.md): Connect Gmail and any other IMAP and SMTP mailbox from your app with the API, or from the dashboard.
- [Gmail and Google Workspace (IMAP)](https://pigeonpost-developer.27communication.com/accounts/gmail.md): Connect Gmail and Google Workspace mailboxes over IMAP and SMTP with an app password: what the user needs, how to connect, Gmail's behaviour and limits, and troubleshooting.
- [Initial sync (import existing mail)](https://pigeonpost-developer.27communication.com/accounts/initial-sync.md): Import up to the last 30 days of mail already in a mailbox when it connects, without email.new webhooks.
- [Account status](https://pigeonpost-developer.27communication.com/accounts/status.md): Know when a mailbox is syncing, and what to do when it isn't.
- [List emails](https://pigeonpost-developer.27communication.com/emails/list.md): Search and page through synced emails across accounts and folders.
- [Retrieve an email](https://pigeonpost-developer.27communication.com/emails/retrieve.md): Get one email and every field of the email object.
- [Send an email](https://pigeonpost-developer.27communication.com/emails/send.md): Send from the user's own mailbox, with attachments, custom headers and tracking.
- [Replies and threads](https://pigeonpost-developer.27communication.com/emails/replies-and-threads.md): Answer emails so they stay in the same conversation.
- [Drafts](https://pigeonpost-developer.27communication.com/emails/drafts.md): Save drafts in the user's mailbox, edit them, and send them later.
- [Read, star, move and trash](https://pigeonpost-developer.27communication.com/emails/update.md): Change an email in the user's mailbox.
- [Attachments](https://pigeonpost-developer.27communication.com/emails/attachments.md): Find, download and send email attachments, and show inline images.
- [Folders](https://pigeonpost-developer.27communication.com/emails/folders.md): List a mailbox's folders (Gmail labels appear as folders).
- [Contacts](https://pigeonpost-developer.27communication.com/emails/contacts.md): The people an account has emailed with.
- [Open and click tracking](https://pigeonpost-developer.27communication.com/emails/tracking.md): Know when a sent email is opened or one of its links is clicked.
- [Webhooks](https://pigeonpost-developer.27communication.com/webhooks/overview.md): Get told about new mail and changes the moment they happen.
- [Events](https://pigeonpost-developer.27communication.com/webhooks/events.md): Every event the engine sends, and what's in it.
- [Verify signatures](https://pigeonpost-developer.27communication.com/webhooks/signatures.md): Check that a webhook call really came from your engine.
- [Retries and delivery](https://pigeonpost-developer.27communication.com/webhooks/retries.md): What happens when your endpoint is down.
- [Errors](https://pigeonpost-developer.27communication.com/reference/errors.md): Error responses and what to do about them.
- [Pagination](https://pigeonpost-developer.27communication.com/reference/pagination.md): Page through long lists with an offset or a cursor.
- [Unipile compatibility](https://pigeonpost-developer.27communication.com/reference/unipile-compatibility.md): What matches Unipile's API v2, and what's different.
- [Start an auth intent](https://pigeonpost-developer.27communication.com/api-reference/auth/start-an-auth-intent.md): 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.
- [List accounts](https://pigeonpost-developer.27communication.com/api-reference/accounts/list-accounts.md): Returns the connected accounts, **newest first**, paged with `offset` and `limit`.
- [Get an account](https://pigeonpost-developer.27communication.com/api-reference/accounts/get-an-account.md): Returns one account: its address, provider, status, metadata and connection settings. Passwords and tokens are never returned.
- [Remove an account](https://pigeonpost-developer.27communication.com/api-reference/accounts/remove-an-account.md): Disconnects the mailbox. The engine stops syncing it, its emails, folders and attachments disappear from the API, and an `account.remove` event is sent. Nothing is deleted in the user's real mailbox.
- [Update an account](https://pigeonpost-developer.27communication.com/api-reference/accounts/update-an-account.md): Sets your own key-value `metadata` on the account, for example the user's id in your app. The object you send **replaces** the current metadata. Values must be strings.
- [Sync an account now](https://pigeonpost-developer.27communication.com/api-reference/accounts/sync-an-account-now.md): Asks the engine to check the mailbox right away instead of waiting for the next automatic check. Returns at once; the sync runs in the background. An `errored` account is retried now. You rarely need this: Inboxes are watched continuously (IMAP IDLE) and other folders are checked every 30 seconds.
- [List emails](https://pigeonpost-developer.27communication.com/api-reference/emails/list-emails.md): Returns emails, **newest first** (by the email's `date`), with optional filters. All filters can be combined: `account_id=…&folder=INBOX&unread=true` returns the unread emails of one account's inbox.
- [Send an email](https://pigeonpost-developer.27communication.com/api-reference/emails/send-an-email.md): Sends an email from the account's own address, through the provider's SMTP server. It appears in the user's **Sent** folder (an `email.new` event follows, with `origin: "api"`).
- [Get an email](https://pigeonpost-developer.27communication.com/api-reference/emails/get-an-email.md): Returns one email with its body, recipients, folders and attachments.
- [Move an email to trash](https://pigeonpost-developer.27communication.com/api-reference/emails/move-an-email-to-trash.md): Moves the email to **Trash**, like the delete button in an email app. It stays in the API with `role: "TRASH"` until the provider empties the trash; then `email.delete` is sent.
- [Update an email](https://pigeonpost-developer.27communication.com/api-reference/emails/update-an-email.md): Marks an email read or unread, stars it, or moves it to another folder, **in the user's real mailbox**. Send only what you want to change. Returns the updated email, which keeps its `id`. An `email.update` event follows.
- [Download an attachment](https://pigeonpost-developer.27communication.com/api-reference/attachments/download-an-attachment.md): Returns **the file itself** (binary). `Content-Type` is the file type and `Content-Disposition` has the original file name. Files are served from your workspace's storage once copied (seconds after the email arrives), otherwise fetched from the provider.
- [List drafts](https://pigeonpost-developer.27communication.com/api-reference/drafts/list-drafts.md): Drafts in the users' Drafts folders, newest first, paged with a cursor. Each is an email object with `object` "Draft" and a `draft_id`.
- [Create a draft](https://pigeonpost-developer.27communication.com/api-reference/drafts/create-a-draft.md): Saves a draft in the user's Drafts folder. Same fields as **Send an email**; recipients are optional. An `email.draft.new` event follows when it syncs.
- [Get a draft](https://pigeonpost-developer.27communication.com/api-reference/drafts/get-a-draft.md): One draft (an email object with `object` "Draft").
- [Delete a draft](https://pigeonpost-developer.27communication.com/api-reference/drafts/delete-a-draft.md): Deletes the draft from the Drafts folder (`email.draft.delete` follows).
- [Update a draft](https://pigeonpost-developer.27communication.com/api-reference/drafts/update-a-draft.md): The fields you send replace the draft's; the rest is kept. The draft is saved again at the provider, so it gets a **new `draft_id`**.
- [Send a draft](https://pigeonpost-developer.27communication.com/api-reference/drafts/send-a-draft.md): Sends the draft to its recipients. It leaves Drafts and appears in Sent with `origin` "api".
- [List folders](https://pigeonpost-developer.27communication.com/api-reference/folders/list-folders.md): Folders (Gmail labels appear as folders), Inbox first. Not paged (`has_more` is always `false`).
- [Get a folder](https://pigeonpost-developer.27communication.com/api-reference/folders/get-a-folder.md): One folder with its email and unread counts.
- [List contacts](https://pigeonpost-developer.27communication.com/api-reference/contacts/list-contacts.md): The people an account has emailed with (from, to, cc, bcc of synced mail), most recent first; the account's own address is left out.
- [List webhook endpoints](https://pigeonpost-developer.27communication.com/api-reference/webhooks/list-webhook-endpoints.md): Your endpoints, newest first.
- [Create a webhook endpoint](https://pigeonpost-developer.27communication.com/api-reference/webhooks/create-a-webhook-endpoint.md): Registers a URL of your app. The engine sends it a `POST` with the event envelope for every `trigger_events` event. The response contains the endpoint's `secret`: check the `X-Email-Engine-Signature` header (HMAC-SHA256 of the body) with it.
- [Get a webhook endpoint](https://pigeonpost-developer.27communication.com/api-reference/webhooks/get-a-webhook-endpoint.md)
- [Delete a webhook endpoint](https://pigeonpost-developer.27communication.com/api-reference/webhooks/delete-a-webhook-endpoint.md)
- [Update a webhook endpoint](https://pigeonpost-developer.27communication.com/api-reference/webhooks/update-a-webhook-endpoint.md): Send only the fields to change. The endpoint keeps its `id` and `secret`. `enabled` false pauses it (calls waiting to be sent are dropped).
- [List webhook conversations](https://pigeonpost-developer.27communication.com/api-reference/webhooks/list-webhook-conversations.md): The calls made to one endpoint (the delivery log), newest first, with their status, attempts, last HTTP status and error, and the payload.
- [Event](https://pigeonpost-developer.27communication.com/api-reference/webhooks/event.md): Every call to your endpoint carries one event in this envelope. `data` depends on `type`:
- [List API keys](https://pigeonpost-developer.27communication.com/api-reference/api-keys/list-api-keys.md): Your API keys (never the keys themselves).
- [Create an API key](https://pigeonpost-developer.27communication.com/api-reference/api-keys/create-an-api-key.md): Creates an access token. The `key` is in this response **only**; store it safely.
- [Delete an API key](https://pigeonpost-developer.27communication.com/api-reference/api-keys/delete-an-api-key.md): Revokes the key at once.

## OpenAPI Specs

- [openapi](/api-reference/openapi.yaml)


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