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. Seeing an alias in the portal confirms the app database mapping; it does not, by itself, prove Postfix is routing production inbound mail to that mailbox.

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.
6. Send a test message to the alias.
7. Ask the server operator to confirm the Postfix route maps the alias to the intended mailbox.
8. Confirm mail event logs show the alias as the original recipient and the destination mailbox as delivered.

Operators can import recent Postfix send/receive metadata into the app database without message bodies:

cd /home/jason/email-servers/emailresellerserver
node scripts/import-mail-events.js --since-minutes=1440 /var/log/mail.log

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 an S/MIME certificate issued for the user's email address, the matching private key as PEM material or inside an exportable PKCS#12/PFX bundle, and the optional private key passphrase.

1. Log in as the user.
2. Click S/MIME in the top bar.
3. To import a .p12 or .pfx bundle, choose it under Import PKCS#12 / YubiKey Backup, enter the bundle passphrase if required, and click Import Bundle.
4. To paste PEM material manually, paste the certificate PEM and matching private key PEM.
5. Enter the private key passphrase only if the key requires one.
6. Click Save S/MIME Identity for manual PEM setup.

YubiKey Quick Start

1. Plug in the YubiKey.
2. Log in to the account you want to protect.
3. In the portal, open MFA and use Security Key / YubiKey > Add YubiKey.
4. Follow the browser prompt and touch the YubiKey when it flashes.
5. Set up a spare YubiKey so the user is not locked out if one key is lost.

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