Messages

Send a message

Send an email from a mailbox. Provide from (email address) or mailbox_id to identify the sender. Prefer from when you know the mailbox email address; Shipmail resolves it to a mailbox ID. At least one of html or text is required. Total recipients (to + cc + bcc) must not exceed 50. Attachments are base64-encoded, max 20 files, 3 MB per file, 3 MB total. To send from a transactional sender (https://shipmail.to/docs/features/transactional-email), set from to its bare address; mailbox_id is optional and, when set, must be the sender's mailbox. Shipmail adds the sender name and Reply-To. Transactional senders send immediately only and refuse scheduled_at, track_reply: true, staged_attachment_ids, a different reply_to and a different display name. A transactional email send that reaches a ceiling returns 429 with details[].code application_daily_limit (daily ceiling for transactional email, a share of the organization's daily sending limit), application_unique_recipients (hourly ceiling of different recipients) or application_storage_full (the sender's mailbox has no transactional email storage left).

post/messages

Request

  • Base URL: https://shipmail.to/api/v1
  • URL: https://shipmail.to/api/v1/messages
  • 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

fromstring

Sending mailbox, as a bare address (hello@example.com) or RFC 5322 name-addr (Acme Support hello@example.com). Shipmail resolves the address to a mailbox ID server-side. A display name applies to this send only; a bare address uses the mailbox display name. For a transactional sender, pass the bare sender address; the sender's display name is added, and a different name is refused.

mailbox_idstring

ID of the sending mailbox. Alternative to from.

subjectstring required

Email subject.

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.

in_reply_tostring

Message-ID this message replies to, sent as the In-Reply-To header. The message joins the conversation of the stored message with this Message-ID when it is found in exactly one conversation of the mailbox; otherwise it starts its own. It never merges conversations.

referencesstring[]

Message-IDs sent as the References header, for threading in the recipient's mail client. They never decide or merge conversations.

staged_attachment_idsstring[]

IDs returned by POST /mailboxes/{id}/staged-attachments. IDs must belong to this API key, organization, and sending mailbox.

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 later. Past or near-immediate times are sent immediately.

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.

Example request

{
  "from": "hello@example.com"
}

Response

Message queued for delivery.

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.