Webmail reads mail from one of two systems, and Setup → Webmail asks which. Under cPanel, cPanel creates and manages the mailboxes and IMAP and SMTP read and send the mail; you configure both, and there is a test button for each. Under Microsoft 365, the mailboxes are made in your Microsoft tenant and people sign in with Microsoft; you register an application in Microsoft Entra ID and give WBAMS its three values.
Choose the mail system
- Open Setup → Webmail in WBAMS and confirm your password when asked.
- Mail domain — the part after the @ in your addresses:
sales@example.orgmeansexample.org. Use the domain itself, not the mail host. - Mail system — cPanel if your mail is on your hosting account, Microsoft 365 if Microsoft delivers it. Save. The screen then shows only the setup for the system you chose.
Switching systems does not erase the other system's settings. A webmail session already open keeps working the way it signed in; the setting decides what the next sign-in does.
cPanel: create the API token
This connects to your own hosting account’s cPanel, using an API token you create there. It is not a service WBAMS provides.
- Sign in to cPanel on the account that hosts the mail domain.
- Open Security → Manage API Tokens.
- 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. - Copy the token immediately. cPanel shows it once and will not show it again.
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.
cPanel: connect
- Hostname — the cPanel server hostname, for example
server.example.org, withouthttps://or a port. Not the website domain, unless they are the same machine. - Port — the cPanel API port. The default is correct for most hosts; change it only if your host says otherwise.
- cPanel username — the account username, not an email address.
- API token — paste the token you just created. It is stored encrypted and never shown again; leave the field empty to keep the stored one.
- Leave Verify the server certificate on. Turn it off only for a staging server with a self-signed certificate, and never in production.
- Press Test cPanel connection. Fix any failure before going further — nothing downstream works until this passes.
cPanel: IMAP and SMTP
These are the servers the webmail app itself talks to when somebody reads or sends mail. Under Microsoft 365 they are fixed by Microsoft and the card is not shown.
- IMAP host and IMAP port — usually the same server, port 993 with SSL/TLS.
- IMAP security — SSL/TLS for 993, STARTTLS for 143. Do not run either without encryption; mail passwords cross this connection.
- SMTP host, SMTP port and SMTP security — usually 465 with SSL/TLS, or 587 with STARTTLS.
- Press Test IMAP. It opens an IMAP session and reads the server's capabilities without signing in to a mailbox. A failure here with a passing cPanel test is almost always a firewall or a port, not a credential.
Microsoft 365: register the application
Microsoft has permanently disabled password sign-in for IMAP, so a Microsoft 365 mailbox is opened with Microsoft sign-in instead. WBAMS needs an application registration in your tenant.
- Set the Webmail address first (see below) and save. It must start with
https://, because Microsoft will not return a sign-in over plain HTTP. - In the Microsoft Entra admin center, create an app registration for WBAMS webmail.
- Copy the exact string Setup → Webmail shows under Redirect URI to register, trailing slash included, and add it to the registration as a Web redirect URI. It must match byte for byte.
- From the registration's Overview page, copy the Directory (tenant) ID and the Application (client) ID into the fields of the same names.
- Create a client secret and paste its Value — not its Secret ID — into Client secret. It is stored encrypted and never shown again.
- Make sure the tenant consents to the permissions webmail asks for when someone signs in: reading mail over IMAP and sending over SMTP (
IMAP.AccessAsUser.All,SMTP.Send), sending through Microsoft Graph (Mail.Send), andopenid,profile,emailandoffline_access. - Save. The Status card should read Signed in through Microsoft for your mail domain.
Diary the date. Sign-in stops working the day the secret does, until a new one is entered.
Under Microsoft 365 WBAMS creates no mailboxes and offers nobody an automatic address: those mailboxes are made in Microsoft by whoever administers the tenant. Sending goes through Microsoft Graph and falls back to SMTP when Graph refuses; a tenant that has not consented to Mail.Send still sends, through SMTP.
Offer it
- Turn on Offer webmail.
- Webmail address — the URL the webmail app is served from. Point a subdomain such as
mail.example.orgat the installation’swebmaildirectory and enter it here. Do not useexample.org/webmailon cPanel hosting: cPanel answers that path with its own login, so it can never reach WBAMS webmail, and the field still saves it as typed. - Who can use it — clients, members, staff and administrators, as many as apply. This decides who is offered an Email page; it does not lock the mail itself.
- Administrator roles — which of your own roles may use it, when administrators are ticked.
- Set Name, Accent color and Logo so the webmail app looks like yours rather than generic.
Mailbox allowances
How many mailboxes a client may create comes from their products: set the allowance on the product rather than per client, so it follows upgrades and downgrades automatically. Members and staff get a figure for the whole level, overridable on one record. Under cPanel you also set the default and largest mailbox size; under Microsoft 365 the tenant decides sizes and those fields are not shown. See Mailbox allowances.
Verify end to end
- Under cPanel, create a mailbox as an administrator from Webmail → Mailboxes. Under Microsoft 365, use a mailbox that already exists in the tenant.
- Sign in at the webmail address with that mailbox — with its password under cPanel, with the Microsoft button under Microsoft 365 — and confirm the folder list loads.
- Send a message to an outside address and confirm it arrives.
- Reply from outside and confirm it appears in the mailbox.
- Finally, sign in to the client area as a test customer and confirm the Email page appears for them.
When it does not work
webmail directory, or the address ends in /webmail on a cPanel host.