Wissensdatenbank

The WHMCS PolarisMail Module allows you to sell individual email accounts on approved shared domains through WHMCS. This is useful when you want customers to order addresses such as name@yourdomain.com instead of requiring them to bring their own custom domain.

The module supports mailbox provisioning, suspend/unsuspend, termination, password changes, quota changes, aliases, distribution lists, and client area mailbox tools.

What the module does

The WHMCS PolarisMail Module can:

• Provision mailbox accounts automatically when an order is accepted.
• Sell email accounts on approved shared domains.
• Restrict orders to specific house domains.
• Protect reserved mailbox names such as admin, support, abuse, and postmaster.
• Allow customers to change mailbox passwords from the WHMCS client area.
• Allow customers to create and manage aliases.
• Allow customers to create and manage distribution lists.
• Suspend, unsuspend, and terminate mailboxes from WHMCS.
• Update quota, language, timezone, and account type using WHMCS package changes.
• Connect to the PolarisMail / EmailArray admin API.

Requirements

Before installing the module, make sure you have:

• WHMCS 8.x recommended.
• PHP 8.1 or higher recommended.
• cURL enabled in PHP.
• A compatible PolarisMail / EmailArray admin API account.
• API access to the admin JSON endpoint.
• At least one domain already configured in PolarisMail / EmailArray.
• Server credentials for the PolarisMail / EmailArray admin API.

The default API endpoint used by the module is:

https://cp.emailarray.com/admin/json.php

Upload the module files

Unzip the module package.

Upload the module folder:

thexyz_polarismail

to your WHMCS server module directory:

/modules/servers/thexyz_polarismail/

The final path should look like this:

/modules/servers/thexyz_polarismail/thexyz_polarismail.php
/modules/servers/thexyz_polarismail/lib/lists.php
/modules/servers/thexyz_polarismail/templates/clientarea.tpl
/modules/servers/thexyz_polarismail/templates/distribution-lists.tpl
/modules/servers/thexyz_polarismail/templates/partials/nav.tpl
/modules/servers/thexyz_polarismail/lang/english.php

Install the optional WHMCS hook

The package also includes a hooks.php file that cleans up the WHMCS client area display for this mailbox product.

Upload or copy:

/modules/servers/thexyz_polarismail/hooks.php

to:

/includes/hooks/thexyz_polarismail_ui_overrides.php

This hook removes unrelated hosting/domain interface elements from the product details page and improves the mailbox product display.

Create a WHMCS server

In WHMCS admin, go to:

System Settings > Servers

Click Add New Server.

Use settings similar to the following:

Click Test Connection.

If the connection succeeds, save the server.

Create a server group

Go to:

System Settings > Servers > Create New Group

Create a group such as:

PolarisMail Servers

Add the PolarisMail server to the group and save.

Create the WHMCS product

Go to:

System Settings > Products/Services

Create a new product group if needed, such as:

Email Services

Then create a new product.

Suggested product name:

Premium Email Account

Set the product type to:

Other

You can also use a name such as:

Thexyz Email Mailbox

or:

Personal Email Account

Set the product module

Inside the product settings, open the Module Settings tab.

Choose:

Thexyz Mailboxes

Select your PolarisMail server group.

Set Automatic Setup based on your preferred workflow. Common options are:

Automatically setup the product as soon as the first payment is received

or:

Automatically setup the product when you manually accept a pending order

Configure module settings

The module includes the following configuration options.

API Endpoint

Default:

https://cp.emailarray.com/admin/json.php

This is the PolarisMail / EmailArray admin JSON API endpoint.

Allowed Domains CSV

Enter the shared domains customers are allowed to order mailboxes on.

Example:

thexyz.com,thexyz.ca,thexyz.cn

Only domains listed here can be used for provisioning.

Default Account Type

Choose the default mailbox account type:

1|Basic
2|Enhanced

Use Basic for standard mailboxes and Enhanced for higher-tier mailbox plans.

Default Quota GB

Set the default mailbox quota in GB.

Example:

25

This can be overridden with a WHMCS configurable option called:

Mailbox Quota (GB)

Max Aliases

Set the maximum number of aliases a customer can create from the WHMCS client area.

Example:

25

Use:

0

for unlimited aliases.

Allow External Forwards

Enable this if customers are allowed to forward aliases to external email addresses.

If disabled, alias forwarding must stay within the mailbox domain.

Default Timezone

Example:

America/Montreal

This is passed to the mail platform when the mailbox is created.

Default Date Format

Example:

yyyy-mm-dd

Default Language

Default:

en

Available module options include:

en
pt-br
id
es
de
fr

Max Distribution Lists

Set the maximum number of distribution lists the customer can create.

Example:

5

Use:

0

for unlimited distribution lists.

