v2

latestOpenAPI 3.1.0Proprietary2026-07-26127193620.1 KB

Sending

Send outbound email

Sends an outbound email through Primitive's outbound relay. By default the request returns once the relay accepts the message for delivery. Set wait: true to wait for the first downstream SMTP delivery outcome.

Host routing. /send-mail is served by the canonical API host (https://api.primitive.dev/v1) so the request body can carry inline attachments up to ~30 MiB raw. The legacy dashboard compatibility host (https://www.primitive.dev/api/v1) also accepts /send-mail, but Vercel request body limits apply before proxying. The typed SDKs route /send-mail to the canonical API host automatically.

post/send-mail

Headers

Idempotency-Keystring

Optional customer-supplied idempotency key. If omitted, Primitive derives one from the canonical request payload and echoes the effective value in the Idempotency-Key response header.

Request body

fromstring required

RFC 5322 From header. The sender domain must be a verified outbound domain for your organization.

tostring required

Recipient address. Recipient eligibility depends on your account's outbound entitlements.

subjectstring required

Subject line for the outbound message

body_textstring

Plain-text message body. At least one of body_text or body_html is required. The combined UTF-8 byte length of body_text and body_html must be at most 262144 bytes.

body_htmlstring

HTML message body. At least one of body_text or body_html is required. The combined UTF-8 byte length of body_text and body_html must be at most 262144 bytes.

in_reply_tostring

Message-ID of the direct parent email when sending a threaded reply.

referencesstring[]

Full ordered message-id chain for the thread.

waitboolean

When true, wait for the first downstream SMTP delivery outcome before returning.

wait_timeout_msinteger

Maximum time to wait for a delivery outcome when wait is true. Defaults to 30000.

Response

Outbound relay result

successtrue required