Skip to main content

​
How sub-account limits work

A sub-account limit represents the maximum number of messages that can be sent from that sub-account during a billing period. By default, sub-accounts have no limit; they can send as many messages as the parent account’s limit allows. Sub-account limits can be set to any non-negative integer and their sum might exceed the parent account’s overall limit. The parent account’s limit is a hard ceiling; once the parent account’s limit is reached, all subsequent sends from the parent account and all sub-accounts are blocked until the next billing period.

​
Example

Parent account P has two sub-accounts, SUB_A and SUB_B:
AccountSending limit
P100,000
SUB_A70,000
SUB_B70,000
The sub-account limits sum to 140,000, which is more than P’s overall limit of 100,000. That means the parent limit, not the sub-account limits, will be the ceiling once total sends across the parent and sub-accounts reach 100,000. Suppose SUB_A sends 70,000 messages and SUB_B has not sent any:
  • SUB_A has hit its own 70,000 limit and is blocked from sending further.
  • P has used 70,000 of its 100,000 overall capacity, leaving 30,000.
  • SUB_B can still send up to 30,000 messages, even though its own limit is 70,000. The parent’s remaining capacity is now the binding ceiling.
Once SUB_B sends those 30,000 messages, P reaches its 100,000 overall limit and no further sends are accepted from P, SUB_A, or SUB_B until the next billing period.
The parent account is responsible for picking sub-account limits that match how much capacity each sub-account is expected to use.

​
Set a limit

Limits can be managed programmatically, or via the sub-accounts page. 
#!/usr/bin/env bash
set -u
: "${PARENT_API_KEY:?Set PARENT_API_KEY (a parent-account API key) before running}"
: "${SUB_ACCOUNT_HANDLE:?Set SUB_ACCOUNT_HANDLE (the sub-account to set a limit on)}"
: "${SEND_LIMIT:?Set SEND_LIMIT (maximum sends per billing period, integer >= 0)}"

curl -X PUT \
  "https://api.mailchannels.net/tx/v1/sub-account/$SUB_ACCOUNT_HANDLE/limit" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $PARENT_API_KEY" \
  -d "{ \"sends\": $SEND_LIMIT }"
Set the following before running:
  • PARENT_API_KEY — a parent-account API key.
  • SUB_ACCOUNT_HANDLE — the sub-account being limited.
  • SEND_LIMIT — maximum sends per billing period (integer, 0 or greater).
Setting sends to 0 effectively pauses the sub-account without suspending it.

​
Get the current limit

#!/usr/bin/env bash
set -u
: "${PARENT_API_KEY:?Set PARENT_API_KEY (a parent-account API key) before running}"
: "${SUB_ACCOUNT_HANDLE:?Set SUB_ACCOUNT_HANDLE (the sub-account to read the limit for)}"

curl "https://api.mailchannels.net/tx/v1/sub-account/$SUB_ACCOUNT_HANDLE/limit" \
  -H "X-Api-Key: $PARENT_API_KEY"
A response of sends: -1 means no explicit limit has been set. The sub-account is bounded only by the parent account’s limit.

​
Remove a limit

Removing the limit lets the sub-account use any remaining capacity in the parent account’s allocation. 
#!/usr/bin/env bash
set -u
: "${PARENT_API_KEY:?Set PARENT_API_KEY (a parent-account API key) before running}"
: "${SUB_ACCOUNT_HANDLE:?Set SUB_ACCOUNT_HANDLE (the sub-account whose limit you want to clear)}"

curl -X DELETE \
  "https://api.mailchannels.net/tx/v1/sub-account/$SUB_ACCOUNT_HANDLE/limit" \
  -H "X-Api-Key: $PARENT_API_KEY"