Create the mailbox custom field

The module needs a mailbox handle from the customer. This is the part before the @.

For example, if the customer wants:

michael@thexyz.com

the mailbox handle is:

michael

In the WHMCS product, go to the Custom Fields tab.

Create a custom field:

The module validates mailbox names and blocks reserved addresses.

Allowed mailbox characters include:

a-z
0-9
.
_
-

The mailbox handle must start and end with a letter or number.

Domain selection options

There are two common ways to set the domain.

Option 1: Use the WHMCS domain field

You can enter the domain directly on the WHMCS service.

Example:

thexyz.com

This domain must also be listed in Allowed Domains CSV.

Option 2: Use one allowed domain only

If your product only sells mailboxes on one shared domain, enter only one domain in Allowed Domains CSV.

Example:

thexyz.com

When only one domain is allowed, the module can use it automatically.

Optional configurable options

You can create WHMCS configurable options to let customers choose plan settings.

Account Type

Create a configurable option named exactly:

Account Type

Suggested options:

Basic
Enhanced

The module accepts either text labels or numeric values.

Mailbox Quota GB

Create a configurable option named exactly:

Mailbox Quota (GB)

Suggested options:

10
25
50
100

If this option exists, it overrides the module’s default quota setting.

Reserved mailbox names

The module blocks common reserved handles such as:

admin
administrator
abuse
billing
contact
hostmaster
info
mail
mailer-daemon
noreply
no-reply
postmaster
root
sales
security
support
webmail
www

This helps prevent customers from registering sensitive or operational mailbox addresses.

Test the module

After configuring the product, place a test order.

Use a test mailbox such as:

testuser

If your allowed domain is:

thexyz.com

the module should provision:

testuser@thexyz.com

After accepting the order or receiving payment, check that:

• The WHMCS service shows as active.
• The mailbox exists in PolarisMail / EmailArray.
• The customer can view the product in the WHMCS client area.
• Password change works.
• Alias creation works.
• Distribution list creation works, if enabled.
• Suspend and unsuspend work from the WHMCS admin service page.
• Terminate removes the mailbox.

Client area features

Customers can manage their mailbox from the WHMCS product details page.

Depending on your configuration, they can:

• View their mailbox address.
• Change their mailbox password.
• Generate one-time webmail access.
• Create aliases.
• Remove aliases.
• Create distribution lists.
• Add and remove distribution list members.

Troubleshooting

Test Connection fails

Check the following:

• Server username is correct.
• Server password is correct.
• API endpoint is correct.
• cURL is enabled on the WHMCS server.
• The WHMCS server can connect outbound to the API endpoint.
• The API account has admin permissions.

Mailbox creation fails

Check:

• The domain is listed in Allowed Domains CSV.
• The domain exists in PolarisMail / EmailArray.
• The customer entered a valid mailbox handle.
• The mailbox handle is not reserved.
• The mailbox does not already exist.
• The generated WHMCS password meets the mailbox password policy.

“No domain found” error

The module could not determine which domain to use.

Fix this by either:

• Entering a domain on the WHMCS service, or
• Setting only one domain in Allowed Domains CSV.

Domain not allowed error

The selected domain is not in the module’s Allowed Domains CSV list.

Add the domain to the list or choose an approved domain.

Password change fails

The mailbox platform may reject passwords that are too weak, reused, or contain invalid characters.

The module requires mailbox passwords to be at least:

10 characters

Passwords cannot contain spaces.

Aliases are not saving

Make sure the module has created its local alias table:

mod_thexyz_pm_aliases

This table is normally created automatically when the module runs.

Also check that the WHMCS database user has permission to create tables.

Distribution lists are not working

Make sure the module’s list support file exists:

/modules/servers/thexyz_polarismail/lib/lists.php

Also confirm the customer has not reached the configured Max Distribution Lists limit.

WHMCS module logs

To review API requests and errors, go to:

Utilities > Logs > Module Log

Enable module logging if needed.

Then test the module again and review the request and response details.

Disable module logging when finished, as logs may contain sensitive API or account details.

Security notes

For best results:

• Use strong WHMCS admin credentials.
• Use a dedicated PolarisMail / EmailArray API admin account if possible.
• Restrict allowed domains carefully.
• Keep reserved handles protected.
• Do not allow customers to register operational addresses such as abuse, postmaster, or security.
• Keep WHMCS and PHP updated.
• Remove or restrict external forwarding if you want tighter control over abuse risk.

Summary

The WHMCS PolarisMail Module makes it possible to sell individual mailbox accounts through WHMCS on approved shared domains. Once installed, customers can order email addresses, manage their mailbox password, create aliases, and use distribution lists from the WHMCS client area, while administrators can manage provisioning using standard WHMCS service actions.