---
title: "Send email"
method: POST
path: "/v1/inboxes/{id}/send"
tags: ["messages"]
---

# Send email

`POST /v1/inboxes/{id}/send`

## Request

- Base URL: `https://api.openmail.sh`
- URL: `https://api.openmail.sh/v1/inboxes/{id}/send`
- Auth: HTTP bearer

Send an email from an inbox. Optionally pass an Idempotency-Key header to make retries safe: a repeat with the same key within 24 hours returns the original message instead of sending again. Without it the API generates a key and sends once. Use threadId to reply to an existing thread. When replying on a thread where your inbox was CC'd (deliveryRole cc), the original sender is automatically CC'd.

Every recipient this call can reach — `to`, `cc` (including any address auto-CC'd on a thread reply), `bcc`, and `replyTo` — is checked against the inbox's outbound correspondent policy before anything is sent. A single denied recipient rejects the whole send with 403 `recipient_not_permitted`; there is no partial delivery.

`bcc` recipients are delivered and stored on the outbound message, but they are not listed on the copy To and Cc recipients receive. An address already in `to` or `cc` is not also blind-copied.

## Path parameters

- `id` string, required

## Headers

- `idempotency-key` string

## Request body

- object
  - `to` string, email, required
  - `subject` string: Required for new threads. Optional when threadId is set — the thread subject is used automatically (with Re: prefix).
  - `body` string, required: Email body. Plain text or HTML — HTML is auto-detected and rendered, with a plain-text fallback generated automatically.
  - `bodyHtml` string: Provide only when the plain-text and HTML versions must differ. Omit for normal sends — put HTML in `body` instead.
  - `threadId` string: Thread ID for replies
  - `includeQuote` boolean: When replying with threadId, append a quoted copy of the previous message to the body. Defaults to true. Set false to send only your reply text.
  - `replyTo` string, email: Optional. Address that replies should be routed to (set as the `Reply-To` MIME header). Free plan: must be the address of an inbox you own in OpenMail. Pro plan or higher: any valid email address.
  - `cc` string[]: Optional CC recipients. Visible to every recipient.
  - `bcc` string[]: Optional BCC recipients. Delivered, but omitted from the message To and Cc recipients can read. Use this for CRM logging addresses (for example HubSpot or Salesforce) that only record the email when they are in BCC. Checked against the inbox's outbound recipient policy, same as `to` and `cc`.

## Response `200`

Email sent (or idempotent replay)

- object: Email sent (or idempotent replay)
  - `messageId` string
  - `threadId` string
  - `providerMessageId` string
  - `status` 'pending' | 'sent' | 'failed'

## Other responses

- `400`: Missing request body, invalid 'to'/'replyTo'/'cc'/'bcc' address, or missing subject when required
- `402`: Sending is paused because this account's monthly spend limit was reached (`spend_cap_paused`)
- `403`: A recipient is not permitted by the inbox's outbound correspondent policy (`recipient_not_permitted`, with the refused address in `recipient`). Also returned when a free-plan customer sets `replyTo` to an address that is not one of their own OpenMail inboxes (`feature_requires_paid_plan`), the account is banned (`account_banned`), or sending is suspended due to deliverability/abuse signals (`reputation_suspended`).
- `404`: Inbox or thread not found
- `409`: The custom domain isn't ready to send yet (`domain_sending_pending`). Usually clears within minutes of verification; check the Retry-After response header.
- `422`: Content blocked (`unsafe_content`, `phishing_detected`), a recipient domain has no MX records (`no_mx_records`, with the failing domain in `domain`), recipient suppressed for bounce/complaint (`recipient_suppressed`), or account storage limit exceeded (`storage_limit_exceeded`)
- `429`: Rate limit exceeded (global daily, per-inbox daily, per-inbox burst) or cold outreach limit. Check the Retry-After response header.

---

[API](https://skmtc.dev/openmail/apis/openmail-api.md) · [All operations](https://skmtc.dev/openmail/apis/openmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openmail/apis/openmail-api/revisions/b943eecca7e2?raw)