# 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.

<Callout title="In brief">

- A custom domain gets email on its own once it is live: `*@<domain>` forwards to the person who attached or bought it.
- Your app sends from `@e.<domain>`, through the project's `ses` resource: production has `SES_API_URL`, `SES_API_KEY` and `SES_FROM_DOMAIN`.
- Replies to `@e.<domain>` are forwarded like mail to `@<domain>`.
- `npx extraorbital emails` shows it all; `emails forward hello@<domain> <to>` adds a forward.

</Callout>

Email comes with a **custom domain**: one you bought here or attached ([Domains and DNS](/docs/domains)). 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`:

| Part | What | How |
| --- | --- | --- |
| Receiving | `*@maisonlune.fr` forwards to the person who attached or bought the domain; aliases forward elsewhere | ImprovMX |
| Sending | The app sends from `@e.maisonlune.fr` | Amazon SES, through the project's `ses/prod` resource |
| Replies | `hello@e.maisonlune.fr` forwards wherever `hello@maisonlune.fr` does | ImprovMX |

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

```bash
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

```bash
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](/docs/resources/ses).

## A domain held elsewhere

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

| Name | Type | Value |
| --- | --- | --- |
| `@` | MX | `mx1.improvmx.com` (10), `mx2.improvmx.com` (20) |
| `@` | TXT | `v=spf1 include:spf.improvmx.com ~all` |
| `e` | MX | `mx1.improvmx.com` (10), `mx2.improvmx.com` (20) |
| `e` | TXT | `v=spf1 include:spf.improvmx.com ~all` |
| `<token>._domainkey.e` (three) | CNAME | `<token>.dkim.amazonses.com` |
| `bounce.e` | MX | `feedback-smtp.<region>.amazonses.com` (10) |
| `bounce.e` | TXT | `v=spf1 include:amazonses.com ~all` |
| `_dmarc.e` | TXT | `v=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

```bash
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.

---

More for agents: [Sitemap](https://extraorbital.dev/sitemap.md) · [llms.txt](https://extraorbital.dev/llms.txt) · [agents.md](https://extraorbital.dev/agents.md)
