Quickstart: mxgate

From no account to forwarded mail in about two minutes: sign up, run one setup command, check the log. Then the same flow as four API calls.

This page takes you from no account to forwarded mail in about two minutes. You need a domain that you own, a mailbox that you read, and Node.js 20 or later.

npx mxgate signup you@gmail.com

The command makes the account and saves the API key in ~/.config/mxgate/config.json. The key is also mailed to you. The free plan needs no card.

Confirm your mailbox

The mail with the key has a link. Open the link and press "Confirm forwarding". Your address is then a forwarding destination. mxgate forwards no mail to an address before its owner confirms it.

Set up the domain

CLOUDFLARE_API_TOKEN=... npx mxgate setup example.com --to you@gmail.com

The command does these steps:

It adds the domain to your account.
It finds the DNS host from the NS records: Cloudflare, Vercel or Porkbun.
It writes the records there: the ownership TXT, the MX, the DKIM key, and a DMARC record if the domain has none.
It waits until mxgate sees the records. The wait is at most 120 seconds.
It sets the catch-all, so mail to each address at example.com goes to the mailbox after --to.

The DNS token stays on your machine. If the domain has a mail server already, the command stops and changes nothing. If --to is not your account address, that mailbox gets its own confirmation link. For another DNS host, or to add the records by hand, see DNS setup.

Check that it works

Send a mail from a different account to an address at your domain, for example hello@example.com. Then read the log:

$ npx mxgate logs example.com
2026-11-14 09:14:02  in   forwarded  client@example.org -> hello@example.com -> you@gmail.com

If there is no row, look at the DNS check and at the alias:

npx mxgate domain verify example.com      # what the DNS check found
npx mxgate alias list example.com         # each alias, and why it is not active

The same flow with the API

The base address is https://api.mxgate.io. The sample answers below are shortened. The API reference has each endpoint in full.

curl -X POST https://api.mxgate.io/v1/signup \
  -H "Content-Type: application/json" -d '{"email":"you@gmail.com"}'

{
  "api_key": "mxg_...",
  "account": { "email": "you@gmail.com", "plan": "free", "status": "active" },
  "mailed": true,
  "next_steps": ["Open the confirmation link mailed to you@gmail.com and press \"Confirm forwarding\".", "..."]
}

The key is shown once. Store it, then confirm the link in the mail.

2. Add the domain

curl -X POST https://api.mxgate.io/v1/domains \
  -H "Authorization: Bearer $MXGATE_API_KEY" \
  -H "Content-Type: application/json" -d '{"name":"example.com"}'

{
  "domain": {
    "name": "example.com",
    "status": "pending",
    "records": [
      { "type": "TXT", "name": "_mxgate.example.com", "value": "mxgate-verify=...", "required": true },
      { "type": "MX", "name": "example.com", "value": "mx1.mxgate.io", "priority": 10, "required": true },
      { "type": "TXT", "name": "_dmarc.example.com", "value": "v=DMARC1; p=none", "required": false },
      { "type": "TXT", "name": "mxgate._domainkey.example.com", "value": "v=DKIM1; k=rsa; p=...", "required": false }
    ]
  },
  "created": true,
  "next_step": "Add the required records, then POST /v1/domains/example.com/verify."
}

Publish the records at your DNS host.

3. Verify

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

{
  "verified": true,
  "domain": {
    "name": "example.com",
    "status": "verified",
    "checks": { "ownership": "ok", "mx": "ok", "dkim": "ok", "mx_found": ["10 mx1.mxgate.io"], "problems": [] }
  },
  "message": "example.com is verified and its MX points to mxgate. Mail to its aliases is forwarded now."
}

DNS changes can take some minutes. Call again until verified is true and mx is ok.

4. Set an alias

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

{
  "alias": {
    "alias": "*",
    "address": "*@example.com",
    "domain": "example.com",
    "to": [{ "email": "you@gmail.com", "confirmed": true }],
    "active": true,
    "inactive_reasons": []
  },
  "created": true,
  "confirmation_mailed_to": []
}

The alias * is the catch-all. Use a name such as hello for one address.

In the browser

The same steps work in the dashboard. Create an account, or sign in with a six-digit code that mxgate mails to you. Add the domain, copy the DNS records to your DNS host, press "Check DNS now", and make the alias. The dashboard does not write the records for you: only mxgate setup does that, because the DNS token stays on your machine.

DNS setup: the four records, mxgate setup, and the check result.
Forwarding and aliases: aliases, the catch-all, destinations, and what happens to a message.
Send as your domain: SMTP logins and the send API.
The message log: why a message did or did not arrive.
Notifications and webhooks: the email digest and the signed webhook.
MCP server and agents: give mxgate to an AI agent.
Keys and sign-in: the API key, recovery, rotation, web sign-in.
Plans and limits: the free and paid plans, rate limits, billing.
Errors: each error code and what to do.

Quickstart