ahasend subaccounts: Manage Sub-Accounts

AhaSend CLI sub-account commands let Platform Partners manage child accounts and their API keys from a parent account.

Prerequisites

Use a full parent-account API key with the matching sub-account scopes: sub-accounts:read, sub-accounts:write, sub-accounts:delete, sub-accounts:suspend (also for unpause-domain) and sub-accounts:usage, and for keys sub-account-api-keys:read, sub-account-api-keys:write and sub-account-api-keys:delete. Sub-accounts are available to Platform Partners; contact sales about access. The shell examples need Bash and jq.

Create and Manage a Test Sub-Account

The examples that use $TEST_SUBACCOUNT_ID make one Bash script: this one, the first one in Manage a Test Sub-Account API Key and the one in Delete the Test Sub-Account. Save them in that order. The script stops if creation fails, and only updates or deletes the test account it creates. The other examples use placeholders: replace YOUR_RESOURCE_ID with a sub-account ID and YOUR_KEY_ID with the ID of one of its API keys.

set -euo pipefail
TEST_SUBACCOUNT_ID=$(ahasend subaccounts create --name "Docs test" --website example.com --monthly-credit 100 --output json | jq -er '.id')
ahasend subaccounts list
ahasend subaccounts get "$TEST_SUBACCOUNT_ID"
ahasend subaccounts update "$TEST_SUBACCOUNT_ID" --name "Docs updated test"
ahasend subaccounts suspend "$TEST_SUBACCOUNT_ID" --reason "Docs suspension test" --force
ahasend subaccounts unsuspend "$TEST_SUBACCOUNT_ID"
ahasend subaccounts usage

--website takes a domain, such as example.com. An http or https URL also works: the command sends only its host, in lowercase. --output json prints the API’s response, so jq reads the new sub-account’s id from it. Usage allocated_cost is a proportional share of the parent’s pooled invoice, not standalone pricing. A monthly credit of 0 means no cap. suspend asks for confirmation unless you pass --force; a script needs it. pause is an alias of suspend, and resume and unpause are aliases of unsuspend. A suspension that AhaSend started can only be lifted by AhaSend support.

Manage a Test Sub-Account API Key

Continue with the sub-account created above. Store the one-time secret_key securely if an application needs it; this test keeps only the key ID.

TEST_KEY_ID=$(ahasend subaccounts api-keys create "$TEST_SUBACCOUNT_ID" --label "Docs test key" --scope accounts:read --output json | jq -er '.id')
ahasend subaccounts api-keys list "$TEST_SUBACCOUNT_ID"
ahasend subaccounts api-keys get "$TEST_SUBACCOUNT_ID" "$TEST_KEY_ID"
ahasend subaccounts api-keys update "$TEST_SUBACCOUNT_ID" "$TEST_KEY_ID" --label "Docs updated key"
ahasend subaccounts api-keys delete "$TEST_SUBACCOUNT_ID" "$TEST_KEY_ID" --force

subaccounts apikeys is an alias of subaccounts api-keys. A sub-account’s key cannot have the sub-accounts: or sub-account-api-keys: scopes; asking for one fails with exit code 4 before any request. A scope ending in {domain} takes one of the sub-account’s domains, such as messages:send:{example.com}. --scope and --ip-allow-list can be repeated, and each splits on commas. To limit a key to one network, or to allow it from any IP again:

ahasend subaccounts api-keys update YOUR_RESOURCE_ID YOUR_KEY_ID --ip-allow-list 203.0.113.0/24
ahasend subaccounts api-keys update YOUR_RESOURCE_ID YOUR_KEY_ID --clear-ip-allow-list

Unpause a Sub-Account Domain

AhaSend pauses a domain, for example when too many of its recent emails bounced. To let a sub-account’s domain send again:

ahasend subaccounts unpause-domain YOUR_RESOURCE_ID example.com

Unpausing a domain that is not paused changes nothing and prints the domain. A change can take some minutes to apply to new email.

Delete the Test Sub-Account

After the preceding create-first workflow, remove only its test account:

ahasend subaccounts delete "$TEST_SUBACCOUNT_ID" --force

Deletion is a soft delete: the sub-account can no longer be used and leaves list results, but AhaSend keeps its historical data. Current billing-period usage still belongs to the parent invoice. Without --force, the command asks for confirmation; answer y or yes.

Command Flags

These flags come from the CLI’s --help. All commands also accept the global flags. List commands page as Lists and Pagination describes.

`subaccounts api-keys create`

ahasend subaccounts api-keys create <sub-account-id> --label <label> --scope <scope> [flags]

Flag	Description and default
`--idempotency-key string`	Idempotency key for safe retries (generated when omitted)
`--ip-allow-list strings`	CIDR block or IP address allowed to use the key (can be used multiple times)
`--label string`	Label for the API key (required)
`--scope strings`	Scope to grant (required; can be used multiple times)

The secret is shown once, in every output format, and cannot be read again. Within 5 minutes, a retry with the same idempotency key returns the original key with its secret.

