Skip to main content
The provisioning module maps WHMCS module commands to MailChannels sub-account operations. Every operation is idempotent and safe to retry.

​
Lifecycle mapping

You can run any of these by hand from Module Commands on the service’s page in the WHMCS admin area.
WHMCS Module Commands row with Create, Renew, Suspend, Unsuspend, Terminate, and Change Package buttons

​
Sub-account handles

Each sub-account handle is deterministic. It is built from three parts:
For example, service 1234 on an installation with hash 3f9a1c7e2b4d gets the handle whmcs3f9a1c7e2b4dya. The installation hash is derived from your WHMCS system URL and encryption hash when the addon is activated. Because the handle is derived rather than random, a retried provisioning run always looks for the same sub-account. The handle contains no customer identity and no secret material. The sub-account’s company name is the client’s company name from their WHMCS profile, truncated to 128 characters. If the client has no company name, or it is shorter than three characters, the plugin uses WHMCS service <ID> instead.

​
What happens on create

When WHMCS runs Create, the module:
  1. Takes a per-service MySQL advisory lock so two operations cannot run on the same service at once. The lock waits up to 20 seconds, then fails with Another MailChannels operation is already running for this service.
  2. Records the service as provisioning with its handle, limit, and credential mode.
  3. Looks for an existing sub-account with that handle by paging through your parent account’s sub-account list.
  4. Creates the sub-account if none exists. If MailChannels answers with a conflict and the handle is then found, the existing sub-account is reused.
  5. Sets the send limit from the plan.
  6. Creates each credential type the plan requires that the service does not already have. Secrets are encrypted immediately with the WHMCS encryption API.
  7. Marks the service active and writes a success entry to the operation history.
If any step fails, the service stays in provisioning, a sanitized failure entry is written to the operation history, and WHMCS shows the error in the Module Queue. Retrying Create picks up where it left off.

​
Credential creation safety

Creating a credential is the one step whose outcome can be ambiguous, for example when a request times out after MailChannels has already created the key. To avoid leaving unknown credentials behind, the module:
  1. Lists the sub-account’s credential IDs before the request.
  2. Creates the credential.
  3. On an ambiguous failure, lists the IDs again and compares.
  4. If exactly one new ID appeared, revokes it and retries the creation once.
  5. If more than one new ID appeared, stops and records RecoveryRequiredException. An administrator must inspect the sub-account in the MailChannels Console and remove stray credentials before retrying.

​
What happens on change package

Change Package runs when a customer upgrades or downgrades, or when you apply plan changes from the addon:
  1. Retrieves the sub-account’s current-period usage.
  2. Rejects the change if the new limit is below current usage. Nothing is changed at MailChannels.
  3. Applies the new limit.
  4. Creates any newly required credential type.
  5. Revokes active module-managed credentials of a type the new plan no longer includes, and erases their stored secrets.
  6. Records the new limit and mode.
Credentials the customer created themselves in the MailChannels Console are never touched. The plugin only manages credentials it created.

​
What happens on terminate

Terminate deletes the sub-account at MailChannels. If the sub-account is already gone, the deletion is treated as successful. The plugin then:
  • Sets every stored credential to erased and removes its ciphertext.
  • Clears cached usage.
  • Sets the service to terminated and records a tombstone timestamp.
The service row and operation history are kept for auditing. They contain the handle, timestamps, states, and sanitized error codes, but no secrets.
Termination is permanent at MailChannels. The sub-account’s suppressions, webhooks, and usage history are deleted with it. A re-created service for the same WHMCS service ID gets the same handle but starts with a fresh sub-account.

​
Recover a failed service

Failed operations appear in two places: the WHMCS Module Queue and the Operation history at the bottom of the addon page. Each history row shows the time, service ID, operation, outcome, error code, and the MailChannels request ID when one is available. To retry provisioning from the addon:
  1. Go to Addons > MailChannels Email API and find Recovery and reconciliation.
  2. Enter the WHMCS service ID and click Retry provisioning.
This calls the WHMCS ModuleCreate API for that service, which runs the same idempotent create flow. You can also retry from the service’s Module Commands in the WHMCS admin area. Common causes and fixes are listed in Troubleshooting.

​
Service states

The client area shows the state to the customer while the service is active. See Client area.