Provide mail through an SMTP gateway

Workspace owns mailboxes and webmail. An upstream gateway such as Proxmox Mail Gateway remains the public SMTP edge and retains MX, PTR, reputation, DKIM, filtering, and the external queue.

This operations guide is for Workspace and mail administrators. It leads from the tenant-bound access check to verifiable inbound and outbound tests. At the end, Workspace manages personal and shared mailboxes plus distribution lists, while the gateway continues to own public mail delivery. See Integrate the mail API and gateway handoff for the technical API contract.

Check access and the agent workflow

Log in to the target tenant with nucli. Check the identity, mail permissions, and reachable mail endpoints before changing state:

nucli --tenant <tenant> whoami --scopes
nucli --tenant <tenant> api GET /api/v1/mail/mailboxes --summary
nucli --tenant <tenant> api GET /api/v1/mail/admin/domains --summary

An automated agent reads the built-in mail workflow before it starts:

nucli skills show mail

The skill uses only tenant-bound HTTP. It must not use database access, numin, Storage paths, or gateway access to bypass authentication, tenancy, permissions, or mail contracts. Mailbox roles and ResourceACL grant mail content access; a tenant administrator role alone does not.

Prepare mailboxes

1. Create the hosted domain through POST /api/v1/mail/admin/domains.
2. Create personal or shared mailboxes through POST /api/v1/mail/admin/mailboxes.
3. Add shared-mailbox members through POST /api/v1/mail/admin/mailboxes/{id}/memberships.
4. Create distribution lists separately through POST /api/v1/mail/admin/distribution-lists.
5. Set tenant configuration storage.context.mail.store_id to the existing encrypted mail store.
6. If required, set a logical mailbox limit through PUT /api/v1/mail/admin/mailboxes/{id}/quota. A value of 0 means unlimited. For a mailbox that predates quota tracking, first reconcile its occupied storage through POST /api/v1/mail/admin/mailboxes/{id}/quota/reconcile. The server rejects a positive quota until this explicit, audited reconciliation has completed.

Distribution lists fan out delivery to target mailboxes. Shared mailboxes instead share work state, assignment, and sender rules.

Pass write payloads as protected files so addresses and identity IDs do not enter shell history:

nucli --tenant <tenant> api POST /api/v1/mail/admin/domains \
  --input mail-domain.json --summary
nucli --tenant <tenant> api POST /api/v1/mail/admin/mailboxes \
  --input mailbox.json --summary
nucli --tenant <tenant> api POST \
  /api/v1/mail/admin/mailboxes/<mailbox-id>/memberships \
  --input membership.json --summary
nucli --tenant <tenant> api POST /api/v1/mail/admin/distribution-lists \
  --input distribution-list.json --summary

Use personal or shared as the mailbox type and owner, editor, or viewer as the membership role. Grant a new member historical access only through an explicit, audited historyGrantedFromAt decision. Every mutation requires explicit administrator approval.

Secure the private handoff

Enable mail.handoff.mailbox.enabled only after configuring:

• a private or loopback mail.handoff.mailbox.bind_address;
• the internal mail.handoff.mailbox.port;
• mail.handoff.mailbox.tls.cert_file and mail.handoff.mailbox.tls.key_file;
• mail.handoff.mailbox.tls.client_ca_file; and
• authorized certificate fingerprints in mail.handoff.mailbox.gateway_sha256.

The listener requires TLS 1.3 and a valid client certificate. PMG may remove a message from its queue only after successful recipient validation and the final 250 stored. Normal delivery and DSNs use separate recipient routers on this private handoff.

Route delivery and bounces

Point the existing tenant SMTP configuration only at the gateway. Workspace does not deliver directly to foreign MX servers. Set mail.outbound.bounce_domain to the bounce domain routed back by the gateway.

Choose one explicit authentication mode for every new SMTP revision:

Workspace does not negotiate a different mode or fall back to another mechanism. If an older SMTP revision has no mode, create a replacement revision, verify its connection, and activate that exact revision.

