Taifa MailTaifa Mail Docs
Sending Emails

Batch Sends

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

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

Batch sending requires the Starter plan or above. Free plan callers receive a 403 Forbidden.

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": "hello@yourdomain.com", "name": "Your Company"},
      "to": [{"email": "alice@example.com", "name": "Alice"}],
      "subject": "Your invoice is ready",
      "html": "<p>Hi Alice, your invoice is attached.</p>",
      "tags": ["invoices"]
    },
    {
      "from_": {"email": "hello@yourdomain.com", "name": "Your Company"},
      "to": [{"email": "bob@example.com", "name": "Bob"}],
      "subject": "Your invoice is ready",
      "html": "<p>Hi Bob, your invoice is attached.</p>",
      "tags": ["invoices"]
    }
  ]'

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
    }
  ]
}
FieldDescription
totalNumber of emails in the batch.
sentCount of emails successfully queued or scheduled.
failedCount of emails that could not be accepted.
resultsOne 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 limits

The maximum number of emails per batch depends on your plan:

PlanMax batch size
FreeNot available
Starter25
Pro50
Business100

An empty array, or one that exceeds the plan limit, 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. Scheduled delivery itself requires the Starter plan or above. See Scheduling Emails.

Previous

Scheduling Emails

Next

Deliverability Best Practices

On this page