> ## 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.
# Install the WHMCS plugin
> Get MailChannels Email API for WHMCS from its Git repository, optionally build a release ZIP, and install, upgrade, deactivate, or remove it.
## Prerequisites
* A WHMCS 9.0 or 8.13 LTS installation running PHP 8.2 or 8.3.
* File system access to the WHMCS installation directory.
* A WHMCS administrator account that can activate addon modules.
* Git, to download the plugin.
The plugin does not need Composer on your WHMCS server. The repository already contains an isolated, namespace-scoped copy of the official `mailchannels/mailchannels-php` SDK and its runtime dependencies.
## Get the plugin
The plugin is open source under the MIT license. The source code is in a public Git repository:
```text theme={null}
https://bitbucket.org/mailchannels/mailchannels-email-api-whmcs-plugin
```
Clone it on a workstation or on the WHMCS server:
```bash theme={null}
git clone https://bitbucket.org/mailchannels/mailchannels-email-api-whmcs-plugin.git
cd mailchannels-email-api-whmcs-plugin
```
You can install the plugin in two ways. Both install the same code.
| Method | Use it when |
| - | - |
| [Install from the clone](#install-from-the-clone) | You want the quickest path. You copy two directories. No build tools are needed. |
| [Build a release ZIP](#build-a-release-zip) | You want a single versioned archive to store, transfer, or deploy to several WHMCS servers. |
## Install from the clone
The two module directories in the repository are ready to use as they are.
From the root of the clone, copy both module directories into your WHMCS installation. Replace `/path/to/whmcs` with your WHMCS directory.
```bash theme={null}
cp -R modules/addons/mailchannels_email_api /path/to/whmcs/modules/addons/
cp -R modules/servers/mailchannels_email_api /path/to/whmcs/modules/servers/
```
The files must end up at these paths:
```text theme={null}
/path/to/whmcs/modules/addons/mailchannels_email_api/
/path/to/whmcs/modules/servers/mailchannels_email_api/
```
The web server user must be able to read every file under both directories.
Continue with [Activate and connect](#activate-and-connect).
## Build a release ZIP
The build script regenerates the bundled SDK runtime and packages the two module directories, the license, and the README into one archive.
### Build requirements
Building runs on Linux or macOS and needs these tools on the build machine. The WHMCS server does not need them.
* Docker. The build runs PHP, Composer, and the namespace scoper in containers, so you do not need PHP installed locally.
* Bash, `rsync`, `zip`, and `unzip`.
* [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`). The build uses it to check that no secret markers end up in the archive.
### Build the archive
From the root of the clone, install the Composer dependencies for the build tools and for the runtime that gets bundled:
```bash theme={null}
docker run --rm -v "$PWD:/work" -w /work composer:2.9 composer install
docker run --rm -v "$PWD/runtime:/work" -w /work composer:2.9 composer install --no-dev
```
Pass the version number you want in the archive name:
```bash theme={null}
dev/scripts/build-release 1.0.0
```
The script finishes with a line such as:
```text theme={null}
Built and content-verified /path/to/clone/dist/mailchannels-email-api-for-whmcs-1.0.0.zip
```
The archive is written to the `dist/` directory. It contains one top-level folder:
```text theme={null}
mailchannels-email-api-for-whmcs-1.0.0/
modules/addons/mailchannels_email_api/
modules/servers/mailchannels_email_api/
docs/operations.md
LICENSE
README.md
```
The build rewrites generated files under `modules/servers/mailchannels_email_api/vendor-scoped/` in your clone. This is expected. Run `git checkout -- modules/servers/mailchannels_email_api/vendor-scoped` afterwards if you want a clean working tree.
### Install the archive
Transfer `mailchannels-email-api-for-whmcs-1.0.0.zip` to the server and extract it:
```bash theme={null}
unzip mailchannels-email-api-for-whmcs-1.0.0.zip
```
Copy both module directories from the extracted folder into your WHMCS installation:
```bash theme={null}
cd mailchannels-email-api-for-whmcs-1.0.0
cp -R modules/addons/mailchannels_email_api /path/to/whmcs/modules/addons/
cp -R modules/servers/mailchannels_email_api /path/to/whmcs/modules/servers/
```
The web server user must be able to read every file under both directories.
## Activate and connect
In the WHMCS admin area, go to **System Settings > Addon Modules**. Find **MailChannels Email API** and click **Activate**.
Activation creates the plugin's database tables and records an installation identity. The identity is a 12-character hash of your WHMCS system URL and encryption hash. It becomes part of every sub-account handle.
Still in **Addon Modules**, click **Configure** next to **MailChannels Email API** and select the administrator roles that may open the addon page. Save the changes.
Open **Addons > MailChannels Email API** and follow [Connect your parent account](/plugins/whmcs/connect-parent-account).
The addon page shows three cards at the top: **Parent connection**, **Active allocations**, and **Shared parent ceiling**. If you see them, the modules loaded correctly.
## Database tables
Activation creates five tables. All of them use the `mod_mailchannels_email_api_` prefix.
| Table | Purpose |
| - | - |
| `settings` | Plugin settings, including the encrypted parent API key and the installation identity. |
| `services` | One row per WHMCS service: handle, lifecycle state, plan limit, credential mode, and cached usage. |
| `credentials` | Module-managed credentials: provider ID, encrypted secret, status, and rotation links. |
| `operations` | A sanitized history of every provisioning operation, its outcome, error code, and request ID. |
| `migrations` | The schema version applied to this installation. |
Secrets in `settings` and `credentials` are encrypted with the WHMCS encryption API. See [Security and data flow](/plugins/whmcs/security).
## Upgrade
1. Update your clone with `git pull`. If you install from a release ZIP, [build a new archive](#build-a-release-zip).
2. Replace both module directories in WHMCS with the new versions. Remove the old directories first so that files deleted in the new version do not linger.
3. Open **System Settings > Addon Modules**. WHMCS detects the new version and runs the plugin's schema migration.
Upgrades never delete provisioning state or encrypted credentials.
## Deactivate
Deactivating the addon in **Addon Modules** disables the admin page and the daily reconciliation hook. Provisioning state and encrypted credentials are retained so you can reactivate safely.
While the addon is deactivated, WHMCS still runs the provisioning module for lifecycle events such as suspend and terminate, because those are attached to products. Those operations continue to work as long as the parent API key remains stored.
## Remove
To remove the plugin completely:
1. Terminate or move any WHMCS services that use the **MailChannels Email API** module. Terminating a service deletes its sub-account at MailChannels.
2. Deactivate the addon.
3. Delete both module directories.
4. Drop the five `mod_mailchannels_email_api_*` tables if you do not want to keep the operation history.
Deleting the module directories does not delete sub-accounts at MailChannels. Use the WHMCS terminate action, or delete them from the MailChannels Console, before you remove the plugin.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.