Send a message
Submit an outbound message to POST /v1/messages.
A submission requires from, at least one recipient across to, cc, and
bcc, and at least one body representation (text, html, or both).
To safely retry a request, clients can optionally add an Idempotency-Key
header with a client-generated value. It makes retries of the same payload safe
for 24 hours; omit it when idempotent retry handling is unnecessary.
POST https://api.example.com/v1/messages HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <token>Idempotency-Key: welcome-user/123456
{ "from": { "email": "noreply@example.org", "name": "Example App" }, "to": [ { "email": "user@example.net", "name": "Example User" } ], "replyTo": [ { "email": "support@example.org", "name": "Support" } ], "subject": "Welcome to Example App", "text": "Hello, welcome to Example App.", "html": "<p>Hello, welcome to <strong>Example App</strong>.</p>", "headers": [ { "name": "X-App", "value": "example" } ], "attachments": [ { "filename": "terms.txt", "contentType": "text/plain", "content": "VGVybXMgYW5kIGNvbmRpdGlvbnMu" } ]}By default, the provider accepts the message for asynchronous processing and
returns 202 Accepted. This does not confirm delivery to the recipient.
HTTP/1.1 202 AcceptedContent-Type: application/json
{ "id": "msg_01HZXKJ42P6X0Q7J9ZMY1P4R8B"}Bounded wait
Section titled “Bounded wait”A client can ask the provider to wait up to a specified number of seconds for submission to complete:
Prefer: wait=10The provider may ignore this preference. If it applies the preference and
submission completes within ten seconds, it can return 200 OK and identifies
the applied preference. If the wait expires first, it returns 202 Accepted
with the same Preference-Applied header and continues asynchronously.
HTTP/1.1 200 OKContent-Type: application/jsonPreference-Applied: wait=10
{ "id": "msg_01HZXKJ42P6X0Q7J9ZMY1P4R8B"}Replayed response
Section titled “Replayed response”The initial 202 is not a terminal stored outcome. Retrying while execution is
still running returns 409. After execution completes, retrying with the same
Idempotency-Key and a byte-for-byte identical body replays the stored terminal
outcome rather than sending a second message. The replay is marked with
Idempotency-Replayed.
HTTP/1.1 200 OKContent-Type: application/jsonIdempotency-Replayed: true
{ "id": "msg_01HZXKJ42P6X0Q7J9ZMY1P4R8B"}A terminal 500 is also stored and replayed. Preflight failures such as 400,
401, 403, 413, 415, 422, and 429 are not stored, so a corrected
request can reuse the same key. See idempotency for
the processing order and conflict behavior.
Failure response
Section titled “Failure response”Failures use application/problem+json. For example, a message with
semantically invalid fields returns 422 Unprocessable Content.
HTTP/1.1 422 Unprocessable ContentContent-Type: application/problem+json
{ "type": "https://mailapi.github.io/problems/invalid-message", "title": "Message fields are invalid", "status": 422, "detail": "At least one recipient address is invalid.", "instance": "/v1/messages/requests/01HZXKJ42P6X0Q7J9ZMY1P4R8B"}The type member is a stable identifier owned by this specification, so a
client can match the condition across providers. See the
problem type registry for the full list and the
submission response table for the other status codes.