`subaccounts api-keys delete`

ahasend subaccounts api-keys delete <sub-account-id> <key-id> [flags]

Flag	Description and default
`-f`, `--force`	Skip confirmation prompt

`subaccounts api-keys get`

ahasend subaccounts api-keys get <sub-account-id> <key-id> [flags]

No command-specific flags. Table and plain output show the secret as [HIDDEN].

`subaccounts api-keys list`

ahasend subaccounts api-keys list <sub-account-id> [flags]

Flag	Description and default
`--after string`	Return the page after this cursor
`--before string`	Return the page before this cursor
`--limit int32`	Maximum number of items to return (0-100; 0 uses the API default)

`subaccounts api-keys update`

ahasend subaccounts api-keys update <sub-account-id> <key-id> [flags]

Flag	Description and default
`--clear-ip-allow-list`	Remove the IP allow list so the key works from any IP
`--ip-allow-list strings`	New CIDR block or IP address allowed to use the key, replacing the list (can be used multiple times)
`--label string`	New label for the API key
`--scope strings`	New scope to grant, replacing all scopes (can be used multiple times)

Give at least one flag. --scope replaces all scopes: to add one, list the existing scopes and the new one.

`subaccounts create`

ahasend subaccounts create --name <name> --website <domain> [flags]

Flag	Description and default
`--idempotency-key string`	Idempotency key for safe retries (generated when omitted)
`--monthly-credit int`	Monthly credit allocation (0-1000000000)
`--name string`	Sub-account name (required)
`--website string`	Sub-account website domain, e.g. example.com (required)

`subaccounts delete`

ahasend subaccounts delete <sub-account-id> [flags]

Flag	Description and default
`-f`, `--force`	Skip confirmation prompt

`subaccounts get`

ahasend subaccounts get <sub-account-id> [flags]

No command-specific flags.

`subaccounts list`

ahasend subaccounts list [flags]

Flag	Description and default
`--after string`	Return the page after this cursor
`--before string`	Return the page before this cursor
`--limit int32`	Maximum number of items to return (0-100; 0 uses the API default)

`subaccounts suspend`

ahasend subaccounts suspend <sub-account-id> [flags]

Alias: pause.

Flag	Description and default
`-f`, `--force`	Skip confirmation prompt
`--reason string`	Reason for the suspension (required)

`subaccounts unpause-domain`

ahasend subaccounts unpause-domain <sub-account-id> <domain> [flags]

No command-specific flags.

`subaccounts unsuspend`

ahasend subaccounts unsuspend <sub-account-id> [flags]

Aliases: resume, unpause. No command-specific flags.

`subaccounts update`

ahasend subaccounts update <sub-account-id> [flags]

Flag	Description and default
`--monthly-credit int`	New monthly credit allocation (0-1000000000)
`--name string`	New sub-account name
`--website string`	New sub-account website domain, e.g. example.com

Only the flags you give change, and at least one is needed. --monthly-credit 0 is sent as 0.

`subaccounts usage`

ahasend subaccounts usage [flags]

No command-specific flags.

Getting Started

Commands

Features

ahasend subaccounts: Manage Sub-Accounts

Prerequisites

Create and Manage a Test Sub-Account

Manage a Test Sub-Account API Key

Unpause a Sub-Account Domain

Delete the Test Sub-Account

Command Flags

`subaccounts api-keys create`

`subaccounts api-keys delete`

`subaccounts api-keys get`

`subaccounts api-keys list`

`subaccounts api-keys update`

`subaccounts create`

`subaccounts delete`

`subaccounts get`

`subaccounts list`

`subaccounts suspend`

`subaccounts unpause-domain`

`subaccounts unsuspend`

`subaccounts update`

`subaccounts usage`

​Prerequisites

​Create and Manage a Test Sub-Account

​Manage a Test Sub-Account API Key

​Unpause a Sub-Account Domain

​Delete the Test Sub-Account

​Command Flags

​subaccounts api-keys create

​subaccounts api-keys delete

​subaccounts api-keys get

​subaccounts api-keys list

​subaccounts api-keys update

​subaccounts create

​subaccounts delete

​subaccounts get

​subaccounts list

​subaccounts suspend

​subaccounts unpause-domain

​subaccounts unsuspend

​subaccounts update

​subaccounts usage

​Related Guides

Prerequisites

Create and Manage a Test Sub-Account

Manage a Test Sub-Account API Key

Unpause a Sub-Account Domain

Delete the Test Sub-Account

Command Flags

`subaccounts api-keys create`

`subaccounts api-keys delete`

`subaccounts api-keys get`

`subaccounts api-keys list`

`subaccounts api-keys update`

`subaccounts create`

`subaccounts delete`

`subaccounts get`

`subaccounts list`

`subaccounts suspend`

`subaccounts unpause-domain`

`subaccounts unsuspend`

`subaccounts update`

`subaccounts usage`

Related Guides