Email Forwarding API

Overview

A forward is a rule on one of your connected domains: mail sent to hello@company.com is delivered to a destination inbox you choose, like a personal Gmail. Forwards work on any domain whose DNS is on Reinterface (see the DNS API for connecting one) and can be managed from the dashboard or this API interchangeably.

Base URL: https://api.reinterface.com/api/v1. All responses are JSON. Last updated: 2026-08-08.

Authentication

Identical to every other Reinterface API: send your personal API key in the x-api-key header. Find it under Dashboard → Settings → API key. Forwards are scoped to your account; you can only manage forwards on domains you connected.

-H "x-api-key: <YOUR_API_KEY>"

The MX requirement

Forwarding servers can only receive your domain’s mail if the domain’s apex MX records point at them. You can create forwards at any time, but they start delivering only once the MX set is right (and, for newly connected domains, once delegation is active).

Every list response includes an mx object so you can check readiness programmatically: ready is true when every required forwarding server is in the apex MX set and no other MX competes with them. If it is false, either create the MX records yourself through the DNS API or call the one-shot fix endpoint below.

List forwards

Required query param: domain. host is @ when the forward is on the root domain, or the subdomain label otherwise. box is the address local part, or * for a catch-all.

curl "https://api.reinterface.com/api/v1/dns/mail-forwards?domain=company.com" \
  -H "x-api-key: <YOUR_API_KEY>"

{
  "domain": "company.com",
  "forwards": [
    { "id": "1488357", "host": "@", "box": "hello", "destination": "founder@gmail.com" },
    { "id": "1488402", "host": "@", "box": "*", "destination": "inbox@gmail.com" }
  ],
  "mx": {
    "ready": true,
    "required": [
      "mailforward71.cloudns.net",
      "mailforward72.cloudns.net",
      "mailforward73.cloudns.net",
      "mailforward74.cloudns.net"
    ],
    "current": [
      "mailforward71.cloudns.net",
      "mailforward72.cloudns.net",
      "mailforward73.cloudns.net",
      "mailforward74.cloudns.net"
    ]
  }
}

Create a forward

Required: domain, box (the local part before the @, e.g. hello, or * for catch-all) and destination (any valid email address outside the domain itself). Optional: host, a subdomain to forward on, e.g. mail makes the address hello@mail.company.com; leave it empty (or omit it) for the root domain.

curl -X POST https://api.reinterface.com/api/v1/dns/mail-forwards \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "domain": "company.com",
    "box": "hello",
    "host": "",
    "destination": "founder@gmail.com"
  }'

{
  "id": "1488357",
  "host": "@",
  "box": "hello",
  "destination": "founder@gmail.com"
}

Catch-all forwards

Pass "box": "*" to forward every address on the domain that has no explicit forward of its own. Explicit forwards win over the catch-all, so hello@ can go to one inbox while *@ sweeps everything else into another.

curl -X POST https://api.reinterface.com/api/v1/dns/mail-forwards \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "domain": "company.com",
    "box": "*",
    "host": "",
    "destination": "inbox@gmail.com"
  }'

Point MX at forwarding servers

One-shot repair for a domain whose mx.ready is false. It deletes the current apex MX records (a lower-priority stranger would still win the mail otherwise) and adds one MX per forwarding server at priorities 10, 20, and so on. The change is live on our nameservers within minutes; the rest of the internet catches up as old MX TTLs expire.

curl -X POST https://api.reinterface.com/api/v1/dns/mail-forwards/mx \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "content-type: application/json" \
  -d '{ "domain": "company.com" }'

{
  "domain": "company.com",
  "replaced": true,
  "mx": {
    "ready": true,
    "required": [
      "mailforward71.cloudns.net",
      "mailforward72.cloudns.net",
      "mailforward73.cloudns.net",
      "mailforward74.cloudns.net"
    ],
    "current": [
      "mailforward71.cloudns.net",
      "mailforward72.cloudns.net",
      "mailforward73.cloudns.net",
      "mailforward74.cloudns.net"
    ]
  }
}

Delete a forward

Required query param: domain. The id comes from the list or create response. Mail sent to the address afterwards bounces (unless a catch-all still covers it).

curl -X DELETE "https://api.reinterface.com/api/v1/dns/mail-forwards/1488357?domain=company.com" \
  -H "x-api-key: <YOUR_API_KEY>"

{
  "success": true,
  "id": "1488357",
  "status": "deleted"
}

Errors

Errors return { "success": false, "error": { "code", "message" } }.

Endpoint summary