Reference
Sub-accounts
If you send mail on behalf of your own clients, a sub-account gives each of them a real, separate Posthaste account — their own domains, their own API keys, and above all their own suppression list — while everything stays on your plan and your one invoice.
They are genuinely separate
A sub-account is not a label or a folder. It is an ordinary account with its own account id, and every isolation rule in Posthaste applies to it exactly as it would to a stranger’s account. That means:
| Between sub-accounts | What happens |
|---|---|
| One client’s key reading another’s messages | Refused. Not filtered — invisible. |
| An unsubscribe on one client | Applies to that client only. It can never silence another client’s password reset, which is usually the whole reason to use these. |
| Domains, API keys, webhooks, statistics | Separate per sub-account. |
| Sending reputation | Each warms up on its own ladder, so a new client cannot inherit volume it has not earned. |
Paying for an account does not let you read its mail. Your own key cannot fetch a sub-account’s messages, and this is deliberate rather than an oversight: your clients’ recipients are real people, and the billing relationship is not their consent.
What you can see is what a payer needs — the name, the status, and how much it has sent this month. To work inside a sub-account, sign in to it.
One bill, one allowance
A sub-account inherits your plan and cannot hold a subscription of its own. Change your plan and every sub-account moves with it.
The monthly allowance is shared across the whole family. If you are on a plan with 300,000 emails a month, that is 300,000 between you and all of your sub-accounts together — not 300,000 each. Sub-accounts are an isolation feature, not a volume discount, and the price you pay tracks the mail you actually send.
If your subscription lapses, the downgrade applies to the family. If your account is suspended, its sub-accounts are suspended with it.
Creating one
/v1/sub-accountsdashboard session only| Field | Type | Notes |
|---|---|---|
| name | string required | What you call this client. Shown on your own list, never to their recipients. |
POST /v1/sub-accounts
{ "name": "Acme Ltd" }
{
"id": "acct_AZLm…",
"name": "Acme Ltd",
"plan": "scale", // inherited from you, not chosen
"status": "active"
}Creating a sub-account requires a signed-in owner or admin — an API key cannot do it, however it is scoped. It adds to what you are paying for, and that belongs with the other actions a person takes rather than a credential sitting on a server.
How many you may have depends on your plan: Free none, Starter none, Growth 5, Scale 25, Enterprise unlimited. Exceeding it returns 403 with "type": "sub_account_limit_reached", carrying the limit and how many you have. A sub-account cannot itself have sub-accounts.
Seeing what you pay for
/v1/sub-accountsaccount:read/v1/sub-accounts/:idaccount:readGET /v1/sub-accounts
{
"data": [
{ "id": "acct_AZLm…", "name": "Acme Ltd",
"status": "active", "sentThisMonth": 12480 }
]
}sentThisMonth is what that client has sent so far this month, which is what you need to see which of them is consuming the allowance.
NextTeam and roles →Invite colleagues, what each role may do, and the actions no API key can perform.