Connect Mailpit with encryption

Mailpit can provide and require STARTTLS itself. Mount a stable server certificate and key, then require STARTTLS:

MP_SMTP_TLS_CERT=/certs/mailpit.crt
MP_SMTP_TLS_KEY=/certs/mailpit.key
MP_SMTP_REQUIRE_STARTTLS=true

The hostname stored in the SMTP revision must be covered by the certificate, and Workspace must trust the issuing certificate authority. Configure the SMTP revision with authMode=none, encryption=starttls, an empty username, and no credential. Keep insecure certificate exceptions disabled. A new self-signed certificate generated on every restart is unsuitable for stable verification because its trust anchor changes as well.

A proxy is not required for this setup. If the operational PKI terminates TLS centrally, the proxy must provide the complete SMTP STARTTLS flow to Workspace and present a certificate that Workspace trusts. Protect the connection from the proxy to Mailpit with verified TLS as well. A plain TCP TLS terminator or implicit TLS on an SMTPS connection does not replace STARTTLS and therefore does not match the none mode contract.

After setup, verify that Mailpit rejects message submission without STARTTLS and that the SMTP trace contains no AUTH after STARTTLS. The relevant Mailpit options are listed in the Mailpit SMTP configuration.

Workspace stores DSNs encrypted, copies the sent message's content ACL, and shows the separate queue state for every envelope recipient in the thread.

Transfer existing mailboxes safely

Workspace does not connect to Zimbra or another IMAP server during migration. An external adapter reads the source system and submits folders, unchanged RFC822 messages, original dates, and flags to the provider-neutral transfer API. Source-system credentials therefore remain outside Workspace.

The transfer consists of one baseline and any number of deltas:

1. Bind a transfer session to exactly one destination mailbox.
2. Declare every source folder, including Sent and custom subfolders.
3. Create a batch with expected counts, bytes, and manifest hashes.
4. Upload each item as a strictly ordered multipart payload containing metadata followed by a message/rfc822 stream. Tombstones have no message body.
5. Queue reconciliation and poll the batch until it reaches ready.
6. Publish only a ready batch. Replays are idempotent; reusing a source key with different content is rejected.

Imported folders appear as read-only source folders in the mail workbench. New mail can arrive through the private SMTP handoff into the same mailbox while migration is in progress.

Before routing cutover, run a complete baseline, a delta, and one final delta. Compare folder and batch counts, bytes, and manifest hashes. For rollback, an authorized client creates POST /api/v1/mail/mailboxes/{mailboxID}/exports. Once complete, the export job provides either a full snapshot or an exact mailbox-revision delta. Importing that artifact into the target remains the external adapter's responsibility.

Change MX, PTR, SPF, DKIM, and DMARC only in a separately approved operations change. Workspace never changes that external configuration.

Verify the deployment

The deployment is complete when all of these checks succeed:

1. GET /api/v1/mail/mailboxes shows only the personal and shared mailboxes granted to the test identity.
2. A test message to a hosted address receives 250 stored on the private handoff only after durable Storage persistence and then appears in the mail workbench.
3. An approved outbound test first reaches stored and queued state. Then check every envelope recipient; queued does not mean delivered.
4. With none, the gateway SMTP trace contains STARTTLS but no AUTH. Also verify at the gateway that an unauthorized source address and sender domain are rejected.
5. An intentionally generated DSN enters through the separate bounce router and attaches to the sent thread.
6. A shared-mailbox member sees only the granted history range and can read or send only as allowed by the assigned role.
7. A distribution list delivers an authorized test message to its configured target mailboxes without creating shared work state.
8. Every declared source folder is visible, reconciliation and export have completed, and the exported artifact passes hash verification.

Users continue with Work with mail.

Plan an installation without PMG

The product core does not depend on PMG. An installation without an existing gateway needs a separately operated mail edge based on established MTA software. That edge owns the same public responsibilities and uses the same private mTLS handoff. Ship it only after a dedicated licensing, security, update, and operations gate; the Workspace server does not become a public MTA.