Skip to content

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.

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”.
  • The startup log names the problem: a warning when no mail server is configured, an error when the configured one cannot be reached.
  • On a fresh instance without any account, the login page also reports a configured mail server that cannot be reached. That notice disappears once the first account exists.
Section titled “Locked out? Issue a sign-in link on the server”

If mail does not work and you cannot get in (first start without a mail server, or the mail server failed later and you have no passkey), issue a sign-in link from inside the app container:

Terminal window
docker exec -it <container> node scripts/login-link.mjs you@example.com

The command prints a link that is valid for 15 minutes and works once. Open it in your browser.

  • It works for an existing account, or for any address while the instance has no account yet (that creates the first one).
  • Two-factor sign-in still applies. A suspended account gets no link.
  • The link appears only in your terminal, never in the logs. When it is used, the audit log records it and the user sees a notice.

Afterwards, fix the mail settings and add a passkey under Settings → Security, so sign-in no longer depends on mail.

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.
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

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.

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.