Sub-account Management

Sub-accounts in MailChannels allow you to create and manage multiple separate email sending identities under your main account. This feature is useful for agencies, resellers, or organizations that need to manage email sending for multiple clients or departments while maintaining clear separation between them.

Creating a Sub-account

Sub-accounts are only available to subscriptions which include at least 100,000 monthly sends. Sub-accounts can only be created by full accounts — they cannot create other sub-accounts.

To create a sub-account, use the POST /tx/v1/sub-account API endpoint. You may optionally provide two fields: company_name and handle.

handle is used to refer to the sub-account in API requests. If it's not provided, one will be generated for you. Handles must be unique across the MailChannels platform. If you provide a handle that is already in use, the request will fail with a 409 Conflict error.

company_name is used to identify the sub-account with a friendly name. It is displayed on the unsubscribe page when using Unsubscribe Links.

Authenticating as a Sub-account

Sub-accounts have their own API keys, which can be used to authenticate API requests. Most API endpoints are available for use by sub-accounts, with the exception of sub-account management endpoints (endpoints under the /tx/v1/sub-account/ path).

To create an API key for a sub-account, use the POST /tx/v1/sub-account/{handle}/api-key API endpoint.

Sub-accounts can also send email using the SMTP interface. To do this, create an SMTP password for the sub-account using the POST /tx/v1/sub-account/{handle}/smtp-password API endpoint.

info

Currently, all accounts (including sub-accounts) must have at least one SMTP password created, even though the SMTP password is not used in API requests.

See the Authentication page for more information.

Sub-account Limits

Sub-accounts can have their own sending limits, which protect the main account from excessive sending by a sub-account. These limits can be set using the POST /tx/v1/sub-account/{handle}/limits API endpoint.

Sub-account limits can be set to any value. It's possible for a sub-account limit, or the sum of all sub-account limits, to exceed the parent account's overall sending limit. In this case, both the sub-account limit and the parent account limit will be enforced.

For example, if we have a parent account (P) with 2 sub-accounts (A, B) and the following limits:

Account	Sending Limit
P	100,000
A	70,000
B	70,000

If A has sent 70,000 messages, but B has not sent any messages, then requests from A will be blocked, because it has reached its sub-account limit. B can now send up to 30,000 messages, after which it will be blocked, because the parent account's limit has been reached.

This means that it's possible for one sub-account to prevent other sub-accounts from sending their full limit of messages. It is up to the parent account to manage sub-account limits to ensure that all sub-accounts can send their full limit.

Limits can be removed to a sub-account by using the DELETE /tx/v1/sub-account/{handle}/limits API endpoint. If no limit has been set (or limits have been deleted), the sub-account has no sending limit, but it will still be subject to the parent account's sending limit.

Sub-accounts and Suppression Lists

Sub-accounts have their own suppression lists, which are separate from the parent account's suppression list. If a recipient is on a parent account's suppression list, they will not be blocked from receiving email from a sub-account unless they are also on the sub-account's suppression list.

For more information on suppression lists, see the Unsubscribe page.

Sub-accounts and Delivery Events

Sub-accounts manage their own delivery event webhooks, separate from the parent account. For more information on delivery events, see the Delivery Events page.

Suspending a Sub-account

A parent account can choose to suspend a sub-account. While suspended, the sub-account cannot send mail, but it can still access all other API endpoints.

To suspend a sub-account, use the POST /tx/v1/sub-account/{handle}/suspend API endpoint.

To activate a sub-account, use the POST /tx/v1/sub-account/{handle}/activate API endpoint.

Other Sub-account Management Operations

Sub-accounts can be deleted by using the DELETE /tx/v1/sub-account/{handle} API endpoint. When a sub-account is deleted, all of its API keys, SMTP passwords, and limits are also deleted.

Parent accounts can get information about their sub-accounts using the GET /tx/v1/sub-account API endpoint. Parent accounts can get usage information for a sub-account using the GET /tx/v1/sub-account/{handle}/usage API endpoint.