If you started with shared domains for disposable inboxes, you made the right trade-off: zero DNS work, fast iteration, and a clean way to unblock CI, QA, or an LLM agent workflow.
But shared domains eventually hit predictable limits: enterprise allowlisting, stricter governance, environment separation, and deliverability control. That is where a disposable email custom domain becomes the pragmatic next step.
This post is a migration plan you can execute with minimal risk. It is written for teams that already consume emails programmatically (webhook or polling), and want to cut over from shared domains to a custom domain without breaking tests, agents, or signup verification flows.
If you are implementing this with Mailhook, keep the canonical integration contract handy: mailhook.co/llms.txt.
What changes when you move from shared domains to a custom domain?
With shared domains, your provider owns DNS and reputation. You “just” provision inboxes and receive messages.
With a custom domain, you also own:
- DNS routing (MX records) so inbound mail actually reaches your inbox provider.
- Governance and allowlisting (you can ask customers, partners, or internal security teams to allowlist your domain).
- Separation (one subdomain per environment or tenant, instead of a shared pool).
Your application code should not need a rewrite if you already modeled “email as an inbox” (email address plus an inbox handle or ID), and you treat email receipt as an event stream.
When a custom domain is worth it (and when it is not)
A custom domain is usually worth migrating to when at least one of these becomes true:
- You need allowlisting compatibility (customer environments, enterprise staging, regulated networks).
- You want reputation isolation (your traffic should not be affected by other tenants on a shared domain).
- You want stable environment boundaries (dev, staging, prod-like, per-tenant).
- You want auditable routing (a predictable domain that your organization controls).
It is usually not worth it yet when:
- You are still prototyping the workflow and domain governance would slow you down.
- Your tests only need email for validation-only scenarios (in which case reserved domains like example/test are often enough).
For deeper background on the trade-offs, see: Custom Email Domains for Testing: Shared vs Dedicated.
The key design principle: “domain as configuration”
Most migrations go sideways because the domain is hard-coded across too many places.
Before you touch DNS, adopt a small abstraction in your codebase:
- Your test harness, agent tool, or verification service should request an address from an Email Address Factory.
- That factory should take a
domain_strategyordomainparameter. - Everything downstream should depend on the returned “EmailWithInbox” descriptor (address plus inbox identifier), not on string parsing.
This lets you run shared and custom domains side-by-side during the cutover.
Migration plan: shared domain to disposable email custom domain
Phase 0: Baseline your current shared-domain workflow
Goal: get a clean “known good” baseline so you can detect regressions.
Capture these metrics (even if it is just logs and counters):
- Inbox creation success rate
- Time to first matching message (p50, p95)
- Duplicate delivery rate (webhook retries, polling dedupe)
- Failure categories (timeout, mismatch, parsing failure)
If you are still using fixed sleeps or scraping HTML, fix that before migrating domains. A domain cutover should not be the moment you also redesign your harness.
Recommended patterns to standardize first:
- Inbox-per-attempt (or inbox-per-run) isolation
- Webhook-first receipt with polling fallback
- Minimal artifact extraction (OTP or verification URL), not “read the whole email in the agent prompt”
Related reading:
- Temp Email Receive: Webhook-First, Polling Fallback
- Disposable Email With Inbox: The Deterministic Pattern
Phase 1: Pick the domain layout (use a subdomain)
For inbound automation, a dedicated subdomain is usually the safest choice:
mail-qa.example.commail-staging.example.commail-ci.example.com
Benefits:
- You avoid impacting production mail on
example.com. - You can delegate ownership to a team.
- You can isolate environments cleanly.
If you have multiple tenants or customers, consider one subdomain per tenant only if you truly need tenant-level isolation. Otherwise keep it per environment.
Phase 2: Choose a recipient routing strategy
When you control the domain, you must decide how recipient addresses map to disposable inboxes.
Common strategies:
- Encoded local-part (stateless): embed an inbox key in the local-part (good default for automation).
- Alias table (stateful): store a mapping from recipient to inbox (useful when you need fixed addresses).
- Catch-all with correlation constraints: accept any local-part but only treat messages as valid if they match strong correlation.
If you want the full trade-off discussion, see: Routing Emails to Inboxes: Keys, Aliases, and Catch-All.
Phase 3: Provision the custom domain in your inbox provider
This step is provider-specific. In Mailhook, custom domain support is available, and you will configure the domain and then point your MX records accordingly.
Use mailhook.co/llms.txt as the source of truth for the exact API and domain setup details.
What you should validate at this stage:
- Your provider confirms the domain is configured and ready to receive.
- You have the exact MX targets and priorities required.
- You have a plan for rotating secrets used for webhook signature verification (if applicable).
Phase 4: DNS cutover (MX records) with a safe rollout
You are making inbound routing changes, so treat DNS like production infrastructure.
Practical guidance:
- Prefer a brand new subdomain dedicated to automation. Do not modify existing MX for live mail.
- Keep DNS TTLs reasonable. If you need rapid iteration, lower TTL ahead of the change window.
- Verify propagation and correctness using
dig.
References for the underlying SMTP and MX behavior:
Two common mistakes during MX setup:
- Confusing the visible
To:header with the SMTP envelope recipient (routing is based on the envelope). - Assuming “MX exists” implies “your provider is receiving mail.” You still need an end-to-end smoke test.
Phase 5: Implement dual-run (shared domain plus custom domain)
Goal: prove the custom domain works under real load before you switch your entire fleet.
In practice:
- Add a config flag to your Email Address Factory:
domain_mode = shared | custom. - Route a small percentage of runs (or a specific CI job) to the custom domain.
- Keep everything else identical: same inbox lifecycle, same matchers, same dedupe.
Exit criteria that are actually meaningful:
- Arrival latency is within your baseline envelope.
- No increase in “message not found” failures.
- No increase in duplicates beyond what your dedupe already handles.
Phase 6: Cutover and decommission shared domain usage
Once dual-run is stable:
- Switch the default to
domain_mode = custom. - Keep shared mode available as a rollback for a defined window.
- After the window, remove shared-domain assumptions from documentation and examples.
A simple operational table for the rollout:
| Phase | What you change | What you measure | Rollback trigger |
|---|---|---|---|
| 0 | Nothing (baseline) | Latency, timeouts, duplicates | Not applicable |
| 1-2 | Domain design only | None | Not applicable |
| 3-4 | Provider config + MX | Smoke test success | Mail not received end-to-end |
| 5 | Dual-run (small %) | Compare to baseline | Sustained timeouts or mismatch spike |
| 6 | Default cutover | Full-fleet reliability | Any severe regression |
Updating your automation and agent tooling safely
A domain migration is also a good time to confirm your tooling is agent-safe.
If you are using webhooks:
- Verify webhook authenticity using signed payloads (and fail closed).
- Implement replay detection.
- Acknowledge quickly, process asynchronously.
If you have LLM agents in the loop:
- Expose a minimized view of the email (only the artifact you need).
- Constrain link handling (allowlist hosts, block private IP ranges, avoid open redirects).
- Keep the tool surface small (create inbox, wait for message, extract artifact, expire inbox).
Related reading:
- Email Signed By: Verify Webhook Payload Authenticity
- Security Emails: How to Parse Safely in LLM Pipelines
Common migration gotchas (and how to avoid them)
Allowlisting is an organizational problem, not a DNS problem
A custom domain helps because it is yours, but you still need to:
- Decide which subdomains are “test only.”
- Document them for partner allowlists.
- Keep ownership and change control clear.
Make inbox lifecycle explicit
Domain cutovers often surface latent lifecycle issues:
- Inboxes living too long
- Late arrivals after a test “finished”
- Reused inboxes causing stale selection
If you need a lifecycle model, see: Manage Inbox Lifecycle: TTLs, Cleanup, and Drain Windows.
Your matchers must be narrow
A custom domain does not automatically prevent flakiness if you still “search the latest email in a big mailbox.” Keep using:
- Inbox-per-attempt
- Strong correlation tokens
- Deterministic selection and dedupe
FAQ
Do I need a custom domain to use disposable inboxes? No. Shared domains are a great starting point for disposable inbox workflows, especially when you want zero DNS setup.
What is the safest domain layout for a disposable email custom domain? Usually a dedicated subdomain per environment (for example, mail-ci.example.com). It reduces blast radius and keeps governance clean.
How do I migrate without breaking CI tests? Use domain-as-configuration and run a dual-run period where a small percentage of jobs use the custom domain while you compare reliability and latency to your baseline.
Will a custom domain automatically fix email deliverability? It improves control and isolation, but deliverability still depends on the sender, the recipient environment, allowlists, and the specifics of the mail path.
Where are the exact Mailhook API and domain setup details documented? In the canonical reference: mailhook.co/llms.txt.
Try Mailhook for custom-domain disposable inboxes
If you want a disposable inbox API that works on shared domains today and can migrate to a custom domain when you need governance and allowlisting, Mailhook provides:
- Disposable inbox creation via API
- Email delivered as structured JSON
- Webhook notifications (with signed payloads) plus polling as a fallback
- Custom domain support
Start with the docs in llms.txt, or head to Mailhook (no credit card required) to set up your first inbox and plan your cutover.
