Skip to main content

​
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:
Clone it on a workstation or on the WHMCS server:
You can install the plugin in two ways. Both install the same code.

​
Install from the clone

The two module directories in the repository are ready to use as they are.
1

Copy the module directories

From the root of the clone, copy both module directories into your WHMCS installation. Replace /path/to/whmcs with your WHMCS directory.
The files must end up at these paths:
The web server user must be able to read every file under both directories.
2

Activate the addon

Continue with 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 (rg). The build uses it to check that no secret markers end up in the archive.

​
Build the archive

1

Install the build dependencies

From the root of the clone, install the Composer dependencies for the build tools and for the runtime that gets bundled:
2

Run the build

Pass the version number you want in the archive name:
The script finishes with a line such as:
3

Check the archive

The archive is written to the dist/ directory. It contains one top-level folder:
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

1

Copy the archive to the WHMCS server

Transfer mailchannels-email-api-for-whmcs-1.0.0.zip to the server and extract it:
2

Copy the module directories

Copy both module directories from the extracted folder into your WHMCS installation:
The web server user must be able to read every file under both directories.

​
Activate and connect

1

Activate the addon

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

Grant admin access

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

Connect your parent account

Open Addons > MailChannels Email API and follow Connect your 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. Secrets in settings and credentials are encrypted with the WHMCS encryption API. See Security and data flow.

​
Upgrade

  1. Update your clone with git pull. If you install from a release ZIP, build a new archive.
  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.