Messages

Reply to a message

Reply to a stored Shipmail message by its msg_ ID. Looks up the message's thread and sends a reply using the same mailbox. JMAP IDs returned by mailbox inbox endpoints must use the mailbox-scoped inbox reply endpoint. Replies to transactional email are not supported and return 422 with details[].code transactional_reply_unsupported.

post/messages/{id}/reply

Request

  • Base URL: https://shipmail.to/api/v1
  • URL: https://shipmail.to/api/v1/messages/{id}/reply
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://shipmail.to/api/auth/oauth2/authorize, token URL https://shipmail.to/api/auth/oauth2/token)

Headers

Idempotency-Keystring

Unique key for idempotent requests. Printable ASCII, 1-255 characters. The response is cached for 24 hours. A message send also derives the message ID from the key, so after the cache expires a retry on the same endpoint returns the message already sent, without comparing the body, for as long as that message exists.

X-Shipmail-Organizationstring

OAuth access tokens only. The organization ID this request acts on. Required when the OAuth connection was approved for several organizations (400 validation_error without it); optional with one. An organization the connection was not approved for returns 403 authorization_error. Ignored for API keys, which belong to one organization.

Request body

htmlstring

HTML body. At least one of html or text is required.

textstring

Plain text body. At least one of html or text is required.

client_referencestring

Caller-defined correlation reference, unique within an organization and mode. Sending again from the same mailbox with a reference already in use returns the original message (201) and sends nothing; the new body is not compared. The same reference from a different mailbox returns 409.

metadataMessageMetadata

Up to 20 scalar values and 8 KB of JSON. Nested objects and arrays are rejected.

source_rfc_message_idstring

Caller-selected source RFC Message-ID. Its domain must equal the actual sender domain.

scheduled_atstring date-time

Optional UTC ISO 8601 time to send this reply later.

track_replyboolean

Track the conversation in the Waiting workflow. true tracks it, false explicitly untracks it, and omitting the field keeps the thread's current tracking: a reply sent on a tracked conversation stays tracked. A tracked conversation moves to Needs action when a human reply arrives; automated replies (out-of-office, auto-acknowledgements, delivery notifications) do not end the wait.

sandbox_outcome'delivered' | 'bounced' | 'complained'

Synthetic final outcome for a sandbox send. Only accepted with a test API key.

Response

Reply sent.

object'message' required
idstring required
mailbox_idstring required
thread_idstring nullable required

Deprecated and not stable: a legacy thread ID that changes when the mail server re-threads its IDs or a relayed send's placeholder key is replaced. It remains supported in thread paths; store conversation_id instead.

conversation_idstring nullable required

Stable Shipmail conversation identifier (thd_...). Store this: it survives thread merges and mail-server re-threading, which thread_id does not.

source_rfc_message_idstring nullable required

Source RFC Message-ID supplied by the caller or observed before relay.

delivered_rfc_message_idstring nullable required

Exact provider-assigned delivered RFC Message-ID after Shipmail observes it in a recipient reply. Null before an observation and never reconstructed from the SES provider ID.

client_referencestring nullable required

Caller-defined organization-scoped reference.

metadataMessageMetadata required

Up to 20 scalar values and 8 KB of JSON. Nested objects and arrays are rejected.

subjectstring nullable required
from_addressstring nullable required
source'api' | 'dashboard' | 'newsletter' | 'inbound' | 'smtp' | 'assistant' required
mode'live' | 'test' required

The API-key data plane that owns this resource. Test resources are isolated from live delivery, quota, suppression, and reputation.

status'scheduled' | 'queued' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'cancelled' required
scheduled_atstring date-time nullable required

UTC ISO 8601 time when a scheduled message should be sent. Null for immediate messages.

created_atstring date-time required
updated_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.