> ## 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. # Start an auth intent > 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. - **`provider: "imap"`** with the IMAP/SMTP settings: the engine signs in to both servers, then connects the account at once and returns it (`201`). Wrong settings give `401 errors/invalid_credentials` and nothing is stored. Pass `account_id` to **reconnect** an existing account instead (`200` for IMAP). By default only email that arrives after connecting is synced. Add `config: { "initial_sync_enable": true }` to also import the mail already in the mailbox (the last 30 days; `initial_sync_days` 1 to 30), without `email.new` events: see the Initial sync guide (/accounts/initial-sync). Encryption, when left out, follows the port: 143, 587 and 25 use `STARTTLS`, other ports `SSL`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /auth/intent 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": "", "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: /auth/intent: post: tags: - Auth summary: Start an auth intent description: > 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. - **`provider: "imap"`** with the IMAP/SMTP settings: the engine signs in to both servers, then connects the account at once and returns it (`201`). Wrong settings give `401 errors/invalid_credentials` and nothing is stored. Pass `account_id` to **reconnect** an existing account instead (`200` for IMAP). By default only email that arrives after connecting is synced. Add `config: { "initial_sync_enable": true }` to also import the mail already in the mailbox (the last 30 days; `initial_sync_days` 1 to 30), without `email.new` events: see the Initial sync guide (/accounts/initial-sync). Encryption, when left out, follows the port: 143, 587 and 25 use `STARTTLS`, other ports `SSL`. operationId: startAuthIntent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuthIntentInput' examples: imap: summary: IMAP (connects now) value: provider: imap email: ana@fastmail.com name: Ana Lee imap_host: imap.fastmail.com imap_port: 993 imap_password: app-password-here smtp_host: smtp.fastmail.com smtp_port: 465 state: user-42 imap_reconnect: summary: IMAP reconnect (new password) value: provider: imap account_id: acc_3c9e4f1a7b2d4e8f9a6c1d2e3f4a5b6c email: ana@fastmail.com imap_host: imap.fastmail.com imap_password: new-app-password smtp_host: smtp.fastmail.com responses: '200': description: 'Reconnect: the account with its new settings.' content: application/json: schema: $ref: '#/components/schemas/Account' example: $ref: '#/components/examples/ImapAccount/value' '201': description: 'IMAP: the new account.' content: application/json: schema: $ref: '#/components/schemas/Account' example: $ref: '#/components/examples/ImapAccount/value' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/InvalidCredentials' '404': $ref: '#/components/responses/NotFound' '409': description: This mailbox is already connected. content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 409 type: errors/already_exists title: Already exists detail: ana@fastmail.com is already connected components: schemas: AuthIntentInput: type: object required: - provider properties: provider: $ref: '#/components/schemas/Provider' account_id: type: string description: Reconnect this account. state: type: string description: >- Sent back in the redirect and the account.add / account.reconnect event. email: type: string format: email description: 'IMAP: the mailbox''s address (defaults to `imap_user`).' name: type: string description: 'IMAP: display name.' password: type: string description: 'IMAP: one password for IMAP and SMTP.' imap_host: type: string description: >- Filled in from the address for Gmail, Yahoo, iCloud, AOL, Zoho, GMX and Fastmail; otherwise required. imap_port: type: integer description: 993 (SSL) or 143 (STARTTLS). imap_user: type: string imap_password: type: string imap_encryption: type: string enum: - SSL - STARTTLS - NONE smtp_host: type: string smtp_port: type: integer description: 465 (SSL), 587 (STARTTLS) or 25. smtp_user: type: string smtp_password: type: string smtp_encryption: type: string enum: - SSL - STARTTLS - NONE smtp_save_to_sent: type: boolean default: true connection_params: type: object description: The same IMAP/SMTP settings nested.: null config: $ref: '#/components/schemas/InitialSyncConfig' Account: type: object properties: object: type: string const: Account id: type: string description: '`acc_…`' user_id: type: string description: The mailbox's email address. name: type: string provider: $ref: '#/components/schemas/Provider' status: $ref: '#/components/schemas/AccountStatus' status_detail: type: string description: The last error message if any.: null is_locked: type: boolean description: 'Paused from the dashboard: not syncing.' initial_sync: $ref: '#/components/schemas/InitialSync' metadata: type: object additionalProperties: type: string description: Your own key-value data. connection_params: type: object description: Connection settings, never passwords. created_at: type: string format: date-time last_synced_at: type: - string - 'null' format: date-time Error: type: object properties: status: type: integer type: type: string enum: - errors/invalid_parameters - errors/unauthorized - errors/invalid_credentials - errors/not_found - errors/already_exists - errors/provider_rejected - errors/provider_error - errors/unexpected_error title: type: string detail: type: string Provider: type: string enum: - imap description: >- `imap`: Gmail, Google Workspace and every other provider through IMAP/SMTP. InitialSyncConfig: type: object description: One provider's initial sync settings. properties: initial_sync_enable: type: boolean default: false description: Import the mail already in the mailbox, without `email.new` events. initial_sync_days: type: integer minimum: 1 maximum: 30 default: 30 description: How many days back to import; at most 30. AccountStatus: type: string enum: - running - errored - disconnected description: > - `running`: connected and syncing. - `errored`: syncing keeps failing (server down, network); the engine retries by itself. - `disconnected`: the provider rejected the password or token (reconnect it), or the account is paused in the dashboard (`is_locked: true`). InitialSync: type: object description: >- Only on accounts connected with `initial_sync_enable: true`: the import of the mail already in the mailbox. properties: status: type: string enum: - pending - running - completed - failed description: >- `pending`: not started yet; `running`: importing; `completed`: done; `failed`: gave up after 5 failed tries (new mail still syncs). started_at: type: - string - 'null' format: date-time completed_at: type: - string - 'null' format: date-time description: When it completed or failed. days: type: integer minimum: 1 maximum: 30 description: How many days back were imported. imported: type: - integer - 'null' description: Emails imported (set when it completes or fails). responses: BadRequest: description: A parameter is missing or wrong. `detail` says which. content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 400 type: errors/invalid_parameters title: Invalid parameters detail: limit must be between 1 and 250 InvalidCredentials: description: >- `errors/invalid_credentials`: the mail provider rejected the account's password or token; reconnect it. (`errors/unauthorized`: a bad access token.) content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 401 type: errors/invalid_credentials title: Invalid credentials detail: 'the mail provider rejected the credentials: invalid_grant' NotFound: description: Nothing with this id (a malformed or wrong-type id is also not found). content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 404 type: errors/not_found title: Not found detail: email email_94a0d77db739407e932c3b97fef44aac not found 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.