Skip to content
extraorbital
Documentation ExtraOrbital
Browse documentation

Start here

Email for your domains

Mail to your custom domain forwarded to you, a sending domain for your app, and replies that arrive, set up on their own.

Email comes with a custom domain: one you bought here or attached (Domains and DNS). The project's own address, <project>.extraorbital-apps.com, never gets email. Every command below acts on the project linked in the folder (.extraorbital.json).

What a domain gets

For maisonlune.fr:

PartWhatHow
Receiving*@maisonlune.fr forwards to the person who attached or bought the domain; aliases forward elsewhereImprovMX
SendingThe app sends from @e.maisonlune.frAmazon SES, through the project's ses/prod resource
Replieshello@e.maisonlune.fr forwards wherever hello@maisonlune.fr doesImprovMX

Sending uses its own subdomain, e.<domain>, so a bounce or a complaint never weighs on the main domain's reputation. Its records are DKIM (three CNAMEs), a custom MAIL FROM (bounce.e.<domain>, an MX and an SPF) and a DMARC policy (p=none).

It starts on its own:

  • for a domain bought here, right after its purchase;
  • for a domain held elsewhere, once it is live (until then nothing proves it is yours).

A subdomain attached with a CNAME (app.maisonlune.fr, www.example.com) has no email of its own: a CNAME cannot share its name with the MX records mail needs. Its apex can.

See where it stands

Terminal
npx extraorbital emails                       # every custom domain of the project
npx extraorbital emails status maisonlune.fr  # one, checked again now

Each domain shows its catch-all and aliases, whether its MX records are seen, whether SES has verified e.<domain> (it takes a few minutes after the records are in place), and, for a domain held elsewhere, the records still to set.

Forwards

Terminal
npx extraorbital emails forward hello@maisonlune.fr ada@example.org
npx extraorbital emails forward hello@maisonlune.fr ada@example.org,bob@example.org
npx extraorbital emails forward '*@maisonlune.fr' team@example.org   # the catch-all
npx extraorbital emails rm hello@maisonlune.fr
npx extraorbital emails rm '*@maisonlune.fr'                         # catch-all off

An alias takes precedence over the catch-all. With the catch-all off, mail to an address without its own forward is refused. Every forward is copied to e.<domain>, so replies follow it.

Sending from the app

The ses/prod resource is provisioned for the project when sending is set up, and its variables are set on production:

js
await fetch(`${process.env.SES_API_URL}/api/v1/send`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SES_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    from: `Maison Lune <hello@${process.env.SES_FROM_DOMAIN}>`,
    to: "ada@example.org",
    replyTo: "hello@maisonlune.fr",
    subject: "Your order",
    text: "Thank you!",
  }),
});

Sending waits until SES has verified e.<domain>. Limits and pricing are the SES resource's.

A domain held elsewhere

Its DNS is at its own provider, so the records come back for you to set there:

NameTypeValue
@MXmx1.improvmx.com (10), mx2.improvmx.com (20)
@TXTv=spf1 include:spf.improvmx.com ~all
eMXmx1.improvmx.com (10), mx2.improvmx.com (20)
eTXTv=spf1 include:spf.improvmx.com ~all
<token>._domainkey.e (three)CNAME<token>.dkim.amazonses.com
bounce.eMXfeedback-smtp.<region>.amazonses.com (10)
bounce.eTXTv=spf1 include:amazonses.com ~all
_dmarc.eTXTv=DMARC1; p=none;

A name has one SPF record: if @ already has one, add include:spf.improvmx.com to it rather than adding a second. The records are checked every minute.

For a domain bought here they are written for you, an existing SPF merged rather than doubled. dns ls shows them as locked: emails disable takes them away. A domain bought here that already receives mail elsewhere (its own MX records) is not taken over: its forwarding waits until those records are removed.

Turn it off

Terminal
npx extraorbital emails disable maisonlune.fr   # asks once; --yes without a terminal
npx extraorbital emails enable maisonlune.fr    # on again, its forwards as they were

disable removes the forwarding, the records written here (an SPF keeps your own includes) and the sending domain. enable also runs a setup again now, a step that gave up included. Detaching a domain bought here keeps its email (domains detach asks whether to turn it off too); detaching a domain held elsewhere turns it off.

MCP

list_emails, enable_emails, set_email_forward, remove_email_forward and disable_emails, on both MCP URLs. None of them charges anything.