Sub-accounts · Barua API

Sub-accounts#

If you send for other businesses, open a sub-account for each. A sub-account is an account of its own: its own domains, keys, suppression list, daily quota, reputation counters and suspension. A customer whose list goes bad is throttled or paused alone instead of pausing everyone you serve. Money is the exception: credits are checked and charged against you, the parent, because you are the one with a balance. Your own standing counts too: a parent that is suspended or over quota cannot send through its children, and their recipients count against your quota and reputation as well as theirs. One level only: a sub-account cannot open sub-accounts.

Any endpoint acts for a sub-account when the request carries X-Barua-Account: <id>. Your key's own scopes still apply. An id that is not a sub-account of your account answers 404 account_not_found, the same as an id that does not exist, so ids cannot be probed. GET /api/v1/account returns whichever account the request is acting for.

To give a customer a key of their own, mint one with the header set. The key belongs to the sub-account, holds at most your key's scopes, and is used without the header from then on:

curl https://barua.tz/api/v1/keys \
  -H "Authorization: Bearer barua_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Barua-Account: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "name": "Mama Ntilie production",
    "scopes": [
      "emails:send",
      "emails:read"
    ]
  }'

Suspending needs a reason of at least 15 characters, because the sub-account sees it verbatim as the message on every refused send: say what happened and what would lift it. Only a suspension placed through the API can be lifted through the API. One placed by Barua, or one whose own bounce or complaint rates still grade as paused, answers 409 conflict and is a matter for support, because that pause protects the reputation every sender shares.

On the account object, sending.tier (healthy, warning, throttled, paused) is graded from lifetime bounce and complaint rates once 50 emails have been sent, and effectiveQuota is dailyQuota or a tenth of it while throttled. credits on a sub-account is its own row and stays at zero because you are charged instead; read your own account for the balance that matters. Deleting a sub-account deletes everything under it, with no undo.

GET /api/v1/account

Get the account this request acts for. Scope accounts:read.

The key's own account, or the sub-account named in X-Barua-Account: one call to read a customer's standing the same way you read your own.

curl https://barua.tz/api/v1/account \
  -H "Authorization: Bearer barua_YOUR_KEY" \
  -H "X-Barua-Account: 7c9e6679-7425-40de-944b-e07fc1f90ae7"

200
{
  "id": "1d2c3b4a-5f6e-4d7c-8b9a-0f1e2d3c4b5a",
  "name": "Duka Langu",
  "parentId": null,
  "createdAt": "2026-08-01T09:12:00.000Z",
  "sending": {
    "tier": "healthy",
    "totalSent": 1284,
    "totalBounced": 6,
    "totalComplained": 0,
    "sentToday": 37,
    "dailyQuota": 500,
    "effectiveQuota": 500,
    "suspended": false
  },
  "credits": {
    "balance": 3716,
    "state": "ok",
    "freeUntil": null,
    "graceDaysLeft": 0,
    "graceEmailsLeft": 0,
    "totalPurchased": 5000,
    "totalUsed": 1284
  }
}

404 not_foundNo domain, sub-account or key with that id on this account.

GET /api/v1/accounts

List sub-accounts. Scope accounts:read.

curl https://barua.tz/api/v1/accounts \
  -H "Authorization: Bearer barua_YOUR_KEY"

200, no body

422 invalid_requestThe body or query failed validation. The message names the first field that failed.

POST /api/v1/accounts

Open a sub-account. Scope accounts:write.

One per customer. A sub-account has its own domains, keys, suppression list, quota, reputation and suspension; its sends are paid for with the parent's credits. One level only: a sub-account cannot open sub-accounts, so do not send X-Barua-Account with this call. Up to 200 sub-accounts per account.

curl https://barua.tz/api/v1/accounts \
  -H "Authorization: Bearer barua_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mama Ntilie Catering"
  }'

