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

# Connect your parent account

> Create a MailChannels parent API key and connect it to the WHMCS addon so the plugin can provision sub-accounts.

The plugin manages every customer sub-account through one MailChannels parent account. You connect it once from the addon page.

## Prerequisites

* The plugin is [installed and activated](/plugins/whmcs/installation).
* You can sign in to the [MailChannels Console](https://dash.mailchannels.com) for the parent account.

## Create a parent API key

<Steps>
  <Step title="Open API keys in the Console">
    Sign in to the MailChannels Console and open [Account > API Keys](https://dash.mailchannels.com/account/api-keys).
  </Step>

  <Step title="Create the key">
    Click **Create API Key**. Give it a label such as `WHMCS` and set the scope to `Sending Email` (`api`). Copy the key. You cannot view it again.
  </Step>
</Steps>

<Warning>
  Treat this key like a root password for your customers' email. It can create, suspend, and delete sub-accounts and their credentials. Store it only in WHMCS, where the plugin encrypts it. Do not reuse it in other integrations.
</Warning>

<Tip>
  Use a dedicated key for WHMCS. If you ever need to rotate it, you can disconnect and reconnect the addon without affecting other systems that use your parent account.
</Tip>

## Connect the key in WHMCS

<Steps>
  <Step title="Open the addon">
    In the WHMCS admin area, go to **Addons > MailChannels Email API**.
  </Step>

  <Step title="Enter the key">
    Under **1. Connect the parent account**, paste the key into **Parent API key** and click **Validate and connect**.

    <Frame>
      <img src="https://mintcdn.com/mailchannelscorporation/D6DVDzSDwKoQr1cV/images/whmcs-plugin/connect-card.png?fit=max&auto=format&n=D6DVDzSDwKoQr1cV&q=85&s=b4148434a02bbf5a119fe3b74f80e245" alt="Connect the parent account card with the Parent API key field and the Validate and connect button" width="2108" height="358" data-path="images/whmcs-plugin/connect-card.png" />
    </Frame>
  </Step>

  <Step title="Confirm the connection">
    The plugin validates the key by retrieving your parent account's current-period usage and listing sub-accounts. If both calls succeed, it encrypts the key with the WHMCS encryption API, saves it, and shows a success message with your current usage and limit.

    The **Parent connection** card changes to **Connected** and records the validation time.
  </Step>
</Steps>

<Check>
  The **Shared parent ceiling** card now shows your parent account's used and total sends for the current billing period.
</Check>

<Frame>
  <img src="https://mintcdn.com/mailchannelscorporation/D6DVDzSDwKoQr1cV/images/whmcs-plugin/dashboard-tiles.png?fit=max&auto=format&n=D6DVDzSDwKoQr1cV&q=85&s=e66515f586dce71ed2938c24a42280a1" alt="Addon status cards showing Parent connection as Connected, Active allocations, and Shared parent ceiling usage" width="2108" height="288" data-path="images/whmcs-plugin/dashboard-tiles.png" />
</Frame>

If the key is stored but MailChannels cannot return parent usage, the **Shared parent ceiling** card shows **Unavailable** with the reason.

### If validation fails

| Message | Cause | Fix |
| - | - | - |
| MailChannels rejected the parent API key. | The key is wrong, revoked, or belongs to a sub-account. | Create a new key on the parent account and try again. |
| The parent API key cannot manage this MailChannels resource. | The key is valid but cannot list sub-accounts. | Confirm the key belongs to the parent account, not a sub-account. |
| MailChannels rate-limited the operation. | Too many requests in a short period. | Wait a minute and retry. |
| Non-HTTPS MailChannels API override is disabled outside the development harness. | The server sets `MAILCHANNELS_WHMCS_API_BASE_URL` to a non-HTTPS URL. | Remove the override in production. See [Security and data flow](/plugins/whmcs/security#api-endpoint). |

## Disconnect

Once a key is connected, the connection form is collapsed. To remove the stored key, expand **Disconnect** under **1. Connect the parent account**, type `DISCONNECT` in the confirmation field, and click **Disconnect**.

Disconnecting deletes the encrypted key and the validation timestamp. It does not change any sub-account at MailChannels, and existing WHMCS service records are retained. Until you connect a key again, every provisioning action fails with the message `Connect a MailChannels parent account in the addon module before provisioning.`

## Rotate the parent key

1. Create a new API key in the MailChannels Console.
2. In the addon, expand **Replace the API key**, paste the new key, and click **Validate and connect**. The new key replaces the old one.
3. Revoke the old key in the Console.

Existing sub-accounts and customer credentials are unaffected. The parent key is used only for management calls, never for customer sending.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.