Sending

Send outbound email

Changed on Oct 10, 2026

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

Request

Base URL: https://api.primitive.dev/v1
URL: https://api.primitive.dev/v1/send-mail
Auth: HTTP bearer

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.

scheduled_atstring date-time

Optional future execution time (ISO 8601). When set, the send is recorded with status scheduled and executed at the requested time instead of immediately. Must be in the future and at most 30 days out. Incompatible with wait (a scheduled send resolves after this request completes) and with attachments / payload_attachments (not yet supported on scheduled sends). Reschedule via PATCH /sent-emails/{id}; cancel via /sent-emails/{id}/cancel. Accepts Z or a numeric UTC offset (2026-10-09T17:00:00Z, 2026-10-09T13:00:00-04:00); an offset is converted to UTC, so the stored and echoed value is UTC. A time with no zone, or a bare date, is rejected.

Response

Outbound relay result. When the request was answered with an existing send instead of making a new one, the response carries Idempotent-Replayed: true and data.idempotency, and nothing was sent for this request.

successboolean required

Changes

Oct 10, 2026414b8232d228 Revision changes
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
Oct 5, 202652138fa51360 Revision changes
- info
  removed the invalid_signup_code enum value from the / response property for the response status
- info
  removed the invalid_signup_code enum value from the / response property for the response status
- info
  removed the invalid_signup_code enum value from the / response property for the response status
- info
  removed the invalid_signup_code enum value from the / response property for the response status
- info
  removed the invalid_signup_code enum value from the / response property for the response status
- info
  removed the invalid_signup_code enum value from the / response property for the response status
- info
  removed the invalid_signup_code enum value from the / response property for the response status
- info
  removed the invalid_signup_code enum value from the / response property for the response status

Operation history (15 revisions)