Sub-account sending limits

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:

Account	Sending limit
`P`	100,000
`SUB_A`	70,000
`SUB_B`	70,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 }"

import { MailChannels } from "mailchannels-sdk";

const { PARENT_API_KEY, SUB_ACCOUNT_HANDLE, SEND_LIMIT } = process.env;
if (!PARENT_API_KEY) throw new Error("Set PARENT_API_KEY (a parent-account API key) before running");
if (!SUB_ACCOUNT_HANDLE) throw new Error("Set SUB_ACCOUNT_HANDLE (the sub-account to set a limit on)");
if (!SEND_LIMIT) throw new Error("Set SEND_LIMIT (maximum sends per billing period, integer >= 0)");

const mailchannels = new MailChannels(PARENT_API_KEY);

const { success, error } = await mailchannels.subAccounts.setLimit(SUB_ACCOUNT_HANDLE, {
  sends: Number(SEND_LIMIT),
});

if (!success) {
  console.error("Set sub-account limit failed:", error);
  process.exit(1);
}
console.log({ success });

import os
import sys

import mailchannels

parent_api_key = os.environ.get("PARENT_API_KEY")
handle = os.environ.get("SUB_ACCOUNT_HANDLE")
send_limit = os.environ.get("SEND_LIMIT")
if not parent_api_key:
    sys.exit("Set PARENT_API_KEY (a parent-account API key) before running")
if not handle:
    sys.exit("Set SUB_ACCOUNT_HANDLE (the sub-account to set a limit on)")
if not send_limit:
    sys.exit("Set SEND_LIMIT (maximum sends per billing period, integer >= 0)")

mailchannels.api_key = parent_api_key

response = mailchannels.SubAccounts.Limits.set(handle, sends=int(send_limit))

print(response)

<?php

require_once __DIR__ . '/vendor/autoload.php';

use MailChannels\Client;

$parent_api_key     = getenv('PARENT_API_KEY') or exit("Error: PARENT_API_KEY is not set\n");
$sub_account_handle = getenv('SUB_ACCOUNT_HANDLE') or exit("Error: SUB_ACCOUNT_HANDLE is not set\n");
$send_limit         = getenv('SEND_LIMIT') or exit("Error: SEND_LIMIT is not set\n");

$client = new Client(apiKey: $parent_api_key);

$response = $client->subAccounts->limits->set($sub_account_handle, sends: (int) $send_limit);

print_r($response->toArray());

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"

import { MailChannels } from "mailchannels-sdk";

const { PARENT_API_KEY, SUB_ACCOUNT_HANDLE } = process.env;
if (!PARENT_API_KEY) throw new Error("Set PARENT_API_KEY (a parent-account API key) before running");
if (!SUB_ACCOUNT_HANDLE) throw new Error("Set SUB_ACCOUNT_HANDLE (the sub-account to read the limit for)");

const mailchannels = new MailChannels(PARENT_API_KEY);

const { data, error } = await mailchannels.subAccounts.getLimit(SUB_ACCOUNT_HANDLE);

if (error) {
  console.error("Get sub-account limit failed:", error);
  process.exit(1);
}
// A value of -1 means no explicit limit; the sub-account shares the parent's allocation.
console.log(data);

import os
import sys

import mailchannels

parent_api_key = os.environ.get("PARENT_API_KEY")
handle = os.environ.get("SUB_ACCOUNT_HANDLE")
if not parent_api_key:
    sys.exit("Set PARENT_API_KEY (a parent-account API key) before running")
if not handle:
    sys.exit("Set SUB_ACCOUNT_HANDLE (the sub-account to read the limit for)")

mailchannels.api_key = parent_api_key

# A value of -1 means the sub-account has no explicit limit and is bounded
# only by the parent account's overall limit.
response = mailchannels.SubAccounts.Limits.retrieve(handle)

print(response)

<?php

require_once __DIR__ . '/vendor/autoload.php';

use MailChannels\Client;

$parent_api_key     = getenv('PARENT_API_KEY') or exit("Error: PARENT_API_KEY is not set\n");
$sub_account_handle = getenv('SUB_ACCOUNT_HANDLE') or exit("Error: SUB_ACCOUNT_HANDLE is not set\n");

$client = new Client(apiKey: $parent_api_key);

// A value of -1 means the sub-account has no explicit limit and is bounded
// only by the parent account's overall limit.
$response = $client->subAccounts->limits->retrieve($sub_account_handle);

print_r($response->toArray());

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"

import { MailChannels } from "mailchannels-sdk";

const { PARENT_API_KEY, SUB_ACCOUNT_HANDLE } = process.env;
if (!PARENT_API_KEY) throw new Error("Set PARENT_API_KEY (a parent-account API key) before running");
if (!SUB_ACCOUNT_HANDLE) throw new Error("Set SUB_ACCOUNT_HANDLE (the sub-account whose limit you want to clear)");

const mailchannels = new MailChannels(PARENT_API_KEY);

const { success, error } = await mailchannels.subAccounts.deleteLimit(SUB_ACCOUNT_HANDLE);

if (!success) {
  console.error("Delete sub-account limit failed:", error);
  process.exit(1);
}
console.log({ success });

import os
import sys

import mailchannels

parent_api_key = os.environ.get("PARENT_API_KEY")
handle = os.environ.get("SUB_ACCOUNT_HANDLE")
if not parent_api_key:
    sys.exit("Set PARENT_API_KEY (a parent-account API key) before running")
if not handle:
    sys.exit("Set SUB_ACCOUNT_HANDLE (the sub-account whose limit you want to clear)")

mailchannels.api_key = parent_api_key

response = mailchannels.SubAccounts.Limits.delete(handle)

print(response)

<?php

require_once __DIR__ . '/vendor/autoload.php';

use MailChannels\Client;

$parent_api_key     = getenv('PARENT_API_KEY') or exit("Error: PARENT_API_KEY is not set\n");
$sub_account_handle = getenv('SUB_ACCOUNT_HANDLE') or exit("Error: SUB_ACCOUNT_HANDLE is not set\n");

$client = new Client(apiKey: $parent_api_key);

$response = $client->subAccounts->limits->delete($sub_account_handle);

print_r($response->toArray());

Get Started

API Reference

Authentication & Account Setup

Sending Email

Email Authentication

Webhooks & Delivery Events

Platform & Multi-tenant

Reputation and Abuse Control

Metrics & Monitoring

Operate in production

Migration guides

Integrations

For AI Agents

Sub-account sending limits

How sub-account limits work

Example

Set a limit

Get the current limit

Remove a limit

​How sub-account limits work

​Example

​Set a limit

​Get the current limit

​Remove a limit

How sub-account limits work

Example

Set a limit

Get the current limit

Remove a limit