> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazobiamail.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage and limits

> Read your email balance, subscription and invoices from the API — what is left of the plan allowance, what you bought, and where the units went.

# Usage and limits

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

1. **The plan allowance** — units included with your monthly plan. They reset
   each billing period and unused units do not carry over.
2. **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.

```bash theme={null}
curl https://app.wazobiamail.com/api/v1/status \
  -H "X-API-Key: $WAZOBIA_API_KEY"
```

```json theme={null}
{
  "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](https://docs.wazobiamail.com/docs/guides/api-keys.md).

## 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.

```bash theme={null}
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](https://docs.wazobiamail.com/docs/guides/billing.md) 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](https://docs.wazobiamail.com/docs/guides/domains.md).
* `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](https://docs.wazobiamail.com/docs/guides/mailboxes.md).

## 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](https://docs.wazobiamail.com/docs/guides/api-keys.md) 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.

> [card] [API keys](https://docs.wazobiamail.com/docs/guides/api-keys.md)
>
> Dashboard keys, sending keys and their permissions.

> [card] [Billing](https://docs.wazobiamail.com/docs/guides/billing.md)
>
> Paying, renewals and credit purchases.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.