> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# Sub-Accounts for SaaS Platforms and Agencies

> Give each customer an isolated AhaSend sub-account with its own domains, API keys and reputation, under one parent with consolidated billing.

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](https://ahasend.com/docs/facts.md#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?

> [card] Full Sending Isolation
>
> Each sub-account has its own domains, suppressions, reputation context, and sending activity. One customer's sending never affects another's.

> [card] Consolidated Billing
>
> All sub-account usage rolls up to the parent account as a single invoice, with per-sub-account cost visibility.

> [card] 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.

> [card] 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](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account.md) and [update](https://ahasend.com/docs/api-reference/sub-accounts/update-sub-account.md) sub-accounts, pause, resume, and soft-delete), pull per-sub-account statistics with [Get Sub-Account Usage](https://ahasend.com/docs/api-reference/sub-accounts/get-sub-accounts-usage.md), 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).

> [!NOTE]
>
> 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`](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account) 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`](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account-api-key) 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.

> [!WARNING]
>
> 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.

```bash 1. Provision theme={null}
PARENT_ACCOUNT_ID="your-parent-account-id"
PARENT_SECRET="aha-sk-parent-64-character-key"

# Create the sub account and capture its account ID
CHILD_ACCOUNT_ID="$(curl -sS -X POST "https://api.ahasend.com/v2/accounts/${PARENT_ACCOUNT_ID}/sub-accounts" -H "Authorization: Bearer ${PARENT_SECRET}" -H "Content-Type: application/json" -H "Idempotency-Key: subacct-20240101-acme" -d '{"name":"Acme Subsidiary","website":"acme.example.com"}' | jq -r '.id')"

# Create its bootstrap API key and capture the one-time secret (shown only once)
CHILD_SECRET="$(curl -sS -X POST "https://api.ahasend.com/v2/accounts/${PARENT_ACCOUNT_ID}/sub-accounts/${CHILD_ACCOUNT_ID}/api-keys" -H "Authorization: Bearer ${PARENT_SECRET}" -H "Content-Type: application/json" -H "Idempotency-Key: child-bootstrap-key-20240101-acme" -d '{"label":"Bootstrap key","scopes":["domains:read","domains:write","messages:send:all"]}' | jq -r '.secret_key')"
```

```bash 2. Verify a domain theme={null}
# From here on, use the CHILD account ID and CHILD secret

# Add a sending domain to the sub account
curl -sS -X POST "https://api.ahasend.com/v2/accounts/${CHILD_ACCOUNT_ID}/domains" -H "Authorization: Bearer ${CHILD_SECRET}" -H "Content-Type: application/json" -d '{"domain":"mail.acme.example.com"}'

# Add the returned DNS records at your DNS provider, then trigger a validation check
curl -sS -X POST "https://api.ahasend.com/v2/accounts/${CHILD_ACCOUNT_ID}/domains/mail.acme.example.com/check-dns" -H "Authorization: Bearer ${CHILD_SECRET}"
```

```bash 3. Send theme={null}
# Once the domain is verified, send as the sub account
curl -sS -X POST "https://api.ahasend.com/v2/accounts/${CHILD_ACCOUNT_ID}/messages" -H "Authorization: Bearer ${CHILD_SECRET}" -H "Content-Type: application/json" -d '{"from":{"email":"noreply@mail.acme.example.com","name":"Acme"},"recipients":[{"email":"user@example.com","name":"Jane Doe"}],"subject":"Welcome to Acme","text_content":"Thanks for signing up!"}'
```

> [!NOTE]
>
> 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](https://ahasend.com/docs/api-reference/domains/create-domain.md), [Check Domain DNS](https://ahasend.com/docs/api-reference/domains/check-dns.md), and [Create Message](https://ahasend.com/docs/api-reference/messages/create-message.md) for the full reference.

## Sub-Account Status

See the API overview for [sub-account status values](https://ahasend.com/docs/api-reference/sub-accounts/overview.md#sub-account-status).

## Paused Domains

AhaSend can [pause sending from a domain](https://ahasend.com/docs/domains.md#why-is-sending-paused-on-my-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](https://ahasend.com/docs/api-reference/sub-accounts/unpause-sub-account-domain.md) with a parent API key that has the `sub-accounts:suspend` scope.

## Usage and Billing

The [usage endpoint](https://ahasend.com/docs/api-reference/sub-accounts/get-sub-accounts-usage.md) 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](https://ahasend.com/docs/api-reference/sub-accounts/overview.md#scopes) needed for each task.

## Next Steps

> [card] [Sub-Accounts API Overview](https://ahasend.com/docs/api-reference/sub-accounts/overview.md)
>
> The full API model for managing sub-accounts and their keys

> [card] [Create a Sub-Account](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account.md)
>
> Provision a new isolated child account under your parent account

> [card] [Create a Sub-Account API Key](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account-api-key.md)
>
> Issue a bootstrap key that authenticates as the child account

> [card] [Sub-Account Usage](https://ahasend.com/docs/api-reference/sub-accounts/get-sub-accounts-usage.md)
>
> 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](https://ahasend.com/docs/facts.md#plans-and-features), [sub-accounts](https://ahasend.com/docs/scale/sub-accounts.md) and [DNS whitelabel](https://ahasend.com/docs/scale/dns-whitelabel.md), or [contact sales](mailto:sales@ahasend.com) for larger setups.

## Related Guides

* [API authentication](https://ahasend.com/docs/api-reference/authentication.md), [Send-only API keys](https://ahasend.com/docs/send-api/credentials.md), [Sub-account API rules](https://ahasend.com/docs/api-reference/sub-accounts/overview.md).
* [Sub-account CLI](https://ahasend.com/docs/cli/commands/subaccounts.md), [Child API keys](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account-api-key.md), [Plans and limits](https://ahasend.com/docs/facts.md).
* [Suppression durations](https://ahasend.com/docs/bounces.md#suppression-duration).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.