docs: add SMTP 550 postfix fix report for mail admin

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
 

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 <user@erg.school>: 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:<user@erg.school>`, 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 <smtp_host> --port 587 \
+      --tls --auth-user <username> --auth-password <password>
+```
+
+A successful relay returns `250 2.0.0 Ok: queued as …`.  
+A 550 response confirms the domain is still being caught locally.