> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oximail.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Mail & SMTP

> The operator view of the mail path: listeners and ports, the [smtp] configuration (DKIM keys, transport maps), the outbound queue and its CLI, sending domains, and the backup MX.

This page is the operator companion to [the SMTP architecture page](../architecture/oximail-smtp): the ports to open, the `[smtp]` configuration, the queue you manage, and the workflows around sending domains. The [first-boot wizard](../first-boot) writes a working baseline for all of it.

## Listeners and ports

| Port | Listener                                                                                              | Config key               |
| ---- | ----------------------------------------------------------------------------------------------------- | ------------------------ |
| 25   | Inbound MX — receives mail from the world. Also the backup-MX listener when `[mode] role = "backup"`. | `[smtp] bind`            |
| 587  | Submission (STARTTLS) — authenticated users sending mail.                                             | `[smtp] submission_bind` |
| 465  | Submission over implicit TLS.                                                                         | `[smtp] smtps_bind`      |

Inbound (25) and submission (587/465) are **separate code paths** with different rules — untrusted mail is authenticated and scored, user mail is identity-validated and queued. Never proxy these ports; they bind directly even behind a reverse proxy.

```toml theme={null}
[smtp]
bind = "0.0.0.0:25"
submission_bind = "0.0.0.0:587"
smtps_bind = "0.0.0.0:465"
hostname = "mail.example.com"     # used in Received:, EHLO, SRS
dane_enabled = true               # outbound DANE (requires [dns] provider)
```

## Sending domains and DKIM keys

Each domain the server sends for has its own signing key, declared as an array entry:

```toml theme={null}
[[smtp.dkim_keys]]
domain = "example.com"
selector = "default"
key_path = "/etc/oximail/dkim/example.com.default.key"
```

Adding a sending domain is a three-step ritual: generate the key (`oximail setup dkim --domain <d>`), add the block above, and **publish the DNS record** — a key without its published TXT record signs mail that receivers reject. `oximail check-dns --domain <d>` confirms the full record set; the [email authentication page](./email-auth-security) explains each record.

Submission validates both the envelope `MAIL FROM` and the body `From:` against the authenticated account's identities — users cannot send as addresses they do not own, and additional sendable addresses are managed as aliases (`oximail alias`, ADR-089).

## Routing outbound: transport maps

By default, outbound mail resolves the destination's MX and delivers directly. `[[smtp.transport_maps]]` overrides routing per destination pattern — the mechanism behind [relay/smarthost sending](./outbound-relay):

```toml theme={null}
[[smtp.transport_maps]]
pattern = "*"                              # catch-all; or a specific domain
relay_host = "smtp.relay.example"
relay_port = 587
auth_user = "account"
auth_password_file = "/etc/oximail/relay.password"   # 0600 sidecar, never inline
```

An authenticated route is TLS-mandatory by construction. Delivery through a route still runs the same [extension mediation](../architecture/oximail-smtp) as direct delivery.

## The outbound queue

Every submission lands in the persistent delivery queue; a worker retries with exponential backoff (1 min → 24 h) until the **5-day** give-up window expires, then bounces with an RFC 3464 DSN. Manage it with:

```bash theme={null}
oximail queue ...                      # list / inspect / cancel entries
curl .../admin/v1/queue                # same over the admin API
curl .../admin/v1/queue/{id}/retry     # force an immediate retry
```

A queue that grows without draining almost always means a DNS, reverse-DNS, or reputation problem on your side — start with `oximail check-dns` and the remote server's reply recorded on the queue entry. Note that an account [erasure](./compliance) deliberately refuses to run while that account still has undelivered queue entries; cancelling them via the queue surface unblocks it.

## Rate limits

`[rate_limit] smtp_outbound_per_hour` caps per-account outbound volume, and the `[rate_limit.destination_domains]` table shapes per-destination behaviour to stay polite with large receivers. Both are runtime-overridable ([configuration](./configuration)).

## Backup MX

A second box with `[mode] role = "backup"` accepts mail for your domains when the primary is down, in one of two modes (queue or synchronous proxy — see [the SMTP layer](../architecture/oximail-smtp)). The wizard has a dedicated Backup MX flow; publish it as MX priority 20. A backup MX **must** know the valid recipients or stay in proxy mode — a backup that accepts everything is a backscatter source.

## Where the rest lives

* Verdicts and folder placement of inbound mail — [anti-spam](./anti-spam).
* The DNS contract (SPF, DKIM, DMARC, MTA-STS, DANE) — [email authentication](./email-auth-security).
* Archiving copies of mail flows — [compliance journaling](./compliance).
* User-level filtering at delivery — [Rules & Sieve](./sieve-rules).