API reference

Request and response headers

Emails

Send an email

POST/v1/emails

Validates the request, writes the message, queues it and returns the id. The email leaves through Amazon SES in the Africa (Cape Town) region within seconds. Requires the emails:send scope and a verified sending domain.

curl https://api.sendbaze.com/v1/emails \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "from": "Yourshop <orders@yourshop.co.za>",
    "to": ["thandi@example.com"],
    "replyTo": "help@yourshop.co.za",
    "subject": "Your order #1042 has shipped",
    "html": "<p>Tracking: <b>CG123456789ZA</b></p>",
    "text": "Tracking: CG123456789ZA",
    "tags": ["order-shipped"]
  }'

# 200 OK
# { "id": "em_01j9x7k2r4m8q3v5n6b7c8d9e0", "status": "queued" }

Send a batch of emails

POST/v1/emails/batch

Up to 1 000 emails in one request. Each item is validated and queued on its own, so a bad item fails alone. Results come back in input order. Idempotency-Key is not applied to individual items; use tags to reconcile.

curl https://api.sendbaze.com/v1/emails/batch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      { "from": "orders@yourshop.co.za", "to": "a@example.com", "subject": "Hi", "text": "..." },
      { "from": "orders@yourshop.co.za", "to": "not-an-email", "subject": "Hi", "text": "..." }
    ]
  }'

# 200 OK
# {
#   "results": [
#     { "index": 0, "ok": true,  "data": { "id": "em_01j9...", "status": "queued" } },
#     { "index": 1, "ok": false, "error": { "code": "validation_error", "message": "...",
#                                           "fields": { "to": ["must be a valid email address"] } } }
#   ]
# }

Retrieve an email

GET/v1/emails/{id}

Returns the message object with its full event timeline. Requires the read scope.

SMS

Send an SMS

POST/v1/sms

Counts segments (GSM-7 or UCS-2), checks credits, applies the compliance rules for the message class, debits credits and queues the message. Credits are refunded automatically if the message never leaves our platform. Requires the sms:send scope.

curl https://api.sendbaze.com/v1/sms \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+27821234567",
    "body": "Your OTP is 482 913. It expires in 5 minutes.",
    "class": "transactional"
  }'

# 200 OK
# { "id": "sm_01j9x7n4q6r8s0t2u4v6w8x0y2", "status": "queued", "segments": 1, "credits": 1 }

Send a batch of SMS

POST/v1/sms/batch

Same shape as the email batch with a messages array of up to 1 000 items. If credits run out part-way, the remaining items fail with insufficient_credits and the earlier ones still send.

Retrieve an SMS

GET/v1/sms/{id}

Returns the message object with segments, credits, scheduledAt and the event timeline.

The message object

Statuses

• queued: accepted and waiting for a worker. Usually under a second.
• sent: handed to Amazon SES or the mobile network.
• delivered: the receiving server or handset confirmed delivery.
• bounced and complained: email only. Both suppress the address.
• failed: permanent failure after retries. error says why.
• expired: SMS only. The network could not deliver within its validity period.
• rejected: blocked before sending, for example a suppressed address or a missing consent record.

Idempotency

Send an Idempotency-Key with any POST. For 24 hours the same key and body return the original response with an Idempotent-Replayed: true header. The same key with a different body or on a different channel returns 409. If a request fails before the message is queued, the key is released so your retry goes through.

# First request
curl https://api.sendbaze.com/v1/sms -H "Idempotency-Key: otp-4821-1" ...
# 200 { "id": "sm_01j9...", ... }

# Same key, same body, within 24 hours
curl https://api.sendbaze.com/v1/sms -H "Idempotency-Key: otp-4821-1" ...
# 200 { "id": "sm_01j9...", ... }   header: Idempotent-Replayed: true

# Same key, different body
# 409 { "error": { "code": "idempotency_conflict", ... } }

Rate limits

100 requests per second per organisation, shared across all its keys. The batch endpoints count as one request each, so bulk sends should use them. Above the limit the API returns 429 with Retry-After.

Test mode

Keys that start with sk_test_ run every validation and compliance check and return an id, but never enqueue, never debit credits and never send. Test messages appear in the logs with a test badge and in GET lookups with status sent. Use them in CI and staging.

Errors

Every error shares one envelope with a stable code. See the errors reference.