Skip to content

Email

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 port 587 (or 2525, 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 port 465 for 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-1 with 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>
  1. Turn on 2-Step Verification for the Google account.
  2. Create an app password at myaccount.google.com/apppasswords. Google shows a 16-character code; remove the spaces.
  3. 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

  1. Set SMTP_URL and EMAIL_FROM and restart the app.
  2. Invite yourself (another address you own) from Settings > Members > Invite member.
  3. 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_URL isn’t set on the running app.
  • Authentication errors (for example Invalid login or 535): 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_FROM domain 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 .env in the app’s folder (apps/scheduler or apps/invoicing), then run docker compose up -d in that folder. This recreates the app container with the new values. docker compose restart is not enough, because it doesn’t reload .env.

The new settings take effect only after this restart or redeploy.

To confirm it works:

  1. Check the logs after the restart: new emails should no longer show up as [email:logged].
  2. Invite an address you own from Settings > Members > Invite member and check that the email arrives.
  3. 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.