201
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Mama Ntilie Catering",
  "parentId": "1d2c3b4a-5f6e-4d7c-8b9a-0f1e2d3c4b5a",
  "createdAt": "2026-09-24T10:02:11.000Z",
  "sending": {
    "tier": "healthy",
    "totalSent": 0,
    "totalBounced": 0,
    "totalComplained": 0,
    "sentToday": 0,
    "dailyQuota": 500,
    "effectiveQuota": 500,
    "suspended": false
  },
  "credits": {
    "balance": 0,
    "state": "trial",
    "freeUntil": null,
    "graceDaysLeft": 3,
    "graceEmailsLeft": 300,
    "totalPurchased": 0,
    "totalUsed": 0
  }
}

400 invalid_jsonThe request body could not be parsed as JSON.

404 not_foundNo domain, sub-account or key with that id on this account.

409 conflictA sub-account tried to open a sub-account, or a suspension cannot be lifted from the API: it was placed by Barua rather than through the API, or the sub-account's own bounce and complaint rates still grade as paused.

409 limit_reachedThe account already has 200 sub-accounts, or 50 live keys.

422 invalid_requestThe body or query failed validation. The message names the first field that failed.

GET /api/v1/accounts/{id}

Get a sub-account. Scope accounts:read.

curl https://barua.tz/api/v1/accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer barua_YOUR_KEY"

200
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Mama Ntilie Catering",
  "parentId": "1d2c3b4a-5f6e-4d7c-8b9a-0f1e2d3c4b5a",
  "createdAt": "2026-09-24T10:02:11.000Z",
  "sending": {
    "tier": "healthy",
    "totalSent": 0,
    "totalBounced": 0,
    "totalComplained": 0,
    "sentToday": 0,
    "dailyQuota": 500,
    "effectiveQuota": 500,
    "suspended": false
  },
  "credits": {
    "balance": 0,
    "state": "trial",
    "freeUntil": null,
    "graceDaysLeft": 3,
    "graceEmailsLeft": 300,
    "totalPurchased": 0,
    "totalUsed": 0
  }
}

404 not_foundNo domain, sub-account or key with that id on this account.

POST /api/v1/accounts/{id}/suspend

Stop or restart a sub-account's sending. Scope accounts:write.

The reason is not a note to you: it is the exact message the sub-account gets on every refused send, so say what happened and what would lift it. Only a suspension placed through the API can be lifted through the API. One placed by Barua, whether by an operator or by the reputation breaker, and one whose bounce or complaint rates still grade as paused, is refused and pointed at support.

curl https://barua.tz/api/v1/accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/suspend \
  -H "Authorization: Bearer barua_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "suspended": true,
    "reason": "Invoices bounced at three customers this morning. Lifted once the address list has been checked."
  }'

200
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Mama Ntilie Catering",
  "parentId": "1d2c3b4a-5f6e-4d7c-8b9a-0f1e2d3c4b5a",
  "createdAt": "2026-09-24T10:02:11.000Z",
  "sending": {
    "tier": "healthy",
    "totalSent": 0,
    "totalBounced": 0,
    "totalComplained": 0,
    "sentToday": 0,
    "dailyQuota": 500,
    "effectiveQuota": 500,
    "suspended": true,
    "suspendedReason": "Invoices bounced at three customers this morning. Lifted once the address list has been checked."
  },
  "credits": {
    "balance": 0,
    "state": "trial",
    "freeUntil": null,
    "graceDaysLeft": 3,
    "graceEmailsLeft": 300,
    "totalPurchased": 0,
    "totalUsed": 0
  }
}

400 invalid_jsonThe request body could not be parsed as JSON.

404 not_foundNo domain, sub-account or key with that id on this account.

422 invalid_requestThe body or query failed validation. The message names the first field that failed.

DELETE /api/v1/accounts/{id}

Delete a sub-account. Scope accounts:write.

Deletes the sub-account and everything under it: keys, domains, send log, counters, credit, webhooks. There is no soft delete and no undo.

curl -X DELETE https://barua.tz/api/v1/accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer barua_YOUR_KEY"

204, no body

404 not_foundNo domain, sub-account or key with that id on this account.