Upgrades, backups and troubleshooting

Commands run in the directory with compose.yml. For the Cloudflare edition, see Upgrading there.

UpgradingCopy Anchor Link

docker compose pull && docker compose up -d

send0 applies database migrations when it starts, before it serves anything. If several send0 processes start at once, they take turns under a lock.

• Pin a version. Set SEND0_VERSION=0.2.0 in .env to stay on one release, or 0.2 to get its patch releases. latest moves to every new release. To upgrade, change it and run the commands above.
• Back up first. Migrations change the database, and there's no automatic rollback.
• Check the release notes on GitHub releases. If compose.yml, Caddyfile or .env.example changed, download them again from the new tag.

BackupsCopy Anchor Link

Back up the database and the blobs (raw mail and attachments). One without the other is incomplete: messages point at blobs by key.

docker compose exec -T postgres pg_dump -U send0 -Fc send0 > send0-$(date +%F).dump
docker run --rm -v send0_blobs:/data -v "$PWD":/backup alpine \
  tar czf /backup/blobs-$(date +%F).tgz -C /data .

Also keep a copy of .env. Without SECRET_KEY and the passwords, a restore needs new secrets.

• With BLOB_DRIVER=s3, the blobs live in your bucket. Back it up with your provider's tools, like versioning or replication.
• On Cloudflare, back up Postgres with pg_dump and your connection string, or your provider's backups (Neon has point-in-time restore). R2 has an S3-compatible API, so any S3 tool can copy the send0-blobs bucket.

RestoringCopy Anchor Link

On a new server, with the same .env, compose.yml and Caddyfile:

docker compose up -d postgres
docker compose exec -T postgres pg_restore -U send0 -d send0 --clean --if-exists < send0-2026-10-07.dump
docker run --rm -v send0_blobs:/data -v "$PWD":/backup alpine \
  tar xzf /backup/blobs-2026-10-07.tgz -C /data
docker compose up -d

Then run docker compose exec send0 send0 doctor, and move DNS if the server's IP changed.

RetentionCopy Anchor Link

send0 removes old mail on its own, every hour (the worker role on Docker, the cron on Cloudflare):

• When a message is older than its inbox's retention_days (1 to 30, default 7), its content is deleted: body, extracted fields, attachments and the raw .eml. The API then returns it with "expired": true. Addresses, subject and status stay, for reply-only sending, threading and bounce and complaint rates.
• 35 days after a message was created, the row is deleted, with threads left empty. Webhook events and delivery logs older than 35 days go too.

It works in batches of 1,000 for up to 20 seconds per run and logs a retention line when it changed anything. If it stops early, the next run carries on.

Where the blobs go depends on the storage:

• Local disk (BLOB_DRIVER=fs) and R2 (the Cloudflare edition): send0 deletes them itself when it removes a message's content.
• S3 or S3-compatible (BLOB_DRIVER=s3): send0 doesn't delete from the bucket, so it never needs delete permission. Add a lifecycle rule that expires raw/ and att/ after 35 days:

aws s3api put-bucket-lifecycle-configuration --bucket <your-bucket> \
  --lifecycle-configuration '{"Rules":[
    {"ID":"send0-raw","Filter":{"Prefix":"raw/"},"Status":"Enabled","Expiration":{"Days":35}},
    {"ID":"send0-att","Filter":{"Prefix":"att/"},"Status":"Enabled","Expiration":{"Days":35}}]}'

This command replaces the bucket's existing lifecycle rules, so add these to them if it has any. MinIO has the same rules (mc ilm rule add --prefix raw/ --expire-days 35 <alias>/<bucket>, and again for att/). On R2, where send0 deletes blobs itself, the same rule is an optional backstop for anything left behind, such as the blobs of a workspace purged before its mail expired:

npx wrangler r2 bucket lifecycle add send0-blobs send0-raw raw/ --expire-days 35
npx wrangler r2 bucket lifecycle add send0-blobs send0-att att/ --expire-days 35

LogsCopy Anchor Link

send0 writes one JSON object per line, with an event field.

docker compose logs -f send0
docker compose logs send0 | grep '"event":"message.rejected"'

On Cloudflare, use Workers Logs in the dashboard, or npx wrangler tail send0.

ScalingCopy Anchor Link

One container runs all three roles: http, smtp and worker. To split them, or run more than one, see Running roles separately.

• Inbound memory is bounded by SMTP_MAX_CLIENTS (default 30 sessions, each up to about 25 MiB).
• Each send0 process opens up to 10 Postgres connections.
• Roles on different machines need BLOB_DRIVER=s3, because the smtp role writes blobs that http reads.

Security checklistCopy Anchor Link

• Set OWNER_EMAIL and sign up right away. Until that account exists, sign-up is open to OWNER_EMAIL only, and it must verify the address. Whoever controls that mailbox claims the install, so use an address you control.
• Keep port 3000 unpublished. Only Caddy should reach it. The compose file doesn't publish it.
• Set TRUSTED_PROXIES if your network has other private hosts. By default, send0 believes X-Forwarded-For from any loopback or private address, which covers Caddy. If other machines on a private network can reach port 3000, narrow it to the Docker network's range. It matters for rate limits and session records.
• Rotate SECRET_KEY by setting a new value and running docker compose up -d. It signs download links for blobs on local disk (and for every download on Cloudflare). Links already issued stop working; they last 15 minutes anyway. Sessions and API keys aren't affected. With BLOB_DRIVER=s3, links are pre-signed by S3 instead.
• Treat SES_EVENTS_TOKEN as a password. It's the only credential on /internal/ses-events, and it's part of the SNS subscription URL. send0 also refuses messages from any topic except SES_EVENTS_TOPIC_ARN. To rotate it, set a new token, then replace the subscription with the new URL.
• Keep .env private. It holds every secret. Don't commit it.

TroubleshootingCopy Anchor Link