Webmail has two halves. cPanel creates and manages the mailboxes; IMAP and SMTP read and send the mail. You configure both on Settings → Webmail, and there is a test button for each.

You need a cPanel account you control.

This connects to your own hosting account’s cPanel, using an API token you create there. It is not a service WBAMS provides.

Create the cPanel API token

  1. Sign in to cPanel on the account that hosts the mail domain.
  2. Open Security → Manage API Tokens.
  3. Create a token, name it something you will recognize later such as wbams-webmail, and set no expiry unless you have a process for rotating it.
  4. Copy the token immediately. cPanel shows it once and will not show it again.
A cPanel API token is a powerful credential.

It can act on the account. Store it only in WBAMS, never in a ticket, a chat message or a screenshot, and revoke it in cPanel the moment it is no longer needed.

Connect cPanel

  1. Open Settings → Webmail in WBAMS.
  2. Hostname — the cPanel server hostname, for example server.example.com. Not the website domain, unless they are the same machine.
  3. Port — the cPanel API port. The default is correct for most hosts; change it only if your host says otherwise.
  4. cPanel username — the account username, not an email address.
  5. API token — paste the token you just created.
  6. Leave Verify the server certificate on. Turn it off only for a staging server with a self-signed certificate, and never in production.
  7. Press Test cPanel connection. Fix any failure before going further — nothing downstream works until this passes.

IMAP and SMTP

These are the servers the webmail app itself talks to when a customer reads or sends mail.

  1. IMAP host and IMAP port — usually the same server, port 993 with SSL/TLS.
  2. IMAP security — SSL/TLS for 993, STARTTLS for 143. Do not run either without encryption; mail passwords cross this connection.
  3. SMTP host, SMTP port and SMTP security — usually 465 with SSL/TLS, or 587 with STARTTLS.
  4. Press Test IMAP. A failure here with a passing cPanel test is almost always a firewall or a port, not a credential.

Offer it to customers

  1. Turn on Offer webmail.
  2. Mail domain — the domain addresses are created under, for example example.com.
  3. Webmail address — the URL the webmail app is served from. Point a subdomain such as email.example.com at the installation’s webmail directory and enter it here.
  4. Who can use it — decide whether every customer sees it or only those whose products include mailboxes.
  5. Administrator roles — which of your own roles may administer mailboxes.
  6. Set Name, Accent color and Logo so the webmail app looks like yours rather than generic.

Mailbox allowances

How many mailboxes a customer may create comes from their product. Set the allowance on the product rather than per customer, so it follows upgrades and downgrades automatically.

Verify end to end

  1. As an administrator, create a mailbox from Webmail → Mailboxes.
  2. Sign in to the webmail address with that mailbox and confirm the folder list loads.
  3. Send a message to an outside address and confirm it arrives.
  4. Reply from outside and confirm it appears in the mailbox.
  5. Finally, sign in to the client area as a test customer and confirm the mailbox manager appears for them.

When it does not work

cPanel test fails
Wrong hostname, wrong port, or a token that has been revoked. Check the hostname is the server, not the website.
cPanel passes, IMAP fails
A firewall between your web server and the mail server, or the wrong security setting for the port.
Customers see no webmail link
Who can use it is restricted, or their product carries no mailbox allowance.
Webmail address returns 404
The subdomain is not pointed at the installation’s webmail directory.