Skip to Content
POST
/api/v1/mailboxes/{mailboxId}/threads/{threadId}/reply

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.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Path Parameters

mailboxId*string

Mailbox ULID identifier

threadId*string

Conversation thread identifier to reply to

Query Parameters

save?string

Whether to save a copy in the Sent folder (default true)

Value in"true""false"
bounce?string

Whether to deliver a non-delivery report if relay fails (default true)

Value in"true""false"

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

application/json
  1. body
attachments?array<>
Itemsitems <= 50
autoSubmitted?|

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)

Value in"auto-generated""auto-replied"
fromAddress?|

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

Formatemail
Lengthlength <= 254
fromName?|

Display name for the From header

Lengthlength <= 320
headers?
html?string|null
sendAt?|

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).

Formatint64
subject?|

Overrides the derived "Re: …" subject

Lengthlength <= 2000
text?string|null

Response Body

The reply was accepted for its recipient

application/json
  1. response
deliveryId*string

Master submission delivery ID

recipients*array<>

Outcome status per recipient

sentCopy?string

Status of saving copy to Sent folder ('saved', 'duplicate', 'over_quota')

Value in"saved""duplicate""over_quota"
sentThreadId?|

Conversation thread ID of the saved sent message

Example Request
curl -X POST 'https://api.open.email/api/v1/mailboxes/string/threads/string/reply' \
  -H 'Content-Type: application/json' \
  -d '{
  "html": "<p>Thanks, looks good. Shipping it.</p>",
  "text": "Thanks, looks good. Shipping it."
}'
Example Response
{
  "deliveryId": "string",
  "recipients": [
    {
      "address": "string",
      "deliveryId": "string",
      "error": "string",
      "list": "string",
      "pattern": "string",
      "source": "permitted_recipients",
      "status": "delivered"
    }
  ],
  "sentCopy": "saved",
  "sentThreadId": "string"
}