# threads.reply

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.

```ts
openemail.threads.reply(
  mailboxId: string,
  threadId: string,
  body?: ThreadsReplyBody,
  options?: ThreadsReplyOptions,
): ApiPromise<ThreadsReplyResult>
```

It calls `POST /mailboxes/{mailboxId}/threads/{threadId}/reply`: [Reply to a conversation thread](/docs/api/delivery/post_ThreadReply) in the API reference.

## Example

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

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |
| `threadId` | `string` | Conversation thread identifier to reply to. The path's `{threadId}`. |
| `body` | [`ThreadsReplyBody`](#threadsreplybody) | Optional. The request's body. |

## Options

The last argument, `options`, a `ThreadsReplyOptions`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `save` | `boolean` | query `save` | Whether to save a copy in the Sent folder (default true) |
| `bounce` | `boolean` | query `bounce` | Whether to deliver a non-delivery report if relay fails (default true) |
| `deliveryId` | `string` | header `x-delivery-id` | 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. |

Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`ThreadsReplyResult`](#threadsreplyresult). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Retries

When a call gives no `deliveryId` (the `x-delivery-id` header), the client makes one, the same for each of the call's retries, so it is retried like a read: the API converges on one send. Give your own to make your own retries safe too ([retries and idempotent sends](/docs/sdks/typescript/errors#retries-and-idempotent-sends)).

## Errors

| Status | What it means |
| --- | --- |
| `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 |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `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) |
| `404` | Mailbox or thread not found |
| `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. |
| `411` | Content-Length required |
| `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) |
| `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. |
| `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. |
| `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) |
| `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 |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### ThreadsReplyBody

```ts
/** The body of `threads.reply`. */
type ThreadsReplyBody = {
  attachments?: ThreadsReplyBodyAttachmentsItem[]
  /** 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) */
  autoSubmitted?: ('auto-generated' | 'auto-replied') | null
  /** 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 */
  fromAddress?: string | null
  /** Display name for the From header */
  fromName?: string | null
  headers?: Record<string, string>
  html?: string | 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). */
  sendAt?: number | null
  /** Overrides the derived "Re: …" subject */
  subject?: string | null
  text?: string | null
}
```

### ThreadsReplyResult

```ts
/** What `threads.reply` answers. */
type ThreadsReplyResult = SendResult | ScheduledSend
```

### ThreadsReplyBodyAttachmentsItem

```ts
/** The API's `ThreadsReplyBodyAttachmentsItem`, as the document describes it. */
type ThreadsReplyBodyAttachmentsItem = {
  /** Staged-upload form: a blobId from POST /mailboxes/{id}/uploads (or JMAP /upload) */
  blobId?: string
  /** Inline form: base64 payload */
  content?: string
  contentId?: string | null
  /** Defaults to the stored part's / upload's type for a reference or blob, else application/octet-stream */
  contentType?: string | null
  /** Required for an inline attachment. For a reference or a staged upload, defaults to the stored part's filename (or "attachment"). */
  filename?: string
  /** Reference form: a message in THIS mailbox to take the part from */
  messageId?: string
  /** Reference form: the part's section, as reported by /messages/{id}/content */
  section?: string
}
```

It names these types of the API, each on a page of its own: [`ScheduledSend`](/docs/sdks/typescript/types/scheduled-send), [`SendResult`](/docs/sdks/typescript/types/send-result).
