Skip to main content
AhaSend sub-accounts give each customer an isolated email account under one parent; this guide covers use cases, setup and billing. Included on Pro (up to 9 sub-accounts) and Max (no limit). There is no charge per sub-account: the volume of all sub-accounts counts on the parent’s plan. See plans and features. This model is built for platforms and agencies that send on behalf of many customers: provision a sub-account per customer, and let it use the full feature set of AhaSend in complete isolation, all billed back to the parent.

​
Why Use Sub-Accounts?

Full Sending Isolation

Each sub-account has its own domains, suppressions, reputation context, and sending activity. One customer’s sending never affects another’s.

Consolidated Billing

All sub-account usage rolls up to the parent account as a single invoice, with per-sub-account cost visibility.

The Full API, Per Customer

A sub-account API key authenticates as the child and can use every regular v2 endpoint: domains, messages, webhooks, routes, and more.

Central Control

Create, update, pause, resume, and soft-delete sub-accounts from the parent, view per-sub-account usage, and set an optional monthly sending cap on each one.

​
How It Works

Sub-accounts follow a parent and child model:
  • All sub-account management endpoints are addressed under the parent account ID, for example /v2/accounts/{account_id}/sub-accounts. The {account_id} is always the parent.
  • Each sub-account has its own child account ID (sub_account_id). Once a sub-account has its own API key, that key uses the child account ID on ordinary routes, for example /v2/accounts/{sub_account_id}/domains.
  • Sub-account API keys can only be created and managed with parent credentials that hold the right sub-account-api-keys:* scope. A sub-account cannot manage its own nested API keys.
From the parent account you stay in control end to end: manage the full lifecycle (create and update sub-accounts, pause, resume, and soft-delete), pull per-sub-account statistics with Get Sub-Account Usage, and, because the parent provisions the sub-account’s API keys, act on the sub-account’s behalf to manage anything inside it (domains, webhooks, sending, and more).
Each sub-account has an optional monthly_credit field, a monthly sending cap where 0 means no cap.

​
When to Use Sub-Accounts

Sub-Accounts are ideal when you send on behalf of distinct end customers and need each kept separate:
  • SaaS platforms giving each of their customers their own sending setup and domains.
  • Agencies managing email for multiple clients under one account and one bill.
  • Resellers who want isolation and per-customer usage reporting without running multiple top-level accounts.
  • Cloud and hosting providers offering transactional email as part of their platform, with a separate, isolated sending account provisioned per tenant.
  • Managed service providers (MSPs) running transactional email on behalf of the clients they manage, keeping each client’s sending, domains, and reputation cleanly separated and individually reportable.
For a single business sending its own transactional mail, a regular account with multiple domains is simpler and is the better fit.

​
Provisioning a Sub-Account

You provision a sub-account from the parent in two API calls: create the sub-account, then create its bootstrap API key. After that, the child key and child account ID are all you need to run that customer’s email.
1

Create the sub-account

With parent credentials, call POST /v2/accounts/{account_id}/sub-accounts using the parent account ID and a unique Idempotency-Key. The response id is the new sub_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 parent credential must hold the sub-account-api-keys:write scope. The 201 response returns a one-time secret_key.
3

Use the child key for that customer

Authenticate with the child secret_key and use the sub_account_id as the account_id on ordinary v2 routes. The child key acts as the sub-account and can use the full feature set in complete isolation.
The secret_key is shown only once, on creation, and is omitted from all later responses (exact idempotent replays within 5 minutes return the same value). Store it securely the moment you receive it.

​
Example: Provision, Verify a Domain, and Send

The flow below runs end to end: it provisions a sub-account with the parent key, then switches to the child key to verify a sending domain and send a message. It uses jq to capture the IDs and secret returned along the way.
Step 1 uses the parent credentials. Steps 2 and 3 use the child account ID and the child secret. Parent credentials are only needed to manage the sub-account itself and its API keys.
See Create Domain, Check Domain DNS, and Create Message for the full reference.

​
Sub-Account Status

See the API overview for sub-account status values.

​
Paused Domains

AhaSend can pause sending from a domain of a sub-account. The owners and admins of the parent account also get the pause email. The parent account can lift the pause. Fix the cause first, then use one of these:
  • Dashboard: go to Settings > Sub-accounts and open the sub-account. The Paused domains card lists each paused domain. Click Lift pause. The owners and admins of the parent account can do this.
  • API: call Unpause Sub-Account Domain with a parent API key that has the sub-accounts:suspend scope.

​
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:
  • Proportional allocation: each sub-account’s allocated_cost is a share of the parent’s pooled invoice for the period, distributed by message volume.
  • Not standalone pricing: allocated_cost reflects a proportional share of the parent’s pooled invoice, not what the sub-account would pay on its own plan.
  • Removed sub-accounts: usage from sub-accounts soft-deleted during the period is still billed to the parent and reported in a separate aggregate.

​
Scopes

Use parent-account keys with the sub-account permission scopes needed for each task.

​
Next Steps

Sub-Accounts API Overview

The full API model for managing sub-accounts and their keys

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
Sub-accounts are included on Pro (up to 9) and Max (no limit); DNS whitelabel is included on Max. See plan features, sub-accounts and DNS whitelabel, or contact sales for larger setups.