# Reply to a conversation thread

Sends a reply to an existing email conversation. The server automatically derives recipient addresses, Subject line, In-Reply-To, and References headers from the conversation thread. A same-key retry of a stored reply retains its original recipient and MIME even if the conversation has advanced.

## `POST /api/v1/mailboxes/{mailboxId}/threads/{threadId}/reply`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier
- `threadId` (string, required) — Conversation thread identifier to reply to

### Query parameters

- `save` ("true" | "false") — Whether to save a copy in the Sent folder (default true)
- `bounce` ("true" | "false") — Whether to deliver a non-delivery report if relay fails (default true)

### Header parameters

- `x-delivery-id` (string) — Client-provided idempotency key for this submission. A retry with the same id converges on the original submission instead of sending again, and is not charged against the send allowance a second time. It does not get around a sending hold: while the sender is paused or disabled the retry is refused like any submission (429 sending_paused, 403 sending_disabled), and once the hold lifts it continues at its original charge.

### Request body (optional)

`application/json`

- `attachments` (object[], max 50 items)
  - `blobId` (string, 1–64 chars) — Staged-upload form: a blobId from POST /mailboxes/{id}/uploads (or JMAP /upload)
  - `content` (string) — Inline form: base64 payload
  - `contentId` (string | null, max 255 chars)
  - `contentType` (string | null, max 255 chars) — Defaults to the stored part's / upload's type for a reference or blob, else application/octet-stream
  - `filename` (string, 1–255 chars) — Required for an inline attachment. For a reference or a staged upload, defaults to the stored part's filename (or "attachment").
  - `messageId` (string, 1–64 chars) — Reference form: a message in THIS mailbox to take the part from
  - `section` (string, max 64 chars, pattern `^[0-9]+(\.[0-9]+)*$`) — Reference form: the part's section, as reported by /messages/{id}/content
- `autoSubmitted` ("auto-generated" | "auto-replied") — RFC 3834 marker for mail an automaton sends: auto-generated (a notification) or auto-replied (an answer to a message). Written as the Auto-Submitted header so a receiver's loop guards recognise it; refused alongside a free-form Auto-Submitted in headers (auto_submitted_conflict)
- `fromAddress` (string | null, max 254 chars) — Address to send the reply as; must be one this mailbox may send as (else 403 sender_not_owned). Defaults to the address the conversation reached this mailbox at, while it still routes here, else the primary address
- `fromName` (string | null, max 320 chars) — Display name for the From header
- `headers` (object)
- `html` (string | null)
- `sendAt` (integer | null) — Release time, epoch seconds. In the future ⇒ the message is stored as a draft and sent then (202 + a schedule); at or before now ⇒ sent immediately. Requires the Sent copy (`?save` may not be false).
- `subject` (string | null, max 2000 chars) — Overrides the derived "Re: …" subject
- `text` (string | null)

### Responses

**200** — The reply was accepted for its recipient

`application/json` → SendResult

- `deliveryId` (string, required) — Master submission delivery ID
- `recipients` (SendRecipientResult[], required) — Outcome status per recipient
  - `address` (string, required) — Recipient email address
  - `deliveryId` (string, required) — Unique delivery attempt ID for this recipient
  - `status` ("delivered" | "queued" | "filtered" | "failed", required) — Outcome status for this recipient
  - `error` (string) — Error reason code if status is failed (e.g. 'over_quota', 'receiving_disabled'). 'sending_paused' and 'sending_disabled' mean a hold on the sender (mailbox, domain or account) landed while the request was running: recipients already handled keep their status and the rest are refused. 'sending_paused' is temporary: retry with the same X-Delivery-Id once the hold lifts. 'sending_disabled' is permanent. 'recipient_not_verified' is permanent for this recipient alone: the account is not yet vetted, so it may send only to its verified recipients (its own domains, and outside addresses whose owners confirmed them), and this one is neither; or the recipient is a hosted address that forwards for an account not yet vetted, to a target that is not one of that account's verified recipients.
  - `list` (string) — On an address-list refusal: the sender's list that decided
  - `pattern` (string) — On an address-list refusal: the entry that decided (`*@*` for a block-all)
  - `source` ("permitted_recipients" | "address_list" | "verified_recipients") — On 'recipient_not_permitted': which of the sender's own policies refused it, the identity or credential allowlist, or the sender's outbound address lists. On 'recipient_not_verified': 'verified_recipients', the verified-recipients rule of the sending account, or of the account the recipient forwards for
- `sentCopy` ("saved" | "duplicate" | "over_quota") — Status of saving copy to Sent folder ('saved', 'duplicate', 'over_quota')
- `sentThreadId` (string | null) — Conversation thread ID of the saved sent message

**202** — Scheduled (`sendAt` in the future): the reply is stored as a draft and released then

`application/json` → ScheduledSend

