Quickstart

This is an integration preview, not a public signup flow. To run these requests, you need an internally provisioned organisation and API key, plus a sending domain verified for that organisation. Public access is coming.

Prepare your server

Keep the API key in a server-side environment variable named THUMELA_API_KEY. Never put it in frontend JavaScript or a public environment variable.

Replace the example addresses below with a sender on your verified domain and a recipient you are authorised to email. The .test addresses are placeholders and are not deliverable.

Send a message

curl https://api.thumela.co.za/emails \
  -H "Authorization: Bearer $THUMELA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "orders@example.test",
    "to": ["customer@example.test"],
    "subject": "Your order is confirmed",
    "text": "Thank you. We have received your order.",
    "idempotencyKey": "order-1042-confirmed"
  }'

A successful request returns HTTP 200 and a message ID:

{ "id": "message_id" }

Acceptance means the message is queued for sending. It is not proof of delivery.

Read its status

curl https://api.thumela.co.za/emails/message_id \
  -H "Authorization: Bearer $THUMELA_API_KEY"

The result includes status, attempts, error and lastEvent. A sent status means SES accepted the message. A delivery event means the recipient’s server accepted it; neither confirms it was read.

Retry deliberately

Use the same idempotencyKey when retrying the same message after a timeout or uncertain response. Within 24 hours, a replay returns the original message ID. Use a new key for a different message.

See Send an email for all fields and Errors for failure handling.