Skip to main content

Receiving domains and DNS

Use a dedicated receiving subdomain such as intake.example.com. Changing the MX records of your normal mail domain changes where incoming mail is delivered.

Configure a custom domain​

  1. Create an active webhook endpoint.
  2. In Receiving domains, add your domain and select the endpoint.
  3. Publish the exact verification TXT value displayed by Wildmail.
  4. Publish the MX destination displayed by Wildmail.
  5. Select Check DNS and wait for the domain to show Ready.

Example records for intake.example.com:

TypeNameValue
TXT_wildmail.intake.example.comwildmail-verification=<your token>
MXintake.example.comPriority 10, destination <the displayed MX host>

Your DNS provider may expect a relative name such as _wildmail.intake rather than a fully qualified name. Avoid adding the zone name twice. Keep other TXT records intact.

Check the public answer using your system resolver:

dig TXT _wildmail.intake.example.com
dig MX intake.example.com

Ownership verification, MX health, billing availability, and an active endpoint all affect readiness. A domain without a usable route is rejected during SMTP recipient admission. Re-run the DNS check after propagation. A TXT success alone does not establish readiness.

The domain's Ready indicator describes its catch-all endpoint. A domain configured only with exact-address routes can still accept mail for those addresses when DNS, billing, the plan, and each route's endpoint allow it, even without a Ready catch-all.

Wildmail automatically rechecks custom-domain TXT ownership and MX records every hour. If a check confirms that the ownership TXT is missing or incorrect, the domain returns to Pending. Missing or incorrect MX records mark MX setup as needed. Either condition stops new mail from being accepted for that domain. Once DNS is corrected, a later scheduled check can restore readiness. Temporary DNS lookup failures leave the last confirmed status in place.

Routing behavior​

Verified custom domains can use exact-address routes alongside the domain catch-all. An exact match such as orders+acme@intake.example.com goes to its configured endpoint first. Wildmail trims, Unicode-normalizes, and lowercases the configured UTF-8 local part before matching, so uppercase and lowercase forms use the same route. Unicode domain names are normalized with IDNA to lowercase ASCII before lookup. Plus-tags remain literal and are not stripped, so orders+acme@intake.example.com is distinct from orders@intake.example.com. Patterns and named parameters are not supported.

When no exact route matches, Wildmail uses the domain's selected catch-all endpoint, if one is configured. A matching exact route can accept mail without a catch-all endpoint. Unmatched addresses are rejected when no catch-all is configured. A matching route that is suspended by the plan or has an unavailable endpoint is rejected during SMTP admission. It does not fall back to catch-all. Deleting the exact route restores catch-all behavior for future mail to that address, if configured.

Free includes domain catch-all routing. Starter and Growth also include unlimited exact-address routes. The allowance is shared across the individual account's customer-owned domains. Suspended routes stay stored and count toward usage. Upgrading restores them. The hosted test address remains separate and keeps its own endpoint assignment.

Wildmail pins the matched route and endpoint destination when it accepts a message, so later configuration edits do not redirect that message. Pausing an endpoint stops pending sends. Replay uses the delivery's pinned endpoint revision. Manage custom-domain routes with the domain routes API.

Hosted address​

Each account also has an assigned hosted test address. It needs an active endpoint and no customer DNS records. The hosted address does not consume a custom-domain slot. Only the receiving address assigned to your account accepts mail.

Limits​

Pending and suspended custom domains count toward your domain allowance. Deleting a custom domain releases its slot. The API returns 409 with code: domain_limit_reached when creation would exceed the allowance. See usage and retention.

SMTP intake also applies limits to source-IP connections, source-IP message attempts, and messages for each receiving domain. Multiple recipients at one domain in the same SMTP transaction count once toward that domain's rate limit. Assigned hosted addresses use account-specific message limits, so unrelated customers do not share one hosted-domain allowance. Exceeding a rate limit temporarily refuses the SMTP command. The sending server should retry later. Rate limits are separate from monthly message and storage allowances.