SMTP
SMTP is the standard way mail programs hand messages to a mail server. Use it if you already have a mailbox with your web host, Google Workspace, Fastmail or Office 365. It is available on Node and Docker only: Cloudflare Workers cannot use it, and EMAIL_PROVIDER=smtp there stops with the "Unknown EMAIL_PROVIDER" message.
Settings
| Variable | Default | What it does |
|---|---|---|
EMAIL_PROVIDER | log | Set to smtp. |
EMAIL_FROM | none | The sender, as Harmony Community Choir <noreply@example.org>. Many servers insist it is the address of the account you log in with. |
SMTP_HOST | none | The mail server's name. Required: without it the server refuses to start with "EMAIL_PROVIDER=smtp needs SMTP_HOST (and usually SMTP_PORT, SMTP_USER, SMTP_PASS)". |
SMTP_PORT | 587 | The port. A value that is not a number is read as 587. |
SMTP_SECURE | false | true means the connection is encrypted from the first byte (implicit TLS), which is normally port 465. Leave it false for port 587, where the connection starts plain and is upgraded to encrypted when the server offers it. Accepted true values: 1, true, yes, on. |
SMTP_USER | none | The account name, usually the full email address. If it is empty the site does not log in at all, which suits only a server that accepts mail from your machine's address. |
SMTP_PASS | none | The account's password. See Keep secrets in files. |
The site gives up if it cannot connect within 10 seconds.
A working example
A generic server on the usual submission port:
EMAIL_PROVIDER=smtp
EMAIL_FROM="Harmony Community Choir <noreply@example.org>"
EMAIL_REPLY_TO=board@example.org
SMTP_HOST=smtp.example.org
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=noreply@example.org
SMTP_PASS=replace-with-the-password
A server that wants an encrypted connection from the start:
SMTP_HOST=smtp.example.org
SMTP_PORT=465
SMTP_SECURE=true
Common mail accounts
Check your provider's current instructions, which change; these are the usual shapes.
| Account | Host | Port | Notes |
|---|---|---|---|
| Google Workspace | smtp.gmail.com | 587 | Sign in with the full address and an app password (the account needs 2-step verification on to make one), not the normal password. The sender must be that address or one of its aliases. |
| Fastmail | smtp.fastmail.com | 587 or 465 | Use an app password made for SMTP in Fastmail's settings. |
| Office 365 | smtp.office365.com | 587 | Needs an account allowed to send with SMTP authentication; where multi-factor authentication is on, use an app password. Your administrator may have switched SMTP sending off. |
| Your web host | usually mail.example.org | 587 or 465 | The host's help pages give the name and port. |
Personal and small-business mailboxes have a daily sending limit. An announcement sends one message per member, so check the limit before emailing a large choir, or send announcements through a service built for it; see Send announcements through a different service.
If something goes wrong
A failed send is written to the server log with the server's own reason, and the message counts as not sent:
SMTP send failed: Invalid login: 535-5.7.8 Username and Password not accepted.
Common causes: the wrong password (or a normal password where an app password is needed), the wrong SMTP_SECURE for the port (a connection that hangs and then times out usually means 465 without SMTP_SECURE=true), a firewall that blocks outgoing mail ports (many cloud hosts do), and a sender address the account is not allowed to use.
Then see Troubleshooting: nobody can log in, or emails do not arrive.