API Compatibility

Versioning promiseCopy Anchor Link

The API is versioned in the URL path. Today only /v1 exists.

• v1 changes are additive only. We add endpoints, optional request fields, response fields and event types. We do not remove or rename a field, change its meaning, or make an optional field required. Your client must ignore response fields it does not know.
• A breaking change ships as /v2. We announce it at least 180 days before it is available, and /v1 keeps working alongside /v2 for 180 days after /v2 is released.

Recipient fan-outCopy Anchor Link

When POST /v1/transactional/send has several recipients in to, each recipient receives a separate copy of the message, with its own message ID. There is no shared message, and no visible Cc: a recipient never sees the other addresses. The request does not accept cc or bcc. If you need every recipient to see the others, that is not available in v1.

Attachment sizeCopy Anchor Link

A message carries at most 10 attachments and at most 10 MiB in total, measured after Base64 decoding. A request over the limit is refused with 400 VALIDATION_FAILED. See Attachments.

Idempotency scopeCopy Anchor Link

X-Idempotency-Key is accepted on exactly two endpoints: POST /v1/transactional/send and POST /v1/transactional/send-batch. No other endpoint reads it, so retrying any other POST can repeat its effect. See Idempotency.