Skip to content

Send a message

POST
/v1/messages
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.

Prefer
string

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=10
Idempotency-Key
string
>= 1 characters <= 256 characters /^[\x21-\x7E]+$/

Client-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/123456
Media typeapplication/json

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
from
required
object
email
required
string format: email
name

Optional display name for the address.

string
to
Array<object>
>= 1 items
object
email
required
string format: email
name

Optional display name for the address.

string
cc
Array<object>
>= 1 items
object
email
required
string format: email
name

Optional display name for the address.

string
bcc
Array<object>
>= 1 items
object
email
required
string format: email
name

Optional display name for the address.

string
replyTo
Array<object>
object
email
required
string format: email
name

Optional display name for the address.

string
subject
string
text
string
html
string
headers

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.

Array<object>
object
name
required

RFC 5322 field name (printable ASCII excluding colon), for example Received or X-Custom-Header.

string
>= 1 characters /^[\x21-\x39\x3B-\x7E]+$/
value
required

Unfolded header field value. Carriage return and line feed are not permitted.

string
/^[^\r\n]*$/
attachments
Array<object>
object
filename
required
string
contentType
required

MIME media type for the attachment.

string
content
required

Base64-encoded attachment content.

string format: byte
extensions

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
key
additional properties
any
Example
{
"vendorTags": [
"welcome-series"
]
}
Any of:
object
Any of:
object

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.

Media typeapplication/json
object
id
required

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.

string
Examplegenerated
{
"id": "example"
}
Preference-Applied
string

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=10
Idempotency-Replayed
boolean

Present 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
true

Submission 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.

Media typeapplication/json
object
id
required

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.

string
Examplegenerated
{
"id": "example"
}
Preference-Applied
string

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=10

Malformed JSON or invalid request syntax.

Media typeapplication/problem+json

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
type
required

URI reference identifying the problem type.

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code generated by the origin server.

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this specific problem occurrence.

string format: uri-reference
key
additional properties
any
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.

Media typeapplication/problem+json

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
type
required

URI reference identifying the problem type.

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code generated by the origin server.

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this specific problem occurrence.

string format: uri-reference
key
additional properties
any
Example
{
"type": "https://mailapi.github.io/problems/unauthenticated",
"title": "Unauthenticated",
"status": 401,
"detail": "The request did not include valid credentials."
}
WWW-Authenticate
string

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.

Media typeapplication/problem+json

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
type
required

URI reference identifying the problem type.

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code generated by the origin server.

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this specific problem occurrence.

string format: uri-reference
key
additional properties
any
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.

Media typeapplication/problem+json

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
type
required

URI reference identifying the problem type.

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code generated by the origin server.

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this specific problem occurrence.

string format: uri-reference
key
additional properties
any
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."
}

Request body or attachment content exceeds a provider limit.

Media typeapplication/problem+json

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
type
required

URI reference identifying the problem type.

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code generated by the origin server.

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this specific problem occurrence.

string format: uri-reference
key
additional properties
any
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.

Media typeapplication/problem+json

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
type
required

URI reference identifying the problem type.

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code generated by the origin server.

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this specific problem occurrence.

string format: uri-reference
key
additional properties
any
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.

Media typeapplication/problem+json

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
type
required

URI reference identifying the problem type.

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code generated by the origin server.

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this specific problem occurrence.

string format: uri-reference
key
additional properties
any
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.

Media typeapplication/problem+json

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
type
required

URI reference identifying the problem type.

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code generated by the origin server.

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this specific problem occurrence.

string format: uri-reference
key
additional properties
any
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."
}
Retry-After
string

Delay before retrying, as defined by RFC 9110: either a non-negative number of seconds or an HTTP-date.

Examples

Delay in seconds.

30

Unexpected 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.

Media typeapplication/problem+json

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
type
required

URI reference identifying the problem type.

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code generated by the origin server.

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this specific problem occurrence.

string format: uri-reference
key
additional properties
any
Example
{
"type": "https://mailapi.github.io/problems/provider-error",
"title": "Provider error",
"status": 500,
"detail": "The submission outcome is unknown."
}
Preference-Applied
string

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=10
Idempotency-Replayed
boolean

Present 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
true

Provider 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.

Media typeapplication/problem+json

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
type
required

URI reference identifying the problem type.

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code generated by the origin server.

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this specific problem occurrence.

string format: uri-reference
key
additional properties
any
Example
{
"type": "https://mailapi.github.io/problems/provider-unavailable",
"title": "Provider unavailable",
"status": 503,
"detail": "The provider did not accept the message. Retry later."
}
Retry-After
string

Delay before retrying, as defined by RFC 9110: either a non-negative number of seconds or an HTTP-date.

Examples

Delay in seconds.

30