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_API_KEY"
response 200
{
"data": [
{
"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
}
],
"nextCursor": null
}
  • 422 invalid_requestThe body or query failed validation. The message names the first field that failed.
  • 422 invalid_cursorcursor is not one this list issued: pass back the nextCursor it gave you, unchanged.

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_API_KEY"
response 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.

Something unclear or wrong? That is a bug in these docs. Write to support@barua.tz.