Skip to main content

​
Before you start

Sub-accounts are available to subscriptions that include at least 100,000 monthly sends. Only a parent account can create sub-accounts; sub-accounts cannot create further sub-accounts.

​
Create a sub-account

#!/usr/bin/env bash
set -u
: "${PARENT_API_KEY:?Set PARENT_API_KEY (a parent-account API key) before running}"
: "${COMPANY_NAME:?Set COMPANY_NAME (display name for the sub-account)}"
# SUB_ACCOUNT_HANDLE is optional. If unset, MailChannels generates a random handle.
HANDLE_FIELD=""
if [ -n "${SUB_ACCOUNT_HANDLE:-}" ]; then
  HANDLE_FIELD=", \"handle\": \"$SUB_ACCOUNT_HANDLE\""
fi

curl -X POST https://api.mailchannels.net/tx/v1/sub-account \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $PARENT_API_KEY" \
  -d "{ \"company_name\": \"$COMPANY_NAME\"$HANDLE_FIELD }"
Set the following before running:
  • PARENT_API_KEY — a parent-account API key with the Sending Email scope.
  • COMPANY_NAME — a display name for the sub-account, between 3 and 128 characters. Shown on the unsubscribe page when using Unsubscribe Links.
  • SUB_ACCOUNT_HANDLE — optional, between 3 and 128 characters, consisting of lowercase letters and digits. If omitted, MailChannels generates a random handle. The handle is the identifier used in every subsequent sub-account API call.
A successful call returns a response with the new sub-account’s handle, company_name, and enabled state.