# Email

> Connect an email provider with SMTP_URL so the app can send invites, confirmations, invoices and reminders.

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](./docker.md#3-create-the-env-file).

## The SMTP_URL format

```text
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:

```sh
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](#sending-domain-spf-and-dkim)).

### Resend

```sh
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

```sh
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

```sh
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

```sh
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)

```sh
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](https://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](https://mailpit.axllent.org/) is a fake SMTP server that catches every email and shows it in a web inbox. Nothing reaches real recipients.

```sh
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>`:

```sh
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:

```sql
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](#provider-presets):

```sh
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](#troubleshooting)).

Emails that were only logged before you set `SMTP_URL` are not sent afterwards. Send new invites if needed.