Forwarding and aliases

An alias is an address at your domain that forwards to one or more mailboxes. This page shows how to set aliases and what mxgate does with each message.

Aliases and the catch-all

An alias has a name, for example hello for hello@example.com. The name can have letters, digits and the characters . _ + -, and at most 64 characters. The alias * is the catch-all: it takes mail for each address at the domain that has no alias of its own. The catch-all does not count against the alias limit of the free plan.

An alias can have more than one destination. Each confirmed destination gets a copy of the message. The free plan permits 3 destinations for each alias, and the paid plan 10.

Set, list and remove

npx mxgate alias set hello@example.com you@gmail.com
npx mxgate alias set '*@example.com' you@gmail.com you@example.org
npx mxgate alias list example.com
npx mxgate alias rm hello@example.com

alias set makes the alias, or replaces the destinations of an alias that exists. alias list shows each alias with its state:

hello@example.com  ->  you@gmail.com  active
*@example.com  ->  you@gmail.com, you@example.org (unconfirmed)  active

The same with the API:

curl -X PUT https://api.mxgate.io/v1/domains/example.com/aliases/hello \
  -H "Authorization: Bearer $MXGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":["you@gmail.com","you@example.org"]}'

curl https://api.mxgate.io/v1/domains/example.com/aliases \
  -H "Authorization: Bearer $MXGATE_API_KEY"

curl -X DELETE https://api.mxgate.io/v1/domains/example.com/aliases/hello \
  -H "Authorization: Bearer $MXGATE_API_KEY"

PUT answers 201 for a new alias and 200 for a replaced alias. The answer has the alias, created, and confirmation_mailed_to: the destinations that got a confirmation link from this call. After you remove an alias, mail to it is refused, unless the domain has a catch-all.

Destinations must confirm

A destination is a mailbox that your account can forward to. mxgate mails each new destination a link. The owner of the mailbox opens the link and presses "Confirm forwarding". No mail goes to a destination before that.

The reason: without this step, an alias could send mail to the mailbox of a person who did not ask for it. The link shows a page and confirms nothing by itself, because mail scanners open each link in a message.

npx mxgate dest add you@example.org       # mail a confirmation link
npx mxgate dest list                      # each destination, confirmed or not

The API calls are POST /v1/destinations with {"email":"you@example.org"} and GET /v1/destinations. alias set does this step for a new destination. mxgate mails one destination at most one link in 10 minutes, and one account causes at most 10 confirmation mails a day.

When an alias is inactive

Each alias has active and inactive_reasons. An alias is inactive when one of these is true:

• The domain is not verified yet.
• No destination of the alias is confirmed yet.
• The alias is disabled.
• The account is suspended.

An alias with one confirmed destination and one that is not confirmed is active. Mail goes only to the confirmed destination.

Forwarding loops

mxgate refuses a destination on the domain of the alias, and a destination on another domain that mxgate forwards. The error is 422 forwarding_loop. Forward to a real mailbox.

What happens to a message

• mxgate does not change the From header, and the message keeps the DKIM signature of the sender.
• mxgate rewrites the envelope sender (SRS), so SPF passes at the destination.
• mxgate adds an ARC seal, so the destination can trust the SPF and DKIM results that mxgate saw when the message arrived.

These three things help Gmail and other providers to accept forwarded mail.

Mail that mxgate refuses

A spam filter (rspamd) gives each message a score. mxgate refuses clear spam at SMTP time, while the sending server is still connected. The sending server gets an error, and nothing is forwarded. Mail to an address with no alias, no catch-all, or no confirmed destination is refused the same way. Each refusal is a rejected row in the message log.

Mail that the destination refuses

If the destination server refuses a forwarded message, the log row is bounced. The sender gets no bounce message. A bounce message would show the address behind the alias. You get the notification: see Notifications and webhooks.

For the same reason, mxgate drops a bounce or an automatic reply that a destination sends later.

Retries and size

If the destination server does not accept a message now, the row is deferred and mxgate tries again. mxgate tries a delivery for 2 days. After that the row is expired. One message is at most 25 MB.