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

# Security and data flow

> How MailChannels Email API for WHMCS protects credentials, what data it sends to MailChannels, and which server settings affect it.

## Credential storage

* The parent API key and every customer credential are encrypted at rest with the WHMCS encryption API (`EncryptPassword` and `DecryptPassword`). They are protected by your WHMCS encryption hash.
* Secrets are decrypted only at the moment they are needed: to call the MailChannels API, or to reveal a credential to its owner.
* When a credential is revoked, replaced, or its service is terminated, the ciphertext is deleted and an erasure timestamp is recorded.

<Warning>
  Your WHMCS encryption hash in `configuration.php` protects every stored secret. If you change it, WHMCS can no longer decrypt the parent key or customer credentials. Reconnect the parent account and ask customers to rotate their credentials.
</Warning>

## Where credentials never appear

* URLs or query strings.
* Ordinary page HTML. Secrets are shown only in the response to an ownership-checked, CSRF-protected POST request that carries `Cache-Control: no-store`.
* The WHMCS welcome email. The plan builder disables it, and the module never populates credential fields.
* WHMCS module logs, the plugin's operation history, cron output, or exception messages.
* Sub-account handles. Handles are derived from a hash of your installation and the WHMCS service ID.

## Redaction

All error text and operation context passes through a redactor before it is stored or displayed. The redactor:

* Replaces the values of keys such as `api_key`, `password`, `secret`, `authorization`, and `x-api-key` with `[redacted]`.
* Replaces inline patterns such as `api_key=...` or `password: ...` in free text.
* Replaces tokens that match MailChannels key prefixes.
* Truncates messages to 500 characters.

MailChannels API errors are also mapped to fixed, safe messages by HTTP status before they reach an administrator or customer. See [Troubleshooting](/plugins/whmcs/troubleshooting#error-messages).

## Access control

| Surface | Protection |
| - | - |
| Addon page | WHMCS administrator role permission for the addon, plus the WHMCS admin CSRF token on every action. |
| Client area page | The logged-in client must own the service. Every action requires the WHMCS client CSRF token. |
| Provisioning | Runs only through WHMCS module commands, the WHMCS API, or the addon's retry action. |
| Concurrency | A per-service MySQL advisory lock prevents overlapping operations on the same service. |

## Data sent to MailChannels

The plugin sends the minimum needed to manage sub-accounts. All calls go to the MailChannels Email API over HTTPS, authenticated with your parent API key, with the user agent `mailchannels-email-api-for-whmcs/<version>`.

| Data | When | Purpose |
| - | - | - |
| Sub-account handle | Every sub-account call | Identifies the sub-account. Derived from your installation hash and the WHMCS service ID. |
| Company name | Sub-account creation | The client's company name from WHMCS, truncated to 128 characters, or `WHMCS service <ID>` if none. Shown on the MailChannels unsubscribe page for that sub-account. |
| Send limit | Create and change package | Sets the sub-account limit. |
| Domain name | Customer runs the domain check | The domain the customer typed, checked with the customer's own sub-account API key. |

The plugin does not send customer names, email addresses, WHMCS IDs, invoices, or message content. WHMCS service IDs are encoded into handles only as base 36 alongside the installation hash.

## Data received from MailChannels

* Sub-account list entries (handle and enabled state) when locating a sub-account.
* Usage snapshots: total usage, limit, and billing period dates. Cached in WHMCS for 15 minutes.
* Credential IDs and one-time secret values at creation. Secrets are encrypted immediately.
* Domain check results, which are shown to the customer and not stored.

## API endpoint

The plugin talks to `https://api.mailchannels.net/tx/v1` by default. Two environment variables exist for the development harness only:

| Variable | Effect |
| - | - |
| `MAILCHANNELS_WHMCS_API_BASE_URL` | Overrides the API base URL. |
| `MAILCHANNELS_WHMCS_ALLOW_INSECURE_API=1` | Required for the override to accept a non-HTTPS URL. Without it, a non-HTTPS override fails closed. |

Do not set either variable on a production server.

## Bundled SDK

The release contains the official `mailchannels/mailchannels-php` SDK and its HTTP dependencies under `modules/servers/mailchannels_email_api/vendor-scoped/`, rewritten into the `MailChannelsWhmcsScoped` namespace. This prevents conflicts with other WHMCS modules that ship their own copies of Guzzle or PSR libraries. Do not run Composer inside the module directory.

## Reporting a vulnerability

If you find a security issue in the plugin, contact MailChannels through the [support portal](https://support.mailchannels.com/hc/en-us/requests/new) and mark the request as a security report. Do not post details publicly until MailChannels has responded.


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