Send an email
POST https://api.thumela.co.za/emails
Send JSON with Content-Type: application/json and bearer authentication.
Request fields
| Field | Type | Requirement |
|---|---|---|
from | string | Required address on a verified sending domain, e.g. Acme <orders@acme.test> |
to | string[] | Required, at least one recipient |
cc, bcc | string[] | Optional additional recipients |
reply_to | string | Optional reply address |
subject | string | Required subject |
html | string | HTML body; at least one of html or text is required |
text | string | Plain-text body; may accompany html |
headers | object | Optional string values, with only X-* names and List-Unsubscribe permitted |
idempotencyKey | string | Optional, 1–256 characters; a key for this message |
tag | string | Optional; defaults to transactional. Any other value is rejected |
There is a maximum of 50 recipients in total across to, cc and bcc. Thumela does not rewrite your HTML or links and does not insert tracking pixels.
Idempotency
Pass idempotencyKey in the JSON body. An Idempotency-Key HTTP header is not implemented.
For the same organisation and key, retries within 24 hours return the original ID. Always reuse a key only for the same logical message; changing the body does not turn a replay into a new send. Domain and suppression validation still apply before replay lookup.
Response
HTTP 200:
{ "id": "message_id" }The message is queued. A success response does not promise delivery.
Read a message
GET https://api.thumela.co.za/emails/:id
Use the same bearer authentication. The response includes:
| Field | Meaning |
|---|---|
id | Message identifier |
status | queued, sending, sent, failed or suppressed |
to | Stored recipient list, including original to, cc and bcc recipients |
subject, tag | Stored message metadata |
attempts | Number of sending attempts |
error | Failure information, or null |
sesMessageId | SES identifier once assigned, or null |
createdAt, sentAt | Creation timestamp and sending timestamp, with sentAt nullable |
lastEvent | Latest event { type, occurredAt }, or null |
Event types are delivery, bounce, complaint, reject and delivery_delay. sent means accepted by SES, not read by the recipient.
Failure and retention boundaries
A suppressed recipient causes a 422 Suppressed response before sending. An unverified sender domain returns 422 UnverifiedDomain. A marketing tag returns 422 UnsupportedTag.
Bodies are kept in process memory for sending and retries. A process restart loses pending bodies and those messages fail with body_lost_on_restart. Message records and events are purged after 90 days.