Webmail & Autoconfig
Two independent UX layers on top of Email Hosting, both optional:
- Webmail — a browser-based mail UI for users who don't want a desktop or mobile client. Requires an extra service (Roundcube) deployed alongside Stalwart.
- Autoconfig — endpoints that let Thunderbird, Apple Mail, and Outlook configure themselves from just an email + password. No extra deployment; built into kuploy-cloud.
You can ship either, both, or neither. Email still works without them — users just type IMAP/SMTP server names by hand.
| Want | Add |
|---|---|
| Casual / shared-machine users | Webmail |
| Easy desktop / mobile setup | Autoconfig |
| Full UX | Both |
Webmail
Tenants running Email Hosting can offer their end users a browser-based webmail client (Roundcube) running next to Stalwart. Once configured, end users see an Open Webmail button on their Mailboxes page.
Why offer webmail?
- Shared / public machines — users sign in without configuring a mail client.
- Mobile fallback — works on any device with a browser.
- Onboarding — new mailbox owners can read their welcome mail immediately, even before they install Thunderbird or Outlook.
If all of your customers already use desktop or mobile mail apps, webmail is optional and can be left disabled.
Roundcube
Kuploy Cloud's webmail story is Roundcube only. Roundcube is a mature, lightweight PHP webmail that maps 1:1 to what Stalwart provides (IMAP, SMTP submission, Sieve). Pairs cleanly, runs on ~256 Mi at idle, single-container Apache image.
We don't ship support for SOGo or other groupware suites — Stalwart is mail-first; layering a calendar/contacts UI on top would require more moving parts than the current Stalwart deployment supports.
Prerequisites
Roundcube reuses the cluster pieces you already have for kuploy-cloud itself. Required:
- Stalwart already deployed. Webmail is a thin shell over IMAP/SMTP; it has nothing to talk to without Stalwart. See Email Hosting.
- cert-manager with a working
ClusterIssuer(typicallyletsencrypt-prod— the same one you use for the kuploy-cloud dashboard). - An ingress controller (nginx is the default in kuploy-k8s).
- A free hostname on a domain you control, typically
webmail.<your-operator-domain>(e.g.webmail.gaveh.com). One hostname per kuploy-cloud instance, shared across all organizations on the instance.
No new ports, no new load-balancer IPs — Roundcube goes through the same HTTPS ingress as the rest of kuploy-cloud.
Setup
1. Deploy Roundcube
The recommended path is the kuploy-k8s deployer, which wires DNS, cert-manager, the Ingress, the Postgres database, and Roundcube's config in one go.
Full deployment (Stalwart + Roundcube together on a fresh install):
python deploy.py --edition cloud --domain console.example.com \
--mail-hostname mail.example.com \
--webmail-hostname webmail.example.com \
--stalwart-lb-ip <dedicated-ip>
Standalone (add Roundcube next to an already-running Stalwart):
python deploy.py webmail \
--mail-hostname mail.example.com \
--webmail-hostname webmail.example.com \
--postgres-service pg-postgresql-0.pg-postgresql-headless \
--postgres-secret postgres \
--db-namespace database
If you're not on kuploy-k8s (Docker Compose, hand-rolled Kubernetes, bare metal), deploy Roundcube yourself with the same shape:
- Single-container Apache image (
roundcube/roundcubemail:1.6.x-apache). - IMAP host = your Stalwart cluster, port 993, SSL.
- SMTP host = your Stalwart cluster, port 587, STARTTLS.
- ManageSieve host = your Stalwart cluster, port 4190, STARTTLS.
- A small Postgres DB for prefs and sessions.
2. DNS records
Add a single CNAME at your registrar pointing the webmail hostname at your kuploy-cloud ingress:
| Record | Host | Value |
|---|---|---|
| CNAME | webmail.example.com | <kuploy-cloud ingress hostname or IP> |
Find the ingress hostname or external IP with:
kubectl get ingress -n kuploy
# or, if you don't know which controller is in use:
kubectl get svc -A | grep LoadBalancer
cert-manager will pick up the new hostname and issue a TLS certificate automatically (HTTP-01 challenge typically resolves within a few minutes once DNS has propagated).
Use the same root domain as your mail server, such as mail.example.com
or webmail.example.com. Many users type the URL by hand the first time.
3. Surface the link to end users
If you deployed via kuploy-k8s, this step is automatic — the deployer
binds https://webmail.example.com into kuploy-cloud's platform config
as part of the deploy. The Open Webmail button appears on the
Mailboxes page within ~60 seconds of the deploy finishing. No
/admin/mail action needed.
The /admin/mail Webmail card will show the URL as read-only with a
"Managed by kuploy-k8s" badge. To change the URL or stop showing the
link, redeploy:
# Move to a new hostname
python deploy.py webmail --webmail-hostname new.example.com
# Stop showing the link
python deploy.py webmail --skip-webmail
This keeps DNS, TLS, Ingress, and Roundcube's trusted-host config in
sync — editing the URL field on /admin/mail alone would only change
the link target without those moving, leaving the button broken.
If you deployed manually (BYO Roundcube, docker-compose, …), set the URL by hand:
- Go to Admin → Mail Server Configuration (
/admin/mail). - Scroll to the Webmail card.
- In Webmail URL, enter the public URL where your webmail is reachable
(for example
https://webmail.example.com). - Click Save Webmail URL.
To remove the link later, return to the same card and click Clear, or save an empty value.
The URL is shared by every organization on the instance. There is no per-org webmail URL today.
What gets deployed
The kuploy-k8s manifest creates the following objects in your kuploy-cloud namespace:
| Resource | Name | Purpose |
|---|---|---|
| Deployment | roundcube | The Roundcube pod (1 replica, ~256 Mi at idle) |
| Service | roundcube | ClusterIP fronting the pod |
| Ingress | roundcube | TLS terminator for webmail.<your-host> |
| Certificate | roundcube-tls | cert-manager-issued TLS cert |
| ConfigMap | roundcube-config | Plugin + trusted-host config |
| (in Postgres) | roundcube DB + user | Prefs, sessions, address book |
| (in Stalwart) | new [server.listener.managesieve] on port 4190 | So Sieve filter editing in Roundcube works |
Roundcube is stateless beyond the Postgres database — no per-pod PVC, no operator-managed volume. Upgrading the image, restarting, or scaling horizontally are all safe.
Confirm everything is up after deploy:
kubectl get all -n kuploy -l app.kubernetes.io/component=webmail
kubectl get certificate -n kuploy roundcube-tls
kubectl get ingress -n kuploy roundcube
What end users see
Once webmail is configured, end users in any organization with email hosting enabled will see, on the Mailboxes page:
- The list of their mailboxes and aliases.
- An Open Webmail button at the top right of the page header.
- The IMAP / SMTP settings for their mailboxes (for use with Thunderbird, Outlook, Apple Mail, etc.).
They sign in to the webmail with the full email address as the username and the mailbox password they set when the mailbox was created.
Autoconfig
Kuploy Cloud serves Mozilla autoconfig.xml and Microsoft
autodiscover.xml for every domain that has mailboxes provisioned. When
a user types only their email address and password in Thunderbird,
Apple Mail, or Outlook, the client fetches one of these
documents and configures IMAPS / SMTP submission automatically against
your Stalwart server. Users do not need to remember server hostnames or
port numbers.
Autoconfig is a peer of Webmail, not a sub-feature of it. They cover different users:
- Autoconfig helps people who want to use a desktop or mobile mail app — they don't have to know your mail server's hostname or port.
- Webmail helps people who don't want to install a mail app at all.
You can enable either, both, or neither.
What gets served
The XML response pins:
- IMAP —
mail.<your-instance-host>, port 993, SSL/TLS. - SMTP —
mail.<your-instance-host>, port 587, STARTTLS. - Username — the user's full email address.
Same hostname your MX record points at — your kuploy-cloud instance's mail server. No additional configuration on your side.
DNS — pointing clients at the autoconfig endpoints
For Thunderbird / Outlook to actually find your kuploy-cloud autoconfig endpoint, two CNAME records per domain are needed:
| Record | Host | Value |
|---|---|---|
| CNAME | autoconfig.<domain> | mail.<your-instance-host> |
| CNAME | autodiscover.<domain> | mail.<your-instance-host> |
These records are surfaced automatically in the DNS Records panel on the Mailboxes page, alongside the existing MX/SPF/DKIM/DMARC rows. Add them at your registrar the same way you add the others.
The standard .well-known paths on the customer's main domain are
also accepted — https://<domain>/.well-known/autoconfig/mail/config-v1.1.xml
and https://<domain>/autodiscover/autodiscover.xml — if your reverse
proxy already routes traffic for that hostname through kuploy-cloud,
that's enough and the CNAMEs aren't strictly needed.
Pushing records automatically
If the mail domain was purchased through this kuploy-cloud instance (via Namecheap or Enom), you don't have to add records by hand:
- Open the Mailboxes page in any organization that owns the domain.
- Click DNS on the domain row to expand the records panel.
- Click Push to Namecheap (or Push to Enom) at the top of the panel.
All six records — MX, SPF, DKIM, DMARC, plus the two autoconfig
CNAMEs — are written in one call. Existing non-mail records on the
domain (your apex A record, www CNAME, third-party verification
TXTs) are preserved.
The button doesn't appear for domains added by your customers from a third-party registrar; for those, paste the records into the registrar's UI manually and click Verify.
What the user experience looks like
A user adds their email account in Thunderbird:
- Clicks Add Account, types
alice@example.com+ password. - Thunderbird fetches
https://autoconfig.example.com/mail/config-v1.1.xml?emailaddress=alice@example.com. - Receives back the IMAPS + SMTP submission settings for your mail server.
- Connects, validates the credentials, and is in their inbox — no manual server settings.
The same flow works in Apple Mail and Outlook (which use
autodiscover.example.com instead).
FAQ
Does kuploy-cloud host the webmail for me? No. The platform only stores the URL and links to it. You choose, deploy, and operate the webmail.
Can different organizations use different webmails? Not today. The webmail URL is a single per-instance setting and is shared by all organizations on that instance.
Can I use a third-party webmail like Gmail or Outlook.com? Only if it lets users add an external IMAP/SMTP account. The link from the Mailboxes page is informational — it points to a sign-in page, not a pre-authenticated session.
What happens if I unset the Webmail URL?
The Open Webmail button disappears from the Mailboxes page in every
organization. Existing IMAP/SMTP connections from desktop and mobile clients
are unaffected. If the URL was set by kuploy-k8s, you unset it by
redeploying with --skip-webmail, not by clearing the field on /admin/mail
(the field is read-only in that case).
Why is the Webmail URL field read-only on /admin/mail?
You deployed Roundcube via kuploy-k8s, so the URL is locked to whatever
the deployer set. Editing it alone would only change the link target —
not DNS, TLS, Ingress, or Roundcube's trusted hosts — and leave the
button broken. To change it, redeploy with a new
--webmail-hostname. Manual override (rare emergencies) is documented in
the deployer's docs/webmail.md.
Do I need autoconfig if I have a webmail? No — they're independent. Many tenants ship both. Webmail covers browser-only users; autoconfig saves desktop/mobile users from typing server settings.
Why doesn't the autoconfig CNAME show as "Verified" after I click Verify? The current verification badge only checks MX/SPF/DKIM/DMARC. The CNAME rows are informational. If the records are correctly set at your registrar, autoconfig will work even though the badge doesn't flip.