- `attempts` (integer, required) — Number of delivery attempts made
- `createdAt` (integer <int64>, required) — Creation timestamp in epoch seconds
- `deferrals` (integer, required) — Number of deferrals encountered
- `deliveryId` (string, required) — Idempotency key for this submission
- `error` (string | null, required) — Error reason if sending failed or was canceled, or null
- `finishedAt` (integer | null, required) — Completion timestamp in epoch seconds, or null if pending
- `messageId` (string, required) — Draft message ULID scheduled for sending
- `recipients` (string[], required) — List of target recipient email addresses
- `releaseAt` (integer <int64>, required) — Actual scheduled release time in epoch seconds
- `result` (array | null, required) — Per-recipient delivery outcomes, or null if pending
- `scheduleId` (string, required) — Scheduled send ULID
- `sendAt` (integer <int64>, required) — Requested send time in epoch seconds
- `state` ("pending" | "releasing" | "sent" | "failed" | "canceled", required) — Current scheduling status
- `threadId` (string | null, required) — Associated conversation thread ID, or null

**207** — The recipient failed; the array carries the reason. sending_paused there is temporary (a hold landed while the request ran): retry with the same X-Delivery-Id once it lifts

`application/json` → SendResult

- `deliveryId` (string, required) — Master submission delivery ID
- `recipients` (SendRecipientResult[], required) — Outcome status per recipient
  - `address` (string, required) — Recipient email address
  - `deliveryId` (string, required) — Unique delivery attempt ID for this recipient
  - `status` ("delivered" | "queued" | "filtered" | "failed", required) — Outcome status for this recipient
  - `error` (string) — Error reason code if status is failed (e.g. 'over_quota', 'receiving_disabled'). 'sending_paused' and 'sending_disabled' mean a hold on the sender (mailbox, domain or account) landed while the request was running: recipients already handled keep their status and the rest are refused. 'sending_paused' is temporary: retry with the same X-Delivery-Id once the hold lifts. 'sending_disabled' is permanent. 'recipient_not_verified' is permanent for this recipient alone: the account is not yet vetted, so it may send only to its verified recipients (its own domains, and outside addresses whose owners confirmed them), and this one is neither; or the recipient is a hosted address that forwards for an account not yet vetted, to a target that is not one of that account's verified recipients.
  - `list` (string) — On an address-list refusal: the sender's list that decided
  - `pattern` (string) — On an address-list refusal: the entry that decided (`*@*` for a block-all)
  - `source` ("permitted_recipients" | "address_list" | "verified_recipients") — On 'recipient_not_permitted': which of the sender's own policies refused it, the identity or credential allowlist, or the sender's outbound address lists. On 'recipient_not_verified': 'verified_recipients', the verified-recipients rule of the sending account, or of the account the recipient forwards for
- `sentCopy` ("saved" | "duplicate" | "over_quota") — Status of saving copy to Sent folder ('saved', 'duplicate', 'over_quota')
- `sentThreadId` (string | null) — Conversation thread ID of the saved sent message

**400** — validation_failed, no_reply_target (the thread has no answerable address, e.g. a null-sender DSN), auto_submitted_conflict (autoSubmitted alongside a free-form Auto-Submitted header), no_primary_address (no fromAddress was given, the conversation's own address does not route here, and the mailbox has no primary address to fall back on), delivery_id_too_long, reserved_delivery_id, or a refused build

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**403** — Permanent — sender_not_owned | sender_not_local | sending_disabled (the mailbox, its domain, or its account may not send) | credential_scope (the credential is scoped below `send`, design D50) | mailbox_gone (the sending mailbox was torn down mid-submission)

`application/json` → ErrorBody

**404** — Mailbox or thread not found

`application/json` → ErrorBody

**409** — delivery_id_reused — the key belongs to another conversation, a message without a single visible reply recipient, a recorded message with a different sender or recipient set, an incompatible scheduled submission, or an immediate send outside its 14-day retry window. Use a fresh X-Delivery-Id for a new message.

`application/json` → ErrorBody

**411** — Content-Length required

`application/json` → ErrorBody

**413** — JSON body exceeds MAX_JSON_BODY_BYTES, the assembled message exceeds MAX_MESSAGE_BYTES, or attachments_too_large (referenced + inline attachment bytes exceed the per-message budget)

`application/json` → ErrorBody

**429** — TEMPORARY, and the only 4xx here that is — retry, never surface it as a permanent failure. rate_limited and sending_paused (a reversible hold) carry `Retry-After` plus `retryAfterSeconds`; too_many_scheduled carries `limit`. This route shares /send's submission path (performSend), so it answers the same refusals.

`application/json` → ErrorBody

**500** — internal — a required Sent or Drafts label is missing; blob_unavailable — an attachment source disappeared, changed length or failed while streaming, before submission admission. Retry when the source is available.

`application/json` → ErrorBody

**503** — Sent copy lost its pending intent (superseded or reaped), or submission_record_unavailable: the submission plan could not be durably prepared before recipient dispatch. Retry with the same X-Delivery-Id. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

**507** — over_quota or account_over_quota — a SCHEDULED reply only: the draft it must store has nowhere to live. An immediate reply is never refused for storage

`application/json` → ErrorBody

### Example request

```bash
curl -X POST 'https://api.open.email/api/v1/mailboxes/{mailboxId}/threads/{threadId}/reply' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## TypeScript SDK

[`openemail.threads.reply`](/docs/sdks/typescript/threads/reply)

```ts
const result = await openemail.threads.reply(mailboxId, threadId, {
  html: '<p>Thanks, looks good. Shipping it.</p>',
  text: 'Thanks, looks good. Shipping it.',
})
```
