Troubleshooting

Where to look

Addons > MailChannels Email API > Operation history. The last 20 operations with outcome, error code, and MailChannels request ID.
Utilities > Module Queue in WHMCS. Failed module commands with the sanitized error message returned to WHMCS.
The mod_mailchannels_email_api_operations table, for history older than the last 20 entries.
WHMCS Activity Log, for module command invocations.

The plugin never writes secrets to any of these locations, so you can share their contents with MailChannels support along with the request ID.

Error messages

The plugin maps MailChannels API responses to fixed messages.

Message	HTTP status	What to do
MailChannels rejected the parent API key.	401	The stored parent key is invalid or revoked. Reconnect with a new key.
The parent API key cannot manage this MailChannels resource.	403	The key lacks permission, or belongs to a sub-account. Use a parent-account key.
The MailChannels resource was not found.	404	The sub-account or credential was deleted outside WHMCS. Run Reconcile now to identify drift.
The MailChannels resource already exists.	409	A sub-account with this handle exists but could not be found in the list. Retry. If it persists, contact support with the request ID.
MailChannels rate-limited the operation.	429	Wait and retry. Avoid applying plan changes to many services at once during peak hours.
MailChannels could not complete the operation.	5xx	A MailChannels-side error. Retry later. Check System Status.
The MailChannels API operation failed.	Other	A transport or unexpected error. Check outbound HTTPS connectivity from the WHMCS server to `api.mailchannels.net`.

Plugin messages

Message	Cause	Fix
Connect a MailChannels parent account in the addon module before provisioning.	No parent key is stored.	Connect the parent account.
Sends per billing period must be a positive integer.	The product’s first module setting is empty, zero, negative, or not a whole number.	Edit the product’s Module Settings and enter a positive integer.
Credential mode must be api, smtp, or both.	The product’s second module setting has an unexpected value.	Choose a value from the dropdown and save.
The new send limit is below current-period usage; the package change was not applied.	A downgrade would put the customer over their new limit.	Wait for the billing period to reset, or choose a higher limit.
Another MailChannels operation is already running for this service.	Two operations overlapped and the second waited more than 20 seconds.	Retry after the first finishes.
MailChannels service state was not found.	A lifecycle command ran on a service that was never provisioned.	Run Create first.
The bundled MailChannels SDK runtime is missing. Reinstall the complete module release.	The `vendor-scoped` directory is missing or incomplete.	Re-copy `modules/servers/mailchannels_email_api` from the repository or your release ZIP.
Non-HTTPS MailChannels API override is disabled outside the development harness.	`MAILCHANNELS_WHMCS_API_BASE_URL` points at a non-HTTPS URL.	Remove the override. See API endpoint.
Credential creation had an ambiguous outcome and multiple new provider IDs were found. Administrator recovery is required.	A timeout during credential creation left more than one unknown credential.	Open the sub-account in the MailChannels Console, remove credentials WHMCS does not list, then retry.
WHMCS could not process encrypted module data.	The WHMCS encryption API failed, usually because the encryption hash changed.	Restore the hash, or reconnect the parent key and have customers rotate credentials.

Provisioning stays in “provisioning”

The service row exists but never reached active.

Check the operation history for the create failure and its error code.
Fix the cause using the tables above.
Retry from Recovery and reconciliation > Retry provisioning, or run Create from the service’s Module Commands.

Retrying is safe. The plugin reuses the sub-account if it already exists and only creates credentials the service still lacks.

Customer cannot send

Authentication errors from the API or SMTP

Have the customer reveal the credential again from the client area and compare it with what their application uses. If they rotated recently, make sure they confirmed the rotation and updated every application that uses the old credential. For SMTP, the username must be the sub-account handle shown on the page, not the customer’s email address.

Domain Lockdown or SPF rejection

Ask the customer to use Check domain on an API plan, or check the domain yourself with the check-domain tool. The _mailchannels TXT record must authorize the account that sends. See Domain Lockdown.

Sender Domain Not Found (550 5.1.2 [SDNF])

The sending domain has no valid A or MX record. The customer must add one. See Troubleshooting the Email API.

Limit reached

Compare the client area usage with the plan limit. If the customer is under their own limit but sending is blocked, check the Shared parent ceiling card. When the parent account reaches its limit, every sub-account is blocked until the next billing period.

Service suspended

WHMCS shows the service as suspended in the client area and hides the management panel. Unsuspend the service in WHMCS. If WHMCS shows it active but MailChannels has it disabled, reconciliation reports remote_lifecycle_drift. Run Unsuspend from Module Commands to re-apply the WHMCS state.

No delivery webhooks or DKIM signature

Messages sent over SMTP do not produce MailChannels delivery webhooks and are not DKIM-signed by MailChannels. This is expected. Customers who need either should send through the API. See Email API vs SMTP.

Reconciliation reports drift

See Fix drift for the meaning of each drift code and the module command that corrects it.

Client area shows “Usage: Unavailable” or an error

The page refreshes usage from MailChannels when the 15-minute cache expires. If MailChannels cannot be reached, the page shows the last cached values and a sanitized error. Check connectivity from the WHMCS server and the parent key status on the addon page.

Contact support

When you contact MailChannels support, include:

The plugin version, WHMCS version, and PHP version.
The operation, outcome, error code, and request ID from the operation history.
The sub-account handle. Never include credentials.

WHMCS: Get Started

WHMCS: Operate

WHMCS: Reference

Where to look

Error messages

Plugin messages

Provisioning stays in “provisioning”

Customer cannot send

Reconciliation reports drift

Client area shows “Usage: Unavailable” or an error

Contact support

​Where to look

​Error messages

​Plugin messages

​Provisioning stays in “provisioning”

​Customer cannot send

​Reconciliation reports drift

​Client area shows “Usage: Unavailable” or an error

​Contact support

Where to look

Error messages

Plugin messages

Provisioning stays in “provisioning”

Customer cannot send

Reconciliation reports drift

Client area shows “Usage: Unavailable” or an error

Contact support