Documentation / Guides

Email forwarding and MX

Forwarding is not part of the zone. It has its own place in Namecheap's API, never shows up in dns list, and is only delivered while the domain's mail routing mode is FWD — which any MX record switches away from. That interaction is the most expensive mistake this tool exists to prevent, because both halves of it fail silently.

The two traps

Adding MX stops forwarding

A domain forwarding hello@example.com to your inbox is on FWD routing. Point it at Google Workspace, and adding those MX records switches routing to MX. The forwarded mailboxes are still stored, still listed in Namecheap's own interface, and no longer delivered anywhere.

dns add and dns set warn before they do this, rather than reporting a successful write over mail that has quietly stopped.

Forwarding on an MX domain goes nowhere

The reverse is just as quiet. Set up forwarding on a domain already on MX routing and the mailboxes are accepted and stored, and nothing ever arrives. dns email list and dns email set say which mode the domain is in instead of reporting success.

Managing forwarding

# what the domain forwards
namecheap dns email list example.com

# forward a mailbox (add is an alias for set)
namecheap dns email set example.com hello you@gmail.com

# catch everything not matched by another mailbox
namecheap dns email set example.com @ you@gmail.com

# stop forwarding a mailbox
namecheap dns email rm example.com hello

Choosing a mode

You cannot have both. Anything that suggests otherwise is the API storing records it will not act on.

Presets handle the switch

Applying an email preset switches the domain's routing mode to MX and removes any MX records from a previous mail provider, along with a stale v=spf1 TXT record on the same host — leaving either in place would break delivery. Unrelated records are untouched unless you pass --replace.

namecheap preset apply google-workspace example.com
namecheap preset apply fastmail example.com
namecheap preset apply protonmail example.com

Forwarding round-trips

dns export --format json carries forwarding under an email_forwarding key, and dns sync and dns diff read it back, so a captured file describes both the records and the mailboxes.

# capture a domain's records and its forwarding
namecheap dns export example.com > example.com.json

# put both back
namecheap dns sync example.com example.com.json

# assert in CI that neither has drifted (exit 8 if either has)
namecheap dns diff example.com example.com.json --check

A zone file cannot express forwarding at all, so --format zone notes that it exists rather than pretending it round-trips. If a domain forwards mail, capture it as JSON.

Rolling back

Snapshots record the routing mode alongside the records, so a rollback restores both — records alone would leave MX published against FWD routing, or the reverse. Snapshots taken before an email-forwarding change also record the mailboxes; those taken before an ordinary DNS write do not, because that write could not have changed them.