diff --git a/TODO.md b/TODO.md index 97829bf..0afdf8b 100644 --- a/TODO.md +++ b/TODO.md @@ -115,6 +115,7 @@ - [x] `request-access.php` (resend path): catch 550 → return HTTP 422 instead of silent "access approved" - [x] `StudentEmail::sendConfirmation()`: catch `SmtpSendException` → log + return false (submission must not be aborted) - [x] `admin/actions/access-request.php`: catch `SmtpSendException` after approval → flash warning distinguishing recipient-rejected vs transient +- [x] `docs/SMTP_550_POSTFIX_FIX.md` — report for Postfix admin (diagnosis, 3 fix options, verification steps) ## CSS refactor diff --git a/docs/SMTP_550_POSTFIX_FIX.md b/docs/SMTP_550_POSTFIX_FIX.md new file mode 100644 index 0000000..6ad203b --- /dev/null +++ b/docs/SMTP_550_POSTFIX_FIX.md @@ -0,0 +1,139 @@ +# SMTP 550 — Recipient Address Rejected (`erg.school`) + +**Date:** 2026-04-30 +**Symptom:** Access-link emails to `@erg.school` addresses fail with: + +``` +550 5.1.1 : Recipient address rejected: User unknown in virtual mailbox table +``` + +--- + +## What is happening + +The SMTP relay that XAMXAM uses to send outbound email is a Postfix instance +that is **also configured as the authoritative mail server for `erg.school`**. + +When XAMXAM sends `RCPT TO:`, Postfix looks up the address in +its local `virtual_mailbox_maps` table. Because the individual mailbox does not +exist in that table, Postfix rejects the message permanently with 550 instead +of forwarding it outward. + +This affects **all** outbound email to `@erg.school` sent through this relay, +regardless of whether the address is real — Postfix never tries to route the +message anywhere else. + +--- + +## Why it happens + +Postfix owns a domain in one of two ways: + +| Setting | Effect | +|---|---| +| `mydestination` | Postfix delivers locally via Unix accounts | +| `virtual_mailbox_domains` | Postfix delivers locally via `virtual_mailbox_maps` | + +If `erg.school` (or a wildcard matching it) appears in either of these on the +outbound relay, Postfix will **never relay** mail to that domain — it will +always attempt local delivery and reject unknown recipients. + +To confirm, run on the relay server: + +```bash +postconf mydestination +postconf virtual_mailbox_domains +postconf relay_domains +``` + +Check whether `erg.school` appears (directly or via a lookup table). + +--- + +## Fix options + +### Option A — Preferred: use a different relay for outbound mail + +Configure XAMXAM to send via an SMTP relay that does **not** host `erg.school` +(e.g. a dedicated outbound relay, a transactional mail provider, or the +outbound smarthost if one exists). + +Change the SMTP settings in the XAMXAM admin panel (`/admin/parametres.php`) +to point to that relay. + +--- + +### Option B — Remove `erg.school` from local delivery on the relay + +If the relay should not be the final destination for `erg.school` mail, remove +it from the relevant Postfix maps. + +**If it is in `mydestination`:** + +```ini +# /etc/postfix/main.cf +mydestination = localhost, localhost.localdomain +# remove erg.school (and any wildcard covering it) +``` + +**If it is in `virtual_mailbox_domains`:** + +```ini +# /etc/postfix/main.cf +virtual_mailbox_domains = ... +# remove erg.school from the list (or from the referenced lookup table) +``` + +After editing `main.cf`: + +```bash +postfix check +systemctl reload postfix +``` + +--- + +### Option C — Add a `transport_maps` override for the domain + +If `erg.school` must remain in `virtual_mailbox_domains` for inbound delivery +but outbound mail from XAMXAM should still be relayed, add a transport override +so that mail *to* `erg.school` sent by XAMXAM is forwarded to the real MX +rather than delivered locally. + +```ini +# /etc/postfix/main.cf +transport_maps = hash:/etc/postfix/transport +``` + +``` +# /etc/postfix/transport +erg.school smtp:[mail.erg.school]:25 +``` + +```bash +postmap /etc/postfix/transport +systemctl reload postfix +``` + +> **Note:** This approach is fragile — if XAMXAM is on the same server as the +> MX, you risk a delivery loop. Option A or B is cleaner. + +--- + +## Verification + +After applying the fix, test with XAMXAM's built-in SMTP probe +(`/admin/parametres.php` → Test SMTP). Then submit a real access request with +an `@erg.school` address and confirm the email arrives. + +You can also test directly from the server: + +```bash +swaks --to test.user@erg.school \ + --from xamxam@erg.be \ + --server --port 587 \ + --tls --auth-user --auth-password +``` + +A successful relay returns `250 2.0.0 Ok: queued as …`. +A 550 response confirms the domain is still being caught locally.