Email: what the site sends and how to choose a provider

Your site sends email so that members can log in (they ask for a link and it arrives in their inbox), so that visitors' contact-form messages reach the choir, and so that you can email announcements and mailings. Out of the box the site sends nothing real: you must pick a provider before members can log in on a live site. This page helps you choose; the pages after it give the settings for each one.

On a site we host

Email is already working and there is nothing to configure; see How your site sends email.

On a self-hosted site

You set up email in the server's settings, as this page and the ones after it describe.

What the site sends

In brief:

• A login link to a member (or to an admin, if you use one login for each admin).
• Contact-form messages from your public site, forwarded to the choir.
• Announcements to members, and mailings to donors and ticket holders, when an admin presses send.
• Tickets, receipts and thank-you messages to the people who bought or gave.
• A short notice to the choir when someone stops (or restarts) a kind of mail.

The complete list, with what triggers each one and whether the reader can stop it, is Every email your site sends.

Choose a provider

You choose one with EMAIL_PROVIDER. Whichever you pick, the domain in EMAIL_FROM has to be verified with that provider, or mail will be refused or land in spam (see Sender addresses, sending speed and testing).

EMAIL_PROVIDER	What it is	Settings it needs	Runs on
log	Writes each email to the server log. Nothing is sent. This is the default.	none	Node, Docker, Cloudflare
none	Email is off.	none	Node, Docker, Cloudflare
ses	Amazon SES	AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY	Node, Docker, Cloudflare
smtp	Any ordinary mail server	SMTP_HOST (and usually SMTP_USER, SMTP_PASS)	Node and Docker only
resend	Resend	RESEND_API_KEY	Node, Docker, Cloudflare
sendgrid	SendGrid	SENDGRID_API_KEY	Node, Docker, Cloudflare
mailgun	Mailgun	MAILGUN_API_KEY, MAILGUN_DOMAIN	Node, Docker, Cloudflare
postmark	Postmark	POSTMARK_SERVER_TOKEN	Node, Docker, Cloudflare

Every provider other than log and none also needs EMAIL_FROM. If it is missing, the server reports "EMAIL_FROM is not set" when it starts (and npm run config:check lists it), and nothing is sent. What you see then depends on the message: a member's login link is not sent and the log says Member login link for ... not sent: email is unconfigured; a contact-form message is kept under Messages; an announcement or mailing is refused with "Email is not set up on the server, so nothing was sent"; and other mail, such as tickets and gift thank-yous, is refused with the log line Email not sent: EMAIL_FROM is not set.

A rough guide to choosing:

• Already have a mail account with your web host, Google Workspace, Fastmail or Office 365, and you run on Node or Docker: use SMTP. Check how many messages a day the account allows, since an announcement sends one message per member.
• Running on Cloudflare Workers: SMTP is not available. Use one of the others.
• Want a service built for sending: any of Amazon SES, Resend, SendGrid, Mailgun or Postmark will do. They all ask you to verify your domain.

You can also use one service for logins and another for announcements; see Send announcements through a different service.

An unknown value

If EMAIL_PROVIDER is anything else, the server stops when it starts, with:

Unknown EMAIL_PROVIDER "mailchimp". Use none, log, ses, smtp, resend, sendgrid, mailgun or postmark.

The value is not case-folded, so write it in lower case. On Cloudflare Workers smtp gets the same message, because Workers cannot send SMTP.

log: the default

With EMAIL_PROVIDER=log, or with no EMAIL_PROVIDER at all, each email is written to the server log instead of being sent. Every line starts with [email]:

[email] To: member@example.org
[email] Subject: Your Harmony Community Choir login link
[email]   Hi Sam,
[email]   
[email]   Use this link to log in to the Harmony Community Choir member portal:
[email]   https://choir.example.org/member/login?token=...

The site counts such an email as sent: an announcement reports success, and a contact-form message is treated as delivered (when there is an address to send it to, see CONTACT_FORM_TO in Sender addresses, sending speed and testing), so it is not kept in Messages. That is useful on your own computer, where you can copy a login link from the log. On a live site it means nobody can log in by emailed link, and contact messages are lost. When the site runs in production with log, npm run config:check lists this problem and the start-up log warns with it (after [config]):

EMAIL_PROVIDER is "log": member login links and contact messages will only be written to the server log

none: email off

With EMAIL_PROVIDER=none, nothing is sent and the email itself is not written to the log. The effects:

• Members cannot be sent login links. Log-in attempts for them simply do not result in an email (the server notes Member login link for ... not sent: email is off in its log).
• Contact-form messages are kept on the server instead, and an admin reads them under Messages.
• The announcement screen says "Email is not set up on the server (EMAIL_PROVIDER and EMAIL_FROM), so announcements cannot be emailed yet." Announcements are still posted in the member portal.
• Mailings to donors and ticket holders are refused with "Email is not set up on the server, so nothing was sent".

Where the site would have sent some other email, such as a ticket confirmation, the log says Email not sent: EMAIL_PROVIDER is none. Use none only if you do not run a member portal by emailed link.

If you use an admin login by email

With ADMIN_AUTH=table, admins also receive login links by email, so log and none leave only the ADMIN_USERNAME and ADMIN_PASSWORD spare key as a way in. The server warns about this at start-up. See Admin sign-in.

There is no Email page in the admin panel

On a site we host, an Email page in the admin panel lets a choir on a paid plan send its announcements through its own mail server. That page does not exist on a self-hosted site: the equivalent is the ANNOUNCEMENT_ settings in Send announcements through a different service. If you try its address, the server answers "This site sends its email through the platform."

Next

1. Follow the page for your provider.
2. Restart the server, then check your configuration.
3. Send yourself a test; see Sender addresses, sending speed and testing.