# 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`:

| Type | Name                          | Value                                                |
| ---- | ----------------------------- | ---------------------------------------------------- |
| TXT  | `_wildmail.intake.example.com` | `wildmail-verification=<your token>`                  |
| MX   | `intake.example.com`          | Priority `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:

```bash
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.

```mermaid
flowchart TD
    A[TXT proves ownership] --> E{All readiness checks pass?}
    B[MX points to Wildmail] --> E
    C[Active catch-all endpoint] --> E
    D[Billing available] --> E
    E -->|Yes| R[Ready to receive]
    E -->|No| F[Fix DNS or account setup]
    F --> V[Check DNS again]
    V --> E
```

## 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.

```mermaid
flowchart LR
    I["orders+acme@intake.example.com"] --> X{Exact route exists?}
    X -->|Yes| A{Route and endpoint active?}
    A -->|Yes| RE[Exact route endpoint]
    A -->|No| S[Not accepted]
    X -->|No| C{Catch-all configured?}
    C -->|Yes| CA{Catch-all endpoint active?}
    CA -->|Yes| E[Catch-all endpoint]
    CA -->|No| N[Not accepted]
    C -->|No| N[Not accepted]
    H[Assigned hosted address] --> HE[Its selected endpoint]
    U[Other hosted-domain address] --> HU[Not accepted]
```

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](https://docs.wildmail.app/docs/guides/delivery-and-replay.md) uses the delivery's pinned endpoint revision. Manage custom-domain routes with the [domain routes API](https://docs.wildmail.app/docs/api/reference.md).

## 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](https://docs.wildmail.app/docs/guides/usage-and-retention.md).

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.
