SMTP for magic-link delivery

Configure SMTP so magic-link sign-in emails actually reach your teammates.

Eddytor signs users in with magic links (no passwords). To send those links by email you must configure SMTP. Without SMTP - the default - magic-link bodies are written to the server logs instead of sent.

Heads up

No SMTP is fine for a solo operator (read the link from the logs), but teammates can't sign in until SMTP is set. It's on the Production checklist.

Configure

Set these in .env (Compose) or the secret (Kubernetes):

EDDYTOR_SMTP_HOST=smtp.example.com
EDDYTOR_SMTP_PORT=587
EDDYTOR_SMTP_USER=apikey-or-username
EDDYTOR_SMTP_PASS=…
EDDYTOR_SMTP_FROM=eddytor@example.com

Point it at SES SMTP, Postfix, Mailgun, Azure Communication Services, or any SMTP relay. Restart the server afterward - config is read at boot.

TLS and authentication

TLS follows the port unless you set EDDYTOR_SMTP_TLS:

PortDefaultOverride
587, and any port not listedSTARTTLS, required - the send fails if the server doesn't offer itEDDYTOR_SMTP_TLS=starttls
465Implicit TLSEDDYTOR_SMTP_TLS=implicit (or tls, ssl)
25, 1025PlaintextEDDYTOR_SMTP_TLS=none (or plain, off)

An unknown or empty EDDYTOR_SMTP_TLS value stops the server at boot.

For a relay that accepts mail without a login, leave EDDYTOR_SMTP_USER and EDDYTOR_SMTP_PASS unset. Eddytor sends credentials only when both are set.

Heads up

Microsoft 365: Microsoft is retiring SMTP AUTH with a username and password in Exchange Online (MC786329). Send through Microsoft Graph instead, log in with XOAUTH2, or relay through a service that doesn't depend on it, such as Azure Communication Services.

Microsoft 365 with OAuth (XOAUTH2)

Log in to smtp.office365.com with an Entra token instead of a password. The identity is set up as for Mail via Microsoft Graph, with two differences: grant the application permission Office 365 Exchange Online → SMTP.SendAsApp instead of Mail.Send, and give it access to the mailbox:

Add-MailboxPermission -Identity eddytor@contoso.com -User <sp-object-id> -AccessRights FullAccess
Set-CASMailbox -Identity eddytor@contoso.com -SmtpClientAuthenticationDisabled $false
EDDYTOR_SMTP_HOST=smtp.office365.com
EDDYTOR_SMTP_FROM=eddytor@contoso.com   # also the login user unless EDDYTOR_SMTP_USER is set
EDDYTOR__MAIL__SMTP_AUTH=xoauth2
EDDYTOR__MAIL__TENANT_ID=<tenant-id>
EDDYTOR__MAIL__CLIENT_ID=<client-id>
EDDYTOR__MAIL__CREDENTIAL=client_secret  # or workload_identity | managed_identity
EDDYTOR_MAIL_CLIENT_SECRET=<client-secret>

Eddytor refuses XOAUTH2 over plaintext. Prefer Graph where you can: it needs no FullAccess. A failed send logs the reply code:

  • 535 5.7.139 - SMTP AUTH is disabled for the tenant, and the mailbox setting hasn't taken effect yet. It can take a while to apply.
  • 535 5.7.3 - Exchange refused the token: check SMTP.SendAsApp and the mailbox permission.

Exchange keeps a copy of every SMTP send in the mailbox's Sent Items, so sign-in and invite links collect there. Apply a retention policy to the mailbox.

docker compose logs eddytor-server | grep -i 'sign in to eddytor' -A2

On Kubernetes, kubectl -n eddytor logs deploy/eddytor-server | grep -i 'sign in to eddytor' -A2.

On this page