Managed domains and DNS

Most email providers hand you a list of DNS records and hope you type them
correctly. relay ships its own authoritative nameserver. You prove ownership
of your domain once, and the nameserver serves the rest: MX, SPF, DKIM, DMARC
reporting addresses, MTA-STS, TLS-RPT, and the Return-Path zone. This page
explains the domain model, what relay serves in what name, and how
verification works.

The domain model

In the examples, acme.com is your domain and relays.to is the relay
platform domain.

Facts to understand about this model:

• The sender subdomain exists once per root domain. The envelope
  addresses, the DKIM zone, and the report collectors live under
  {prefix}.{root}. You delegate exactly that subdomain to the relay
  nameservers, and you add one DMARC record at your root.
• Every root domain gets its own signing keys: RSA-2048 and Ed25519
  keys, one selector each, at relay-rsa2048 and relay-ed25519 under
  _domainkey. Your domain signs with its own keys, so
  reputation attaches to your domain and not to someone else’s.
• Managed domains cannot be deleted in the dashboard, and custom domains can.
• There can be no overlap: you cannot register a subdomain of the managed
  domain, and no two organizations can claim overlapping names.

From signup to first send

flowchart TD
    A[Sign up with GitHub] --> B[Organization created]
    B --> C[Managed sender domain created and verified]
    C --> D[DKIM keys generated for the domain]
    D --> E[Create SMTP credential]
    E --> F[Send immediately]

Nothing in this path touches DNS configuration. The nameserver serves the
zone, the platform signs, and you send.

The platform signature comes from a platform domain row registered for the
operator’s organization. Relay matches that platform domain by its name.
Once the platform domain exists, the nameserver serves its DKIM selectors
through the ordinary record path, and relay cosigns customer mail. Until
then, relay signs with the sending domain only.

Adding your own domain

The flow for a user domain, for example acme.com:

flowchart TD
    A[Add domain in dashboard] --> B[Store DKIM keys at creation]
    B --> C[Dashboard shows the records to publish]
    C --> D[You publish NS records for the sender subdomain and one DMARC record]
    D --> E[Run verification]
    E --> F{Checks ok?}
    F -- No --> G[Fix shown record, check again]
    G --> E
    F -- Yes --> H[Verified for sending, receiving, or both]
    H --> I[Nameserver serves the DNS now]

Verification reads the live DNS for seven records and splits the result
into two independent purposes:

• Sending: NS delegation on the sender subdomain, SPF authorization, the
  two DKIM CNAMEs, and the DMARC record at the root.
• Receiving: the MX record at the root, the MTA-STS record and CNAME, and
  the TLS-RPT record with the relay reporting address.

Each purpose verifies on its own. Publish only the sending records and the
domain shows sending verified while receiving reads as not set up. Checks
run per record, and the dashboard shows each of them, so a wrong record is
identifiable. Re-check at any time.

What the nameserver serves

For a delegated domain the authoritative nameserver answers:

The dashboard always shows the current record set with concrete names and
the check state per record, so you never hand-edit names here.

The MTA-STS CNAME points at mta-sts.mail.relay.acme.com. That name sits
in the sender subdomain mail.relay.acme.com, which the relay nameserver
already serves. relay serves the policy over HTTPS and issues the
certificate for mta-sts.acme.com on the first fetch. You add no record
and no certificate for that name.

Receiving-domain notes

A domain can send and receive independently of each other. app.acme.com as
a receiving domain needs only its MX record to point at your sender
subdomain. Verification reflects this split: a setup without receiving
records reads as not set up, not as a failure. The webhook health check
shows the observed MX. Read the
receiving page for
the acceptance flow.

Troubleshooting

Related pages

• Encryption. The
  MTA-STS policy served for your domains.
• Webhooks. Receiving
  setup from the application side.