Skip to main content
Sub accounts let a parent account create and manage isolated child accounts under a single billing relationship. Each sub account has its own domains, members, suppressions, and sending activity, while the parent account retains administrative control and consolidated billing. This model is built for platforms and agencies that send on behalf of many customers: provision a sub account per customer, issue that sub account its own API key, and let it use the full v2 API in isolation — all billed back to the parent.

​
Overview

From the parent account you can:
  • Manage the sub account lifecycle — create, read, update, suspend, unsuspend, and soft-delete sub accounts
  • Provision sub-account API keys — create a bootstrap API key that authenticates as the child account
  • Track usage and cost — read per-sub-account message volume and the proportional share of the parent’s invoice allocated to each sub account
All sub-account endpoints are addressed under the parent account ID, for example /v2/accounts/{account_id}/sub-accounts. The {account_id} path parameter is always the parent account, and {sub_account_id} identifies the child.

​
Sub account status

Each sub account reports a status field:
StatusMeaning
activeThe sub account is operating normally.
suspendedThe sub account was suspended directly via the suspend endpoint.
parent-suspendedThe sub account is suspended because its parent account is suspended.
deletedThe sub account has been soft-deleted.
The monthly_credit field is an optional monthly cap on the sub account, where 0 means no cap.

​
Provisioning a sub account

Stand up a new sub account and give it its own credentials in two calls, then use the returned child secret for all of that customer’s traffic.
1

Create the sub account

Call POST /v2/accounts/{account_id}/sub-accounts with the parent account ID and a unique Idempotency-Key. Capture the id from the response — this is the sub_account_id (the child account ID).
2

Create a bootstrap API key

Call POST /v2/accounts/{account_id}/sub-accounts/{sub_account_id}/api-keys with the parent account ID, the new sub_account_id, and a different unique Idempotency-Key. The credential you use must belong to the parent account and hold the sub-account-api-keys:write scope.
3

Store the one-time secret

The 201 response includes a one-time secret_key. Store it immediately — it is omitted from all list, get, update, and delete responses. Exact idempotent replays within 5 minutes return the same secret_key; after that window it cannot be retrieved again.
4

Send as the child account

Use the child secret_key as the bearer token and the sub_account_id as the account_id on ordinary v2 routes (for example GET /v2/accounts/{sub_account_id}/domains). The child key authenticates as the sub account and is scoped to its resources.
Sub-account API keys can only be managed with parent credentials that hold the relevant sub-account-api-keys:* scope. A sub account’s own credentials cannot create or manage its nested API keys.

​
Usage and billing

The usage endpoint returns current billing-period message volume and the proportional cost allocated to the parent and each active sub account:
  • allocation_method is proportional — each allocated_cost is a share of the parent’s pooled invoice for the period, distributed by message volume.
  • allocated_cost is not standalone pricing. As the allocation_note disclaimer states, it reflects a proportional share of the parent’s pooled invoice, not what the sub account would pay on its own plan.
  • removed_sub_accounts aggregates usage from sub accounts that were soft-deleted during the current period. That usage is still billed to the parent and is not attributed to individual sub accounts.
  • total is the combined parent, active sub-account, and removed-sub-account usage for the period.
Soft-deleted sub accounts are excluded from the list endpoint. Usage they accrued before deletion in the current period is still reported through the removed_sub_accounts aggregate.

​
Idempotency

The create endpoints — create sub account and create sub-account API key — accept an Idempotency-Key header for safe retries. Because the API-key create response carries a one-time secret_key, its idempotent replay is only available for 5 minutes; other create responses are replayable for 24 hours. See Request Idempotency for the full retry model.

​
Scopes

Sub-account operations require dedicated scopes, all granted to parent-account API keys:
ScopeGrants
sub-accounts:readList and read sub accounts
sub-accounts:writeCreate and update sub accounts
sub-accounts:deleteSoft-delete sub accounts
sub-accounts:suspendSuspend and unsuspend sub accounts
sub-accounts:usageRead per-sub-account usage and allocated cost
sub-account-api-keys:readList and read sub-account API keys
sub-account-api-keys:writeCreate and update sub-account API keys
sub-account-api-keys:deleteDelete sub-account API keys
See the Scopes reference for how scopes are evaluated.

​
Getting Started

Create a Sub Account

Provision a new isolated child account under your parent account

Create a Sub-Account API Key

Issue a bootstrap key that authenticates as the child account

Sub-Account Usage

Track per-sub-account volume and allocated cost for the billing period

Scopes

Understand the scopes that control sub-account access