Watching your usage
GET /v1/usage
Scope tenant:read. One call, everything about where you stand:
{
"messages_sent_last_60s": 3,
"messages_sent_today_utc": 412,
"messages_sent_this_period": 18204,
"messages_sent_last_30d": 21655,
"monthly_included_sends": 30000,
"rate_cap_per_min": 10,
"mailboxes_active": 24,
"domains_verified": 2,
"bytes_stored": 8123456789
}
The two pairs that matter are messages_sent_last_60s against
rate_cap_per_min, and messages_sent_this_period against
monthly_included_sends. Everything else is context.
Read your cap, do not hardcode it. It is per plan, it changes on an
upgrade, and the reputation engine can lower it without you doing anything.
A client that assumes 60 because that was true when it was written will
start getting 429s it does not understand.
Pacing against the per-minute cap
messages_sent_last_60s is a rolling count over the same window the cap is
enforced on, so it is directly comparable:
remaining_this_minute = rate_cap_per_min - messages_sent_last_60s
That is a far better basis for a sender loop than counting your own sends, because it includes everything else sending on the workspace: the console, webmail, another worker, a colleague testing.
The others, and what each is for
| Endpoint | Scope | Answers |
|---|---|---|
GET /v1/usage |
tenant:read |
how much is left |
GET /v1/messages/stats |
send:read |
how sends are turning out |
GET /v1/reputation |
send:read |
whether your cap has been lowered, and why |
GET /v1/usage/storage |
tenant:read |
per-mailbox storage |
GET /v1/usage/report |
tenant:admin |
a longer window, for review rather than control |
If a 429 surprises you, GET /v1/reputation is the one to read. A cap
lowered by bounce rate looks identical to a cap you were always on, and only
that endpoint tells the two apart. See
Sender reputation.
Test sends do not count
Nothing sent with an lk_test_ key counts against the per-minute cap, the
monthly allowance, send units, warm-up or reputation. Every count filters
them out.
So you cannot load-test your pacing logic with a test key: it will never
produce the 429 you are trying to handle. See
Simulating failures for what can and cannot be
exercised.