Usage and limits

Sending spends email units. A balance is made of two parts that are spent in a fixed order:

The plan allowance — units included with your monthly plan. They reset each billing period and unused units do not carry over.
Purchased credits — units you bought. They never expire, so they are the buffer that keeps sending alive when a pay-as-you-go month runs past the plan.

The allowance is always spent first. That is why a healthy purchasedBalance with an exhausted includedRemaining still sends: the account has moved on to its credits.

One call for the whole picture

GET /api/v1/status is the snapshot most integrations need. It returns the plan and the balance together, and it is the endpoint the dashboard reads.

curl https://app.wazobiamail.com/api/v1/status \
  -H "X-API-Key: $WAZOBIA_API_KEY"

{
  "success": true,
  "message": "Account status retrieved successfully",
  "data": {
    "plan": {
      "id": "pro",
      "name": "Pro Plan",
      "status": "active",
      "billingInterval": "monthly",
      "startDate": "2026-10-01T00:00:00",
      "endDate": "2026-11-01T00:00:00",
      "autoRenew": true
    },
    "units": {
      "monthlyAllocation": 10000,
      "subscriptionUsed": 2500,
      "subscriptionRemaining": 7500,
      "purchasedBalance": 5000,
      "totalRemaining": 12500,
      "unlimited": false
    }
  }
}

Field	Meaning
`monthlyAllocation`	Units the plan includes this period.
`subscriptionUsed`	Units already spent from the allowance this period.
`subscriptionRemaining`	Allowance left before credits are touched.
`purchasedBalance`	Credits bought and still available.
`totalRemaining`	`subscriptionRemaining` + `purchasedBalance` — what you can send.
`unlimited`	True on plans with no monthly cap.

This call needs status:read. A dashboard key has every permission, so it works without further setup; see API keys.

The balance on its own

GET /api/v1/units/summary returns only the units block, plus canBuyCredits, which tells you whether a credit purchase is currently offered (purchases pause while an invoice is unpaid). It needs units:read.

Where the units went

GET /api/v1/units/ledger lists every movement, newest first: plan allowances, sending usage, purchases and adjustments. Each entry carries quantity (negative when units were spent), balanceAfter, source, reference and reason, which is exactly what the dashboard’s Credit history shows.

curl "https://app.wazobiamail.com/api/v1/units/ledger?per_page=25&status=purchase" \
  -H "X-API-Key: $WAZOBIA_API_KEY"

Page with page and per_page (1–100). Filter with status to one source, and use search to match a reference such as an invoice id. Requires units:read.

Buying more

GET /api/v1/units/packs is public and lists the fixed packs with their prices in kobo and cents. POST /api/v1/units/purchases creates an invoice for credits and returns its id. Nothing is charged at that moment, and credits are added only after the payment is verified:

Send packId for a fixed pack, or units for a custom quantity. The minimum purchase is ₦2,000 or $3.
Without an active paid subscription, planId is required and the monthly plan is added to the same invoice.
Prices are always calculated on the server; a client-supplied price is never accepted.

Requires units:write. Billing covers the payment flow and what the invoice looks like.

The subscription behind the allowance

GET /api/v1/subscriptions/current returns the active subscription for a product — plan id, name, prices, billing interval, period dates, renewal state — or null when the account has none. product defaults to wazobiamail; the only other accepted value is commanda. Requires subscriptions:current:read. The plan catalogue itself is public at GET /api/v1/plans.

Invoices

GET /api/v1/billing/invoices lists the account’s invoices newest first, up to 200, each with amount, currency, status, purpose, due date and payment date. Download a single one as a PDF through GET /api/v1/billing/invoices/{id}/download. Both need billing:invoices:read, and an account can only ever see its own invoices.

Domains and mailbox space

The same key reports the resources your plan pays for:

GET /api/v1/sending/domains lists sending domains with their verification state — see Domains.
GET /api/v1/mailboxes lists hosted mailboxes.
GET /api/v1/mailboxes/storage adds what the numbers alone do not show: per mailbox usedBytes, quotaBytes and remainingBytes, the account’s storage budget, and per-domain totals. Service addresses such as admin@ do not count toward the mailbox allowance, but their storage does.

The domain list requires sending:domains:read. Both mailbox reads need mailboxes:read; creating and changing mailboxes needs mailboxes:write. See Mailboxes.

Which key to use

Every operation on this page needs a dashboard API key. A scoped sending key created through POST /api/v1/sending/api-keys sends email and nothing else — it gets 401 here. API keys compares the two. A 403 means the key is valid but lacks the permission named on the endpoint, or that the account is not on a WazobiaMail plan. Missing permissions are fixed by creating a key with the right scope; plan problems are fixed in the dashboard.

API keys

Dashboard keys, sending keys and their permissions.

Billing

Paying, renewals and credit purchases.

Start here

SDKs & libraries

Everyday email

Sending

Enterprise

Account

Usage and limits

Usage and limits

One call for the whole picture

The balance on its own

Where the units went

Buying more

The subscription behind the allowance

Invoices

Domains and mailbox space

Which key to use

API keys

Billing

​Usage and limits

​One call for the whole picture

​The balance on its own

​Where the units went

​Buying more

​The subscription behind the allowance

​Invoices

​Domains and mailbox space

​Which key to use

API keys

Billing

Usage and limits

One call for the whole picture

The balance on its own

Where the units went

Buying more

The subscription behind the allowance

Invoices

Domains and mailbox space

Which key to use