Email & SMTP troubleshooting

Several flows depend on outbound email: magic-link sign-in, team invitations, email-address changes (and their security notifications), and account-deletion confirmations. If any of these “don’t arrive”, work through the checks below.

1. Is SMTP configured at all?

Orimora only sends mail when a real SMTP server is configured. When it isn’t, the email-dependent actions are disabled in the UI with a hint — rather than appearing to work and silently failing.

• If the email-change form, the invite form, or magic-link sign-in is greyed out, SMTP is not set up. Configure the SMTP_* variables — see Configuration → SMTP — and restart the app.
• The default SMTP_HOST=localhost:1026 is the local Mailpit placeholder; in production it counts as “not configured”.

2. Run the live connection test

A system administrator can verify connectivity without sending a real message under Settings → Admin → Test SMTP. This connects to the server and authenticates:

• Green — Orimora can reach and log in to the server. If mail still doesn’t arrive, the problem is downstream (recipient, spam, sender reputation) — continue below.
• Red — the error message points at the cause (host unreachable, auth rejected, TLS handshake failed). Fix the SMTP_* settings and retest.

3. Common causes

Symptom	Likely cause / fix
Connection refused / timeout	Wrong SMTP_HOST/SMTP_PORT, or the host’s firewall blocks outbound 587/465
Authentication failed	Wrong SMTP_USER/SMTP_PASSWORD; some providers need an app-specific password
TLS / STARTTLS handshake failed	Use port 587 (STARTTLS) or 465 (implicit TLS); Orimora enforces TLS outside localhost
Sent, but never delivered	Recipient spam folder, or the provider rejects the SMTP_FROM address (SPF/DKIM/DMARC)
Delivered for some, not others	Domain-level filtering at the recipient; check the provider’s suppression/bounce list

Sender reputation

Use a SMTP_FROM address on a domain you control, with SPF and DKIM records pointing at your SMTP provider. Mail from a mismatched or unauthenticated sender is the most common reason messages are silently dropped or sent to spam.

4. Delivery is asynchronous

Outbound mail is queued (Redis-backed) and sent by a background worker, so a click returns immediately even though delivery happens a moment later. Transient SMTP failures are retried automatically. A persistent failure (e.g. wrong credentials) will retry and then give up — check the application logs for the send error, and confirm Redis/the worker is running.

5. Local development

For local dev, Orimora ships with Mailpit (localhost:1026): every message is captured in its web UI instead of being delivered, so all email flows work end-to-end without a real provider.

See also

• Configuration → SMTP — the SMTP_* variables
• Team members — invitations and email recovery
• Security — magic-link sign-in and email changes