Connect an email provider with SMTP_URL so the app can send invites, confirmations, invoices and reminders.
View as MarkdownCoding agents can read this page at /docs/email.md
Email is optional. Without it, the app still works, but every email (invites, password resets, notifications) is printed to the app logs instead of being sent.
The apps send email for invites, password resets, booking confirmations and reminders (Scheduler), and invoices, reminders and receipts (Invoicing). They send it through any SMTP server, which every email provider offers. SMTP is the standard protocol for handing an email to a mail server.
You configure it with two variables:
| Variable | Example | Description |
|---|---|---|
SMTP_URL |
smtp://resend:re_xxxx@smtp.resend.com:587 |
The SMTP server, user name and password in one URL |
EMAIL_FROM |
Scheduler <cal@example.com> |
The sender shown to recipients. Defaults to <app name> <noreply@<host of APP_URL>> |
Without email
If SMTP_URL is not set, nothing is sent. Each email is printed to the app logs instead, in a block that starts with [email:logged], and recorded in the email_log table. That’s enough to try the app and to copy invite or password-reset links by hand, but your users and clients won’t hear from the app.
One exception: the Docker Compose files use the Mailpit test server when SMTP_URL is unset, so on Docker you must set SMTP_URL for email to work at all. See the Docker guide.
The SMTP_URL format
smtp://USERNAME:PASSWORD@HOST:PORT
smtps://USERNAME:PASSWORD@HOST:465
- Use
smtp://with port587(or2525,2587, depending on the provider). The connection starts unencrypted and switches to TLS when the server supports it, which all the providers below do. - Use
smtps://with port465for a connection that’s encrypted from the start.
Special characters must be URL-encoded
The user name and password sit inside a URL, so characters that have a meaning in URLs must be written as codes. Common ones:
| Character | Write it as |
|---|---|
@ |
%40 |
: |
%3A |
/ |
%2F |
+ |
%2B |
# |
%23 |
? |
%3F |
% |
%25 |
| space | %20 |
For example, the user name you@gmail.com becomes you%40gmail.com. To encode a value safely, run:
python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' 'p@ss/w+rd'
# p%40ss%2Fw%2Brd
Provider presets
Pick one. Each needs a verified sending domain or address first (see Sending domain).
Resend
SMTP_URL=smtp://resend:RESEND_API_KEY@smtp.resend.com:587
The user name is the literal word resend; the password is an API key from the Resend dashboard. Resend also accepts ports 465 (use smtps://), 2587 and 2465. If port 587 is blocked where you host, try smtp://resend:RESEND_API_KEY@smtp.resend.com:2587.
Postmark
SMTP_URL=smtp://SERVER_TOKEN:SERVER_TOKEN@smtp.postmarkapp.com:587
Use your server’s Server API Token as both the user name and the password. Port 2525 also works. Emails go through the default transactional stream.
SendGrid
SMTP_URL=smtp://apikey:SENDGRID_API_KEY@smtp.sendgrid.net:587
The user name is the literal word apikey; the password is an API key with at least Mail Send permission. Port 2525 also works.
Amazon SES
SMTP_URL=smtp://SMTP_USERNAME:SMTP_PASSWORD@email-smtp.us-east-1.amazonaws.com:587
- Replace
us-east-1with the region where you verified your domain. - SES SMTP credentials are not your AWS access keys. Create them in the SES console’s SMTP settings.
- SES passwords often contain
/or+. URL-encode the password (see above). - New SES accounts start in a sandbox where you can only send to verified addresses. Request production access in the SES console before going live.
Gmail (small setups only)
SMTP_URL=smtp://you%40gmail.com:APP_PASSWORD@smtp.gmail.com:587
EMAIL_FROM=Scheduler <you@gmail.com>
- Turn on 2-Step Verification for the Google account.
- Create an app password at myaccount.google.com/apppasswords. Google shows a 16-character code; remove the spaces.
- Use your Gmail address (with
@written as%40) as the user name and the app password as the password.
Set EMAIL_FROM to the same Gmail address. App passwords aren’t available for some work or school accounts, or with Advanced Protection. Gmail also limits how many emails you can send per day, so use a real email provider once you have more than a handful of users.
Mailpit (testing)
Mailpit is a fake SMTP server that catches every email and shows it in a web inbox. Nothing reaches real recipients.
SMTP_URL=smtp://localhost:1025 # Mailpit on the same machine
SMTP_URL=smtp://mailpit:1025 # Mailpit in the same Docker Compose project
The Docker Compose files start Mailpit when you add --profile dev, with the inbox at http://localhost:8025. Don’t use it on a public server.
Choosing EMAIL_FROM
EMAIL_FROM is the sender recipients see, written as Name <address>:
EMAIL_FROM=Acme Billing <billing@acme.com>
The address must be on a domain (or be an address) that your provider has verified for you. The default, noreply@ plus your app’s host name, only works if that exact domain is verified, so on addresses like *.up.railway.app or *.onrender.com you must set EMAIL_FROM yourself. Recipients who reply write to this address, so use one you read, or one that tells people where to write.
Sending domain, SPF and DKIM
To send from you@yourdomain.com, the provider has to prove to receiving mail servers that it’s allowed to send for yourdomain.com. Otherwise your emails land in spam or are rejected. The provider’s dashboard walks you through it: you add a few DNS records at your domain registrar and wait for them to be verified.
- SPF is a DNS record that lists which servers may send email for your domain.
- DKIM is a DNS record holding a public key; the provider signs each email with the matching private key, so receivers can check the email is genuine and unchanged.
- DMARC is a DNS record that tells receivers what to do with emails that fail those checks. Providers usually suggest a starting value.
Many providers recommend sending from a subdomain (such as mail.yourdomain.com) to keep app email separate from your normal mailbox. Follow your provider’s instructions; you don’t need to understand the records in detail.
Testing
- Set
SMTP_URLandEMAIL_FROMand restart the app. - Invite yourself (another address you own) from Settings > Members > Invite member.
- Check that the email arrives and isn’t in spam.
Troubleshooting
Each email attempt is recorded in the email_log table, with the error message for failures:
SELECT created_at, "to", subject, status, error FROM email_log ORDER BY created_at DESC LIMIT 20;
- Status
logged:SMTP_URLisn’t set on the running app. - Authentication errors (for example
Invalid loginor535): wrong user name or password, or a special character that isn’t URL-encoded. - Timeouts or connection refused: the port is blocked by your host or firewall. Try 2525 or 2587 if your provider supports it. Render’s free services block 25, 465 and 587.
- Sender rejected, or emails go to spam: the
EMAIL_FROMdomain isn’t verified with the provider, or the SPF and DKIM records are missing. - Inviting someone shows an error: invites are sent right away, so an SMTP failure makes the invite fail. Check the logs and
email_log. Booking and invoice emails are retried automatically in the background.
Adding this to an existing deploy
You can add email at any time. Set these variables on the running app, with the values for your provider from Provider presets:
SMTP_URL=smtp://resend:re_xxxxxxxx@smtp.resend.com:587
EMAIL_FROM=Scheduler <cal@example.com>
- Railway: open the app service’s Variables tab, add the variables, and deploy the staged changes. Railway redeploys the service.
- Render: open the web service’s environment settings, add the variables, and save. Render redeploys the service.
- Docker Compose: add the variables to
.envin the app’s folder (apps/schedulerorapps/invoicing), then rundocker compose up -din that folder. This recreates the app container with the new values.docker compose restartis not enough, because it doesn’t reload.env.
The new settings take effect only after this restart or redeploy.
To confirm it works:
- Check the logs after the restart: new emails should no longer show up as
[email:logged]. - Invite an address you own from Settings > Members > Invite member and check that the email arrives.
- If it doesn’t, look at the latest rows in
email_log(see Troubleshooting).
Emails that were only logged before you set SMTP_URL are not sent afterwards. Send new invites if needed.