Default Subdomain & Custom Primary Domain #

TsubameMail supports immediate out-of-the-box email delivery using a platform-allocated subdomain (<slug>.<base>), as well as seamless transition to your own custom domain (acme.example.invalid).

Domain Lifecycle Rules #

  1. Immediate Subdomain Allocation: When a tenant <slug> is onboarded, the platform provisions <slug>.<base> with status verified and designates it as the tenant's initial primary domain. You can create mailboxes (alice@<slug>.<base>) and send/receive mail right away without waiting for external DNS propagation.
  2. Custom Domain Binding: Register your custom domain (POST /v1/domains with {"tenant": "<tenant-id>", "name": "acme.example.invalid"}), publish the _tsubame-verify TXT challenge, and complete verification (POST /v1/domains/verify).
  3. Switching the Primary Domain: Once a custom domain is verified, promote it to the tenant's primary domain (POST /v1/domains/primary) via the Tenant Console or API.
  4. Permanent Subdomain Retention:
IMPORTANT

Allocated Subdomains Are Never Deactivated: Even after you switch your primary domain to a custom domain (such as acme.example.invalid), your original platform subdomain (<slug>.<base>) remains permanently active and non-reclaimable. Existing addresses (user@<slug>.<base>), aliases, and historical routing continue delivering mail without interruption.

Primary Switch Verification Checklist #

  • Confirm acme.example.invalid shows status: verified and valid MX / SPF / DKIM / DMARC records (see DNS Records).
  • Switch primary domain in Domain Settings (POST /v1/domains/primary).
  • Verify new outbound defaults use @acme.example.invalid while inbound messages addressed to @<slug>.<base> still land in the corresponding user mailboxes.