Batch Sends

Send multiple official messages in a single request using the Taifa Mail batch API.

Batch sends let you deliver many individual official messages in one API call. Each email in the batch can have its own recipient, subject, and body.

POST /v1/emails/batch

The request body is a JSON array of email objects. Each object uses the same shape as a single send request (from_, to, subject, html, text, cc, bcc, reply_to, headers, tags, send_at).

curl -X POST https://govconnect.ke/v1/emails/batch \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "from_": {"email": "notices@health.go.ke", "name": "Ministry of Health"},
      "to": [{"email": "alice@example.com", "name": "Alice"}],
      "subject": "Clinic appointment reminder",
      "html": "<p>Hi Alice, this is a reminder for your clinic appointment.</p>",
      "tags": ["appointments"]
    },
    {
      "from_": {"email": "notices@health.go.ke", "name": "Ministry of Health"},
      "to": [{"email": "bob@example.com", "name": "Bob"}],
      "subject": "Clinic appointment reminder",
      "html": "<p>Hi Bob, this is a reminder for your clinic appointment.</p>",
      "tags": ["appointments"]
    }
  ]'

Response

The endpoint returns 202 Accepted:

{
  "total": 2,
  "sent": 2,
  "failed": 0,
  "results": [
    {
      "id": "3f8c1e2a-9b4d-4c7e-8a1f-2d6b5e9c0a3d",
      "status": "queued",
      "rejection_reason": null
    },
    {
      "id": "7a2d5b9c-0e3f-4c1a-8b6d-9e4f2c5a0d3b",
      "status": "queued",
      "rejection_reason": null
    }
  ]
}

Field	Description
`total`	Number of emails in the batch.
`sent`	Count of emails successfully queued or scheduled.
`failed`	Count of emails that could not be accepted.
`results`	One entry per email, in request order. Failed entries have `id: null`, `status: "error"`, and a `rejection_reason`.

Each email in the batch is processed independently. A failure on one email does not stop the rest.

Batch size limit

A single batch request can contain up to 500 emails. This is a flat anti-abuse cap that applies to every account.

An empty array, or one that exceeds the 500-email cap, returns 400 Bad Request. For larger sends, split them into multiple batch requests.

The batch endpoint can also schedule: include send_at on any email in the array. See Scheduling Emails.

Batch Sends

POST /v1/emails/batch

Response

Batch size limit

On this page