Multi-domain hosting

Bongo hosts many mail domains on a single server. Every tenant domain shares one mail hostname, one TLS certificate and one set of listeners; each domain then gets its own DKIM key, catch-all, administrators and quota. This guide takes you from a running server to a fully configured tenant domain.

It assumes you already have a working single-node deployment (see deploy/README.md). The examples use mail.example.com as the shared mail hostname and tenant.com as a domain you are adding.

The shared-host model (read this first)

There is one mail hostname for the whole server, set once in config as smtp.hostname:

smtp {
  hostname = "mail.example.com"
}

Every domain you host points its MX and service records at that hostname — not at per-domain names. So tenant.com and another.com both have MX -> mail.example.com. This is why one certificate and one set of DNS service records cover every tenant: clients always resolve to, connect to and validate the same host. You do not add a domain in the HCL file; domains are created at runtime through the admin UI and stored in the cluster.

Consequences worth knowing up front:

  • One TLS certificate (for mail.example.com) secures SMTP, IMAP and the web UI for all tenants.
  • A tenant only needs A/AAAA records for the apex and a couple of client-discovery names; the mail itself always flows through mail.example.com.
  • Outbound mail for every domain leaves as mail.example.com, so that host needs correct forward and reverse DNS (PTR) and its own SPF/DKIM alignment.

1. Add the domain

As a global administrator, go to Admin → Domains (/admin/domains) and add tenant.com. Only a global admin can create or delete a domain; once it exists, you can delegate day-to-day management (see step 7).

A new domain starts enabled. You can disable it at any time from its Manage page. A disabled domain refuses all inbound mail (SMTP answers 550 5.1.1 for every address on it, including aliases and the catch-all) without being deleted; its accounts and stored mail are kept, and re-enabling restores delivery.

2. Open the domain’s Manage page

Click Manage next to the domain (/admin/domains/tenant.com). This page is the control centre for everything below: live DNS status, the record set to publish, DKIM, catch-all, administrators, owner and quota. It performs live DNS lookups each time you load it, so it doubles as your verification tool.

3. Publish DNS

The DNS Setup Records section lists exactly what to publish at the tenant’s DNS provider, generated for this server so the values never drift from what the status checks expect. Copy each row, or use Download BIND zone file to get them all at once (/admin/domains/tenant.com/dns.zone).

The record set is:

Type Host Value Purpose
A @, mail, autoconfig, autodiscover server IPv4 address apex + client-discovery names
AAAA @, mail server IPv6 address only when the mail host has an IPv6 address
MX @ 10 mail.example.com. route inbound mail to the shared host
TXT (SPF) @ v=spf1 mx ~all authorise the MX host to send
TXT (DMARC) _dmarc v=DMARC1; p=none; rua=mailto:postmaster@tenant.com reporting, policy none to start
TXT (DKIM) mail._domainkey v=DKIM1; k=rsa; p=... shown only after you generate a key (step 4)
SRV _imaps._tcp, _submissions._tcp (465), _submission._tcp (587), _autodiscover._tcp, _caldavs._tcp, _carddavs._tcp target mail.example.com. RFC 6186 client autodiscovery
TXT _caldavs._tcp, _carddavs._tcp path=/caldav/, path=/carddav/ CalDAV/CardDAV discovery path

Start DMARC at p=none so you can watch the rua reports before you enforce. Move to p=quarantine and then p=reject once SPF and DKIM are consistently passing.

If a tenant domain’s website is served by something other than Bongo, that web server should also redirect /.well-known/caldav and /.well-known/carddav to the mail host for every HTTP method; Apple tries the email domain first. See caldav-carddav.md.

Reading the DNS status checks

The DNS Configuration section shows the live state of each record against what this server expects. The legend below the table explains the four states:

  • Valid — the record is published and matches this server.
  • Missing — no matching record was found; publish it using the setup records above. For MX, Valid means at least one MX host name equals mail.example.com; a domain whose MX records all point elsewhere reads as Missing.
  • Not generated — nothing to check yet, e.g. no DKIM key exists.
  • Could not check — the DNS lookup failed or timed out; retry shortly.

