← barua.tz

Reading emails#

The send log, newest first, 25 at a time and up to 100. Pages are keyset cursors rather than offsets: a log that gains rows while you walk it must not shift under you, so an integration polling for what happened since its last look neither reads a send twice nor misses one. Pass nextCursor back as cursor; it is null on the last page. Filter with status and since.

One email comes with events: what each receiving server did, per recipient, in the order it happened, straight from Barua's own mail server log. status: sent only says our server took the message; deliveredAt, bouncedAt and complainedAt are stamped as outcomes arrive, and a bounce can land days later. A sandboxed or failed send has no events.

GET /api/v1/emails

List sent emails. Scope emails:read.

The send log, newest first. Pages are keyset cursors rather than offsets, so a log that gains rows while you walk it does not shift under you.

curl
curl "https://barua.tz/api/v1/emails?status=sent&since=2026-09-01T00:00:00Z&limit=25" \
  -H "Authorization: Bearer barua_YOUR_KEY"
response 200
200, no body
422 invalid_requestThe body or query failed validation. The message names the first field that failed.
422 invalid_cursorcursor is not one the emails or suppressions list issued.

GET /api/v1/emails/{id}

Get one email with its delivery events. Scope emails:read.

The send as logged, plus events: what each receiving server did, per recipient, in the order it happened, from Barua's own mail server log. A sandboxed or failed send has no events.

curl
curl https://barua.tz/api/v1/emails/9b2e6d7a-3c4f-4e5a-9b1c-2d3e4f5a6b7c \
  -H "Authorization: Bearer barua_YOUR_KEY"
response 200
200
{
  "id": "9b2e6d7a-3c4f-4e5a-9b1c-2d3e4f5a6b7c",
  "from": "receipts@dukalangu.co.tz",
  "to": [
    "neema@gmail.com"
  ],
  "subject": "Receipt R-1042: TZS 25,000",
  "template": "receipt",
  "status": "sent",
  "error": null,
  "createdAt": "2026-09-24T08:15:30.412Z",
  "deliveredAt": "2026-09-24T08:15:33.901Z",
  "bouncedAt": null,
  "complainedAt": null,
  "sandbox": false,
  "events": [
    {
      "recipient": "neema@gmail.com",
      "status": "delivered",
      "dsn": "2.0.0",
      "detail": "250 2.0.0 OK 1758701733 a1b2c3d4e5 - gsmtp",
      "occurredAt": "2026-09-24T08:15:33.901Z"
    }
  ]
}
404 email_not_foundNo email with that id on this account.