> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailchannels.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-account sending limits

> Learn how to manage sending limits for sub-accounts.

## 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.

<Info>
  The parent account is responsible for picking sub-account limits that match how much capacity each sub-account is expected
  to use.
</Info>

## Set a limit

Limits can be managed programmatically, or via the [sub-accounts page](https://dash.mailchannels.com/sub-accounts).

<CodeGroup>
  ```bash cURL theme={null}
  #!/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 }"
  ```

  ```javascript Node.js theme={null}
  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 });
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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());
  ```
</CodeGroup>

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).

<Note>
  Setting `sends` to `0` effectively pauses the sub-account without suspending it.
</Note>

## Get the current limit

<CodeGroup>
  ```bash cURL theme={null}
  #!/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"
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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());
  ```
</CodeGroup>

<Note>
  A response of `sends: -1` means no explicit limit has been set. The sub-account is bounded only by the parent account's
  limit.
</Note>

## Remove a limit

Removing the limit lets the sub-account use any remaining capacity in the parent account's allocation.

<CodeGroup>
  ```bash cURL theme={null}
  #!/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"
  ```

  ```javascript Node.js theme={null}
  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 });
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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());
  ```
</CodeGroup>