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.

Available to Platform Partners. Contact sales for access. 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.

Platform Partner feature: Sub-Accounts is part of our Platform Partner capabilities and is currently in early access. Contact us to enable it on your account.

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, suspend, unsuspend, 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, suspend, unsuspend, 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.

1. Provision

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')"

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.

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 and DNS whitelabel are available to Platform Partners. See plan features, sub-accounts, and DNS whitelabel, or contact sales.

Related Guides

• API authentication, Send-only API keys, Sub-account API rules.
• Sub-account CLI, Child API keys, Plans and limits.
• Suppression durations.