GET /v1/mail/allowance
What the caller's plan grants for mailboxes.
Authentication
Send an API key as a bearer token. The key must carry the mail.view permission; a key without it is refused with 403, not 404.
Where your organisation id goes
This endpoint takes org_id as a query parameter. Leave it out and the call covers your whole tenancy subtree; send it to narrow the call to one organisation.
Your organisation id is on the API keys screen in your dashboard, beside the key itself. It is the same id in every call you make.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X GET https://api.zinndigital.com/v1/mail/allowance \
-H "Authorization: Bearer zdk_live_…"Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
The preflight the "set up email" screen reads: whether the governing plan includes mailboxes, how large each one is, and how many a domain may have. Reports rather than refuses — an organization with no plan gets included: false and an upgrade prompt, not an error, because this is a read screen. Resolution walks up the parent_org chain, so a reseller's client organization inherits the reseller's plan (CLAUDE.md §2.3). source names where the answer came from. mailbox_limit is the smaller of the plan's mailboxes grant and the platform abuse ceiling, so it does vary by plan; -1 means both are uncapped. Requires mail.view. ⭐ Pass fqdn whenever the question is about one domain, which is nearly always. Since the owner's ruling of 2026-08-16 a domain registered with us — or transferred in — grants free mailboxes on itself, whatever the organization's hosting plan says, and that grant is only reachable when the hostname is supplied. Without fqdn this endpoint answers the narrower question "does anything the organization owns include mail at all", and a customer whose only product is a domain gets included: false followed by a successful mailbox creation — a screen disagreeing with its own API.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
org_id (query) | Uuid | No | The organization to resolve for; defaults to the caller's own when unambiguous. |
fqdn (query) | string | No | Resolve for this hostname. Adds the domain source — free mailboxes on a domain we hold the registration for. |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
offered_providers | MailProvider[] | Yes | The providers this organization may set a domain up on, in picker order — the one producer of the white-label rule (W40-MAIL). zinn is absent, not disabled, for an… |
included | boolean | Yes | Whether the plan includes mailboxes at an operable size. |
box_quota_mb | integer | Yes | Per-mailbox size in MB. 0 means no per-mailbox cap. |
mailbox_limit | integer | Yes | Mailboxes allowed per domain; -1 is uncapped. The smaller of the plan's mailboxes grant and the platform abuse ceiling: a plan may lower it, and a generous plan can never… |
source | string<staff, subscription, trial, domain, free, none> | Yes | Where the allowance came from. domain means the domain itself grants it — it is registered with us or was transferred in, so its mailboxes are free whatever the… |
Errors this endpoint can return
401 · 403 · 422 · 429