DNS changes take as long as your TTLs to propagate. If a record reads Missing straight after publishing, give it time and reload.

4. Generate the DKIM key

In DKIM Signing, click Generate DKIM Key. Bongo creates a per-domain RSA-2048 key with selector mail, stores the private key in the cluster and starts signing outbound mail from tenant.com immediately. The page then shows the exact mail._domainkey.tenant.com TXT record to publish.

Publish that record, then reload the Manage page — the DKIM check should turn Valid once DNS propagates. Rotating a key follows the same flow, but note: mail signed with the new key will not verify until the new TXT record has propagated, so publish it promptly after rotating.

5. Verify SPF and DMARC

With SPF (v=spf1 mx ~all), DKIM published and DMARC in place, send a test message from a tenant.com account to an external provider (Gmail is convenient — “Show original” reports SPF, DKIM and DMARC results). You want SPF pass, DKIM pass aligned to tenant.com, and DMARC pass. The Manage page’s status checks should show all four rows Valid.

Forwarding: mail a user forwards (account forward address or a rule) leaves with an SRS envelope sender on that user’s own domain, so SPF at the next hop checks tenant.com, not the original author’s domain. tenant.com’s SPF record must therefore include this host. A user whose profile address is not on a hosted domain keeps the original sender, and the forward fails SPF at the next hop.

6. Set a catch-all (optional)

Catch-All Address routes any mail to an unrecognised address in the domain to one user. Enter the owning user’s ID; clear it to turn catch-all off. Use this sparingly — a catch-all receives spam addressed to guessed local parts.

7. Delegate administration

Bongo has two admin tiers:

  • Domain owner — set in the Domain Owner section (global-admin only). The owner has elevated trust for the domain and is implicitly a domain administrator.
  • Domain administrators — granted in the Domain Administrators section. They can manage users, aliases, DKIM and catch-all for this domain only.

Tenancy isolation is enforced server-side: a domain admin only ever sees and acts on their own domains. Requests for a domain they do not administer return 403, and they cannot enumerate users outside their domains. Creating and deleting domains, setting the owner and setting quotas remain global-admin actions.

8. Set per-domain quotas

In Quota (global-admin only) you can cap a domain:

  • Max users — the number of accounts whose primary domain is this domain (0 = unlimited). Enforced when a new user is created.
  • Max storage — aggregate stored-message bytes for the domain (0 = unlimited). Checked at SMTP delivery, IMAP APPEND, CalDAV/CardDAV PUT and web saves: once the domain is at or over quota those writes are refused. Usage is recomputed by the leader about every ten minutes, so this is a soft limit that can be overshot between recomputations.

9. Client autoconfiguration

Once the A records for autoconfig.tenant.com / autodiscover.tenant.com and the SRV records are published, mail clients set themselves up from just an address and password. Bongo serves:

  • Thunderbird / Mozilla — https://autoconfig.tenant.com/.well-known/autoconfig/mail/config-v1.1.xml
  • Outlook — https://autodiscover.tenant.com/autodiscover/autodiscover.xml
  • Apple Mail (iOS/macOS) — https://mail.example.com/.well-known/mobileconfig

All of them advertise the shared host mail.example.com with IMAPS on 993 and submission on 465 (implicit TLS) first, then 587 (STARTTLS). The Apple profile carries a single outgoing server, so it uses 465. When smtp.submissions_port is 0, or no smtp.tls certificate is configured, 465 is left out of all three. In production, bongo only answers autoconfig for domains it actually hosts, so a domain must exist (and be enabled) before autoconfig works for it.

Checklist

For each domain you host:

  • Domain created in Admin → Domains
  • A/AAAA, MX, SPF, DMARC and SRV records published (from the setup records)
  • DKIM key generated and its TXT record published
  • All four DNS status checks show Valid
  • Test message to an external provider shows SPF/DKIM/DMARC pass
  • Owner and/or domain administrators delegated (if handing off)
  • Quota set (if the domain should be capped)
  • A test client configured via autoconfig

See also

View this page's source on GitHub