Docs: Stalwart validation off only for the test domain (rcpt_domain expressions)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Jonas Leder 2026-11-16 16:12:00 +01:00
commit 44c5f633b1

View file

@ -33,34 +33,83 @@ swaks --to random-1234@mail-test.example.org --server mail.example.org
```
Then look for the message in the catch-all mailbox. A `550` means step 4 or the domain in step 2 is missing.
## 2. Disable all validation
## 2. Disable validation for the test domain only
Mail Tester does the SPF, DKIM, DMARC, rDNS and blacklist checks itself, so Stalwart must accept every mail
and must not reject, tag or move it.
Mail Tester does the DKIM, DMARC, SPF, rDNS and blacklist checks itself, so for the test domain Stalwart must
not reject, tag or move mail. Other domains on the server keep their normal protection.
**Settings › MTA › Inbound › Sender Authentication** (`SenderAuth`): each field is an expression, set it to
always return `disable`, e.g. `{ "else": "disable" }`:
Stalwart evaluates most of these settings as expressions, and the recipient domain is only known at the RCPT TO
stage, so which settings can be limited to one domain depends on the stage they run at:
| Field | Value |
|---|---|
| `spfEhloVerify` | `disable` |
| `spfFromVerify` | `disable` |
| `dkimVerify` | `disable` |
| `dmarcVerify` | `disable` |
| `reverseIpVerify` (rDNS) | `disable` |
| `arcVerify` | `disable` (default) |
| Setting (object) | Stage | Per domain? |
|---|---|---|
| `dkimVerify`, `dmarcVerify`, `arcVerify` (`SenderAuth`) | per recipient | yes, `rcpt_domain` |
| `enableSpamFilter` (`MtaStageData`) | DATA | yes, `rcpt_domain` |
| `spfEhloVerify`, `spfFromVerify`, `reverseIpVerify` (`SenderAuth`) | connection / MAIL FROM | no, recipient unknown yet |
| `require`, `rejectNonFqdn` (`MtaStageEhlo`) | EHLO | no |
**Settings › Spam Filter › General** (`SpamSettings`): set `enable` to `false`. This is one switch for the whole
server, so if other domains share the instance their spam filtering goes off too. For that case run a separate
Stalwart instance for the test domain.
### 2.1 Per-domain settings
Notes:
In each expression, replace `mail-test.example.org` with your `MAIL_DOMAIN`. Every `else` branch below is the
Stalwart default, so other domains behave exactly as before.
**Settings › MTA › Inbound › Sender Authentication** (`SenderAuth`):
```json
{
"dkimVerify": {
"match": { "0": { "if": "rcpt_domain == 'mail-test.example.org'", "then": "disable" } },
"else": "relaxed"
},
"dmarcVerify": {
"match": {
"0": { "if": "rcpt_domain == 'mail-test.example.org'", "then": "disable" },
"1": { "if": "local_port == 25", "then": "relaxed" }
},
"else": "disable"
},
"arcVerify": {
"match": { "0": { "if": "rcpt_domain == 'mail-test.example.org'", "then": "disable" } },
"else": "disable"
}
}
```
**Settings › MTA › Session › Data Stage** (`MtaStageData`), spam filter off for the test domain:
```json
{
"enableSpamFilter": {
"match": { "0": { "if": "rcpt_domain == 'mail-test.example.org'", "then": "false" } },
"else": "is_empty(authenticated_as)"
}
}
```
Keep `SpamSettings.enable` (Settings › Spam Filter › General) **on**, it is the global switch for all domains.
Check the defaults of your instance first and keep them in the `else` branches if they differ from the ones above.
`rcpt_domain` is the *last* recipient of the message. A mail addressed to the test domain and another local
domain at the same time is therefore treated by the last recipient. Test mails have one recipient, so this does not matter.
### 2.2 Settings that cannot be limited to one domain
SPF and reverse-DNS checks run before the recipient is known. At their defaults (`relaxed` on port 25) they only
record a result and never reject, and the spam filter that would act on it is off for the test domain (2.1),
so leave `spfEhloVerify`, `spfFromVerify` and `reverseIpVerify` at their defaults.
The EHLO stage can reject before the recipient is known: `rejectNonFqdn` (default: on port 25) refuses a sender
whose HELO name is not a valid hostname, and the sender gets a bounce instead of a report. If you want the report
anyway, set `rejectNonFqdn` and `require` to `false` (**Settings › MTA › Session › EHLO Stage**). This applies to
all domains on the server, so for a shared server prefer a dedicated Stalwart instance or listener for the test domain.
### 2.3 Everything else
- With the checks disabled, Stalwart writes no `Received-SPF` / `Authentication-Results` headers. That is
intended: Mail Tester verifies SPF/DKIM/DMARC from the raw message and the connecting IP.
- Remove rate limits / auto-ban rules that affect the sending IPs (Settings › Security), otherwise your own
repeated tests may get blocked.
- Do **not** disable the `Received` header: Mail Tester reads the sender IP, HELO name and TLS usage from it.
- Test: send a mail with a broken DKIM signature or from an IP without SPF to the test domain. It must arrive
and show up in the report. The same mail to a normal domain must still be treated by your usual rules.
<details>
<summary>Older Stalwart (0.11 / 0.15, <code>config.toml</code>)</summary>