Send a message
const url = 'https://api.example.com/v1/messages';const options = { method: 'POST', headers: { Prefer: 'wait=10', 'Idempotency-Key': 'welcome-user/123456', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"from":{"email":"hello@example.com","name":"example"},"to":[{"email":"hello@example.com","name":"example"}],"cc":[{"email":"hello@example.com","name":"example"}],"bcc":[{"email":"hello@example.com","name":"example"}],"replyTo":[{"email":"hello@example.com","name":"example"}],"subject":"example","text":"example","html":"example","headers":[{"name":"example","value":"example"}],"attachments":[{"filename":"example","contentType":"example","content":"example"}],"extensions":{"vendorTags":["welcome-series"]}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.example.com/v1/messages \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: welcome-user/123456' \ --header 'Prefer: wait=10' \ --data '{ "from": { "email": "hello@example.com", "name": "example" }, "to": [ { "email": "hello@example.com", "name": "example" } ], "cc": [ { "email": "hello@example.com", "name": "example" } ], "bcc": [ { "email": "hello@example.com", "name": "example" } ], "replyTo": [ { "email": "hello@example.com", "name": "example" } ], "subject": "example", "text": "example", "html": "example", "headers": [ { "name": "example", "value": "example" } ], "attachments": [ { "filename": "example", "contentType": "example", "content": "example" } ], "extensions": { "vendorTags": [ "welcome-series" ] } }'Submits an outbound message for asynchronous processing. The default success response is 202. A client can send Prefer: wait=N to ask the provider to wait up to N seconds for submission to complete; when the preference is applied and submission completes in time, the provider can return 200. Neither response confirms delivery to any recipient.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”RFC 7240 processing preference. wait=N, where N is a non-negative number of seconds, asks the provider to wait up to that duration for submission to complete. The provider may ignore the preference. If it applies the preference, it returns Preference-Applied: wait=N; completion within the applied wait can produce 200, otherwise the response remains 202 and processing continues asynchronously.
Example
wait=10Client-generated key that makes submission execution idempotent for 24 hours. The key namespace is scoped to the authenticated principal and this operation; one principal cannot collide with or replay another principal’s key.
Authentication, authorization, media-type and size checks, JSON parsing, message validation, and rate-limit admission happen before the key is reserved. Responses from those checks (400, 401, 403, 413, 415, 422, and 429) are not stored and may be corrected and retried with the same key.
After those checks pass, the provider atomically associates the key with the byte-for-byte UTF-8 request body. JSON whitespace and object-member ordering are significant. A different body or an execution still in progress returns 409. Once execution produces a terminal 200 or 500 outcome, the provider stores its status and body for the remainder of the retention period. The initial 202 response is not terminal and is not stored as the outcome. A matching retry while execution continues returns 409; after completion it replays the terminal response with Idempotency-Replayed: true rather than executing again. A 503 means execution did not begin and is not stored. After 24 hours the association is forgotten and the key can start a new submission.
The key is transmitted as an HTTP field value, so it is restricted to visible ASCII characters.
Example
welcome-user/123456Request Bodyrequired
Section titled “Request Bodyrequired”A submission additionally requires at least one recipient across to, cc, and bcc, and at least one body representation. Entries in headers are supplemental: names represented by structured fields (From, To, Cc, Bcc, Reply-To, and Subject) and MIME framing fields (Content-Type, Content-Transfer-Encoding, and MIME-Version) are invalid in an outbound request and produce 422 rather than overriding the structured message.
object
object
Optional display name for the address.
object
Optional display name for the address.
object
Optional display name for the address.
object
Optional display name for the address.
object
Optional display name for the address.
Ordered RFC 5322-style header fields. Structured fields such as from, to, and subject are authoritative for those concepts; headers provide supplemental values, including repeated fields.
object
RFC 5322 field name (printable ASCII excluding colon), for example Received or X-Custom-Header.
Unfolded header field value. Carriage return and line feed are not permitted.
object
MIME media type for the attachment.
Base64-encoded attachment content.
Provider-specific extension members. Mail API defines no extension name. A provider must document every name it accepts, must not require one for a conformant submission, and must ignore rather than reject names it does not recognize. Keeping extensions in one container lets the rest of the message model stay strictly validated.
object
Example
{ "vendorTags": [ "welcome-series" ]}object
object
object
object
object
Responses
Section titled “Responses”Submission completed and the provider accepted responsibility for further processing. This is returned when submission completes within an applied Prefer: wait=N period or when a completed, keyed outcome is replayed. It does not confirm final recipient delivery.
object
Mail API identifier assigned before asynchronous execution begins and retained for correlation with any downstream provider identifier. It is not a delivery receipt or the URL of a status resource.
Examplegenerated
{ "id": "example"}Headers
Section titled “Headers”RFC 7240 preference applied while processing the request. Present as wait=N when the provider honored that preference; absent when no preference was applied.
Example
wait=10Present with the value true when the response was replayed from a previous submission that used the same Idempotency-Key. Absent for a newly processed submission.
Example
trueSubmission was accepted for asynchronous processing. This is the default success response and is also returned when an applied Prefer: wait=N period expires before submission completes. It does not confirm final recipient delivery.
object
Mail API identifier assigned before asynchronous execution begins and retained for correlation with any downstream provider identifier. It is not a delivery receipt or the URL of a status resource.
Examplegenerated
{ "id": "example"}Headers
Section titled “Headers”RFC 7240 preference applied while processing the request. Present as wait=N when the provider honored that preference; absent when no preference was applied.
Example
wait=10Malformed JSON or invalid request syntax.
RFC 9457 problem details for an unsuccessful request. The type values listed at https://mailapi.github.io/problems/ are stable, specification-owned identifiers; a conformant provider uses them unchanged so that clients can match a condition across providers. A provider may define additional type values under its own namespace for conditions this specification does not name.
object
URI reference identifying the problem type.
Short, human-readable summary of the problem type.
HTTP status code generated by the origin server.
Human-readable explanation specific to this occurrence.
URI reference identifying this specific problem occurrence.
Example
{ "type": "https://mailapi.github.io/problems/malformed-request", "title": "Malformed request", "status": 400, "detail": "The request body is not valid JSON."}Authentication credentials are missing, malformed, or invalid.
RFC 9457 problem details for an unsuccessful request. The type values listed at https://mailapi.github.io/problems/ are stable, specification-owned identifiers; a conformant provider uses them unchanged so that clients can match a condition across providers. A provider may define additional type values under its own namespace for conditions this specification does not name.
object
URI reference identifying the problem type.
Short, human-readable summary of the problem type.
HTTP status code generated by the origin server.
Human-readable explanation specific to this occurrence.
URI reference identifying this specific problem occurrence.
Example
{ "type": "https://mailapi.github.io/problems/unauthenticated", "title": "Unauthenticated", "status": 401, "detail": "The request did not include valid credentials."}Headers
Section titled “Headers”Challenge describing the authentication scheme the provider expects.
Example
Bearer realm="mailapi"Credentials are valid but not authorized for this submission, for example when the authenticated principal may not send as the requested from identity.
RFC 9457 problem details for an unsuccessful request. The type values listed at https://mailapi.github.io/problems/ are stable, specification-owned identifiers; a conformant provider uses them unchanged so that clients can match a condition across providers. A provider may define additional type values under its own namespace for conditions this specification does not name.
object
URI reference identifying the problem type.
Short, human-readable summary of the problem type.
HTTP status code generated by the origin server.
Human-readable explanation specific to this occurrence.
URI reference identifying this specific problem occurrence.
Example
{ "type": "https://mailapi.github.io/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "This principal is not authorized to send as noreply@example.org."}Idempotency key conflicts with a different request payload, or an identical submission using that key is still in progress.
RFC 9457 problem details for an unsuccessful request. The type values listed at https://mailapi.github.io/problems/ are stable, specification-owned identifiers; a conformant provider uses them unchanged so that clients can match a condition across providers. A provider may define additional type values under its own namespace for conditions this specification does not name.
object
URI reference identifying the problem type.
Short, human-readable summary of the problem type.
HTTP status code generated by the origin server.
Human-readable explanation specific to this occurrence.
URI reference identifying this specific problem occurrence.
Examples
The key was reused with a different payload.
{ "type": "https://mailapi.github.io/problems/idempotency-key-reused", "title": "Idempotency key reused", "status": 409, "detail": "This key was already used with a different request body."}The matching submission is still in progress.
{ "type": "https://mailapi.github.io/problems/idempotency-key-in-progress", "title": "Idempotent submission in progress", "status": 409, "detail": "Retry the request with the same key later."}Request body or attachment content exceeds a provider limit.
RFC 9457 problem details for an unsuccessful request. The type values listed at https://mailapi.github.io/problems/ are stable, specification-owned identifiers; a conformant provider uses them unchanged so that clients can match a condition across providers. A provider may define additional type values under its own namespace for conditions this specification does not name.
object
URI reference identifying the problem type.
Short, human-readable summary of the problem type.
HTTP status code generated by the origin server.
Human-readable explanation specific to this occurrence.
URI reference identifying this specific problem occurrence.
Example
{ "type": "https://mailapi.github.io/problems/payload-too-large", "title": "Payload too large", "status": 413, "detail": "The request body exceeds the provider submission limit."}Unsupported request media type.
RFC 9457 problem details for an unsuccessful request. The type values listed at https://mailapi.github.io/problems/ are stable, specification-owned identifiers; a conformant provider uses them unchanged so that clients can match a condition across providers. A provider may define additional type values under its own namespace for conditions this specification does not name.
object
URI reference identifying the problem type.
Short, human-readable summary of the problem type.
HTTP status code generated by the origin server.
Human-readable explanation specific to this occurrence.
URI reference identifying this specific problem occurrence.
Example
{ "type": "https://mailapi.github.io/problems/unsupported-media-type", "title": "Unsupported media type", "status": 415, "detail": "Send the request body as application/json."}Message fields are syntactically valid but semantically invalid.
RFC 9457 problem details for an unsuccessful request. The type values listed at https://mailapi.github.io/problems/ are stable, specification-owned identifiers; a conformant provider uses them unchanged so that clients can match a condition across providers. A provider may define additional type values under its own namespace for conditions this specification does not name.
object
URI reference identifying the problem type.
Short, human-readable summary of the problem type.
HTTP status code generated by the origin server.
Human-readable explanation specific to this occurrence.
URI reference identifying this specific problem occurrence.
Example
{ "type": "https://mailapi.github.io/problems/invalid-message", "title": "Message fields are invalid", "status": 422, "detail": "At least one recipient address is invalid."}Submission rate limit exceeded. The request may be retried.
RFC 9457 problem details for an unsuccessful request. The type values listed at https://mailapi.github.io/problems/ are stable, specification-owned identifiers; a conformant provider uses them unchanged so that clients can match a condition across providers. A provider may define additional type values under its own namespace for conditions this specification does not name.
object
URI reference identifying the problem type.
Short, human-readable summary of the problem type.
HTTP status code generated by the origin server.
Human-readable explanation specific to this occurrence.
URI reference identifying this specific problem occurrence.
Example
{ "type": "https://mailapi.github.io/problems/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Too many submissions. Retry after the indicated delay."}Headers
Section titled “Headers”Delay before retrying, as defined by RFC 9110: either a non-negative number of seconds or an HTTP-date.
Examples
Delay in seconds.
30Absolute retry time.
Fri, 21 Aug 2026 10:55:00 GMTUnexpected provider error. The submission outcome may be unknown; without an Idempotency-Key, a retry can create a duplicate. With an Idempotency-Key, this terminal response is stored and a matching retry replays it rather than executing another submission.
RFC 9457 problem details for an unsuccessful request. The type values listed at https://mailapi.github.io/problems/ are stable, specification-owned identifiers; a conformant provider uses them unchanged so that clients can match a condition across providers. A provider may define additional type values under its own namespace for conditions this specification does not name.
object
URI reference identifying the problem type.
Short, human-readable summary of the problem type.
HTTP status code generated by the origin server.
Human-readable explanation specific to this occurrence.
URI reference identifying this specific problem occurrence.
Example
{ "type": "https://mailapi.github.io/problems/provider-error", "title": "Provider error", "status": 500, "detail": "The submission outcome is unknown."}Headers
Section titled “Headers”RFC 7240 preference applied while processing the request. Present as wait=N when the provider honored that preference; absent when no preference was applied.
Example
wait=10Present with the value true when the response was replayed from a previous submission that used the same Idempotency-Key. Absent for a newly processed submission.
Example
trueProvider is temporarily unable to accept the message. Submission execution did not begin, so an Idempotency-Key is not retained and the same request and key may be retried.
RFC 9457 problem details for an unsuccessful request. The type values listed at https://mailapi.github.io/problems/ are stable, specification-owned identifiers; a conformant provider uses them unchanged so that clients can match a condition across providers. A provider may define additional type values under its own namespace for conditions this specification does not name.
object
URI reference identifying the problem type.
Short, human-readable summary of the problem type.
HTTP status code generated by the origin server.
Human-readable explanation specific to this occurrence.
URI reference identifying this specific problem occurrence.
Example
{ "type": "https://mailapi.github.io/problems/provider-unavailable", "title": "Provider unavailable", "status": 503, "detail": "The provider did not accept the message. Retry later."}Headers
Section titled “Headers”Delay before retrying, as defined by RFC 9110: either a non-negative number of seconds or an HTTP-date.
Examples
Delay in seconds.
30Absolute retry time.
Fri, 21 Aug 2026 10:55:00 GMT