Tenant Domain Setup Guide

Who Does What

Information To Collect First

• Primary domain, for example example.com.
• Mail hostname users will connect to, for example mail.example.com.
• Tenant admin email address.
• Expected mailbox addresses, such as support@example.com and billing@example.com.
• DNS provider login owner, such as Cloudflare, Route 53, GoDaddy, or the registrar.
• Whether mail is locally hosted by this server or by an external IMAP/SMTP provider.
• Whether the tenant needs S/MIME signing or encrypted outbound mail.

Required DNS Records

Replace example.com, mail.example.com, and 203.0.113.10 with the tenant's real values.

DKIM Public Key

DKIM has two parts: the private signing key stays on the mail server, and the public DNS key is added as a TXT record by the domain owner. Tenants should not receive or upload the private DKIM key.

The server operator or Super Admin should provide the tenant with:

Type: TXT
Name: default._domainkey.example.com
Value: v=DKIM1; k=rsa; p=<public-key-text>

The selector in the name, such as default, must match the server's OpenDKIM configuration.

Optional But Recommended DNS Records

MTA-STS

Type: A
Name: mta-sts
Value: 203.0.113.10

Type: TXT
Name: _mta-sts
Value: v=STSv1; id=20260521T000000Z

The policy must also be reachable at:

https://mta-sts.example.com/.well-known/mta-sts.txt

Use mode: testing first, then move to enforce after reports look healthy.

TLS-RPT

Type: TXT
Name: _smtp._tls
Value: v=TLSRPTv1; rua=mailto:tls-rpt@example.com

Use a mailbox that an admin or Super Admin can review.

Tenant Setup In The App

Only a Super Admin can create a tenant.

1. Log in as a Super Admin.
2. Open Admin Panel, then Tenants.
3. Click Server Setup Wizard and confirm the approved IMAP/SMTP hosts.
4. Click Add Tenant.
5. Enter the organization name, primary domain, approved IMAP/SMTP hosts, ports, user limit, and storage limit.
6. Save the tenant.
7. Create or assign a Tenant Admin for that tenant.

Mailbox User Setup

1. Tenant Admin opens Admin Panel, then Users.
2. Click User Wizard or Add User.
3. Enter the mailbox address, such as support@example.com.
4. Generate a temporary password.
5. Leave mailbox credentials blank when this deployment should provision the local mailbox automatically.
6. Give the temporary password to the user through a secure channel.

The user should sign in, click Password, and choose their own password. On provisioned local mailboxes, this also updates the IMAP/SMTP mailbox password.

Alias Setup

Aliases are managed in the app, but the mail server must also route them correctly.

1. Open Admin Panel, then Aliases.
2. Click Add Alias.
3. Enter the alias address, such as sales@example.com.
4. Choose the destination user.
5. Save.

S/MIME Identity Setup

S/MIME is different from DKIM. DKIM signs the domain's outbound mail at the server level. S/MIME signs or encrypts a user's individual messages with that user's certificate.

For S/MIME signing, the user or admin needs a PEM-formatted S/MIME certificate, the matching PEM-formatted private key, and the optional private key passphrase.

1. Log in as the user.
2. Click S/MIME in the top bar.
3. Paste the certificate PEM.
4. Paste the matching private key PEM.
5. Enter the passphrase only if the key requires one.
6. Click Save S/MIME Identity.

External Mail Client Details

Go-Live Checklist

• Tenant domain is correct in the app.
• Mail hostname resolves to the correct server.
• MX points to the mail hostname.
• SPF exists and authorizes the active sending path.
• DKIM TXT exists for the configured selector.
• DMARC exists, starting with p=none or a policy approved by the domain owner.
• Reverse DNS/PTR for the mail server IP is configured by the IP provider.
• Optional MTA-STS and TLS-RPT are configured.
• Test user can sign in to webmail, receive mail, and send mail.
• External IMAP/SMTP client setup works if needed.
• S/MIME status is healthy for users who need signing/encryption.

Troubleshooting