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

# Creating a sub-account

> Create a sub-account under your MailChannels parent account.

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

<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}"
  : "${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 }"
  ```

  ```javascript Node.js theme={null}
  import { MailChannels } from "mailchannels-sdk";

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

  const mailchannels = new MailChannels(PARENT_API_KEY);

  // SUB_ACCOUNT_HANDLE is optional. If omitted, MailChannels generates a random handle.
  const { data, error } = await mailchannels.subAccounts.create(COMPANY_NAME, SUB_ACCOUNT_HANDLE);

  if (error) {
    console.error("Create sub-account failed:", error);
    process.exit(1);
  }
  console.log(data);
  ```

  ```python Python theme={null}
  import os
  import sys

  import mailchannels

  parent_api_key = os.environ.get("PARENT_API_KEY")
  company_name = os.environ.get("COMPANY_NAME")
  if not parent_api_key:
      sys.exit("Set PARENT_API_KEY (a parent-account API key) before running")
  if not company_name:
      sys.exit("Set COMPANY_NAME (display name for the sub-account)")

  mailchannels.api_key = parent_api_key

  # SUB_ACCOUNT_HANDLE is optional. If omitted, MailChannels generates a random handle.
  response = mailchannels.SubAccounts.create(
      company_name=company_name,
      handle=os.environ.get("SUB_ACCOUNT_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");
  $company_name   = getenv('COMPANY_NAME') or exit("Error: COMPANY_NAME is not set\n");

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

  // SUB_ACCOUNT_HANDLE is optional. If omitted, MailChannels generates a random handle.
  $response = $client->subAccounts->create(
      companyName: $company_name,
      handle:      getenv('SUB_ACCOUNT_HANDLE') ?: null,
  );

  print_r($response->toArray());
  ```
</CodeGroup>

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.