> ## 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.
# Service lifecycle
> What the plugin does at MailChannels when WHMCS creates, suspends, reactivates, upgrades, renews, or terminates a service, and how failures are recovered.
The provisioning module maps WHMCS module commands to MailChannels sub-account operations. Every operation is idempotent and safe to retry.
## Lifecycle mapping
| WHMCS action | MailChannels result |
| - | - |
| Create | Create the sub-account, set the send limit, create the required credentials, mark the service active. |
| Suspend | Suspend the sub-account. Sending is blocked. Credentials are kept. |
| Unsuspend | Activate the sub-account. Sending resumes with the same credentials. |
| Change Package | Apply the new send limit, create newly required credentials, revoke credential types the new plan drops. |
| Renew | No remote change. MailChannels resets usage on its own billing period. |
| Terminate | Permanently delete the sub-account, erase encrypted secrets, keep a non-secret tombstone. |
You can run any of these by hand from **Module Commands** on the service's page in the WHMCS admin area.
## Sub-account handles
Each sub-account handle is deterministic. It is built from three parts:
```text theme={null}
whmcs + <12-character installation hash> +
```
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 ` 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](/plugins/whmcs/create-plans#change-an-existing-plan) 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](/plugins/whmcs/troubleshooting).
## Service states
| State | Meaning |
| - | - |
| `provisioning` | Create started but has not completed. Retry is safe. |
| `active` | The sub-account is enabled and credentials are available. |
| `suspended` | The sub-account is suspended at MailChannels. |
| `terminated` | The sub-account was deleted and secrets were erased. |
The client area shows the state to the customer while the service is active. See [Client area](/plugins/whmcs/client-area).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.