> ## 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. # Send an email > 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"`). **Reply:** set `reply_to` to the `email_…` id you answer. The engine fills in the recipients, the subject (`Re: …`) and the threading headers. **Attachments:** `multipart/form-data` with files in fields named `attachments`, or JSON with base64 `content`. Up to 30 MB per request. **Tracking:** `tracking_options` reports opens and clicks (`tracking.open`, `tracking.click`). At least one recipient is needed, unless you use `reply_to`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /emails 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: /emails: post: tags: - Emails summary: Send an email description: > 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"`). **Reply:** set `reply_to` to the `email_…` id you answer. The engine fills in the recipients, the subject (`Re: …`) and the threading headers. **Attachments:** `multipart/form-data` with files in fields named `attachments`, or JSON with base64 `content`. Up to 30 MB per request. **Tracking:** `tracking_options` reports opens and clicks (`tracking.open`, `tracking.click`). At least one recipient is needed, unless you use `reply_to`. operationId: sendEmail requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendInput' examples: simple: summary: A new email value: account_id: acc_ba1fa6938d8548298e8ce62e4b4b4e99 to: - display_name: Ana Lee identifier: ana@example.com subject: Meeting tomorrow body:

Hi Ana,

Are we still on for 10:00?

reply: summary: A reply in the same thread value: account_id: acc_ba1fa6938d8548298e8ce62e4b4b4e99 reply_to: email_94a0d77db739407e932c3b97fef44aac body:

Thanks, see you then!

attachment: summary: With an attachment (base64) value: account_id: acc_ba1fa6938d8548298e8ce62e4b4b4e99 to: - identifier: ana@example.com subject: Our proposal body:

The proposal is attached.

attachments: - filename: proposal.pdf content_type: application/pdf content: JVBERi0xLjQKJcfsj6IK tracked: summary: With open and click tracking value: account_id: acc_ba1fa6938d8548298e8ce62e4b4b4e99 to: - identifier: ana@example.com subject: Our offer body:

See the offer.

tracking_options: opens: true links: true label: campaign-7 multipart/form-data: schema: type: object required: - account_id properties: account_id: type: string description: The account to send from (`acc_…`). to: type: string description: JSON list of attendees, or comma-separated addresses. cc: type: string bcc: type: string subject: type: string body: type: string description: HTML body. body_plain: type: string reply_to: type: string description: The `email_…` id you answer. tracking_options: type: string description: JSON, e.g. `{"opens":true}`. custom_headers: type: string description: JSON list of `{name, value}`. attachments: type: array items: type: string format: binary description: One field per file, all named `attachments`. responses: '201': description: The email is sent. content: application/json: schema: type: object properties: object: type: string const: EmailSent account_id: type: string message_id: type: string description: >- The `Message-ID` of the sent email. Its Sent copy has the same `message_id`. provider_id: type: - string - 'null' description: >- Always `null`: SMTP returns no id when sending. The Sent copy gets its ids when it syncs. tracking_id: type: - string - 'null' description: Set when `tracking_options` is used (`trk_…`). example: object: EmailSent account_id: acc_ba1fa6938d8548298e8ce62e4b4b4e99 message_id: 84c3db9476d84b288bc6fa055a576764@mail-api.example.com provider_id: 1a1108eec86709d8 tracking_id: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/InvalidCredentials' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ProviderRejected' '502': $ref: '#/components/responses/ProviderError' components: schemas: SendInput: type: object properties: account_id: type: string description: The account to send from (`acc_…`). to: type: array items: $ref: '#/components/schemas/Attendee' cc: type: array items: $ref: '#/components/schemas/Attendee' bcc: type: array items: $ref: '#/components/schemas/Attendee' from: type: object properties: display_name: type: string identifier: type: string description: Sender name; `identifier` can set a send-as alias. reply_to_addresses: type: array items: $ref: '#/components/schemas/Attendee' subject: type: string body: type: string description: HTML body. body_plain: type: string reply_to: type: string description: The `email_…` id you answer. custom_headers: type: array items: type: object properties: name: type: string value: type: string description: X-…, List-Unsubscribe, List-Unsubscribe-Post or Reply-To. tracking_options: type: object properties: opens: type: boolean links: type: boolean label: type: string custom_domain: type: string attachments: type: array items: type: object required: - content properties: filename: type: string content_type: type: string content: type: string contentEncoding: base64 Attendee: type: object properties: display_name: type: string identifier: type: string format: email required: - identifier 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 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 ProviderRejected: description: The mail provider refused the request. Retrying won't help. content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 422 type: errors/provider_rejected title: Rejected by the provider detail: Message too large ProviderError: description: The mail provider failed or didn't answer. Try again later. content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 502 type: errors/provider_error title: Mail provider error detail: timed out talking to imap.example.com 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.