Deploy and Host Plunk on Railway

Built for an LLM agent to deploy and use. There is no signup page and nothing to fill in: the admin login, a public API key and a secret API key are generated at deploy time and are valid from the first boot. The contract below lists every URL, variable name and one script that proves it works.

Plunk is a self-hosted email platform and an open source alternative to Resend and Mailchimp. It sends transactional email through your own AWS SES account, tracks events, and runs automations and campaigns from one dashboard and one REST API.

About Hosting Plunk

This template runs four services built from the official Plunk 0.18.0 image (ghcr.io/useplunk/plunk, pinned by digest): plunk-api (the REST API plus the background queue worker), plunk-dashboard (the web UI), a Postgres 17 database on a volume and a Redis 7 queue on a volume. The upstream image bundles everything behind one nginx on four hostnames, which Railway cannot route, so each service starts only the part it needs. On first boot plunk-api applies the database migrations and creates the admin user and a project named Default with the keys from the service variables. The same values apply after every redeploy. Public signup is closed, so nobody else can register on your instance. Allow about two minutes for the first deploy to turn healthy.

Sending real email needs your own AWS SES account: set AWS_SES_REGION, AWS_SES_ACCESS_KEY_ID and AWS_SES_SECRET_ACCESS_KEY on the plunk-api service and redeploy it. Until you do, the API, dashboard, contacts and event tracking all work, and only the SES calls log errors.

Agent contract

Public URL: API_URL, which is https:// plus the RAILWAY_PUBLIC_DOMAIN of the plunk-api service. The dashboard is https:// plus the RAILWAY_PUBLIC_DOMAIN of the plunk-dashboard service.
Private URL: http://plunk-api.railway.internal:8080
Credentials: dashboard login is PLUNK_ADMIN_EMAIL with the password in PLUNK_ADMIN_PASSWORD; the public API key is PLUNK_PUBLIC_KEY; the secret API key is PLUNK_SECRET_KEY. All four are variables on the plunk-api service.
Auth: send Authorization: Bearer followed by PLUNK_PUBLIC_KEY to POST /v1/track. Send Authorization: Bearer followed by PLUNK_SECRET_KEY to GET /contacts, POST /v1/send and POST /v1/verify.
Health: GET /health returns 200 with no credentials

# run with API_URL, PLUNK_PUBLIC_KEY and PLUNK_SECRET_KEY set; needs curl
curl -s -o /dev/null -w 'health %{http_code}\n' "$API_URL/health"
curl -fsS -X POST "$API_URL/v1/track" \
  -H "Authorization: Bearer $PLUNK_PUBLIC_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"event":"agent-contract-test","email":"agent@example.com"}' -o /dev/null -w 'track %{http_code}\n'
sleep 3
curl -fsS -H "Authorization: Bearer $PLUNK_SECRET_KEY" "$API_URL/contacts" | grep -o 'agent@example.com' | head -1

A fresh deploy prints health 200, track 200 and agent@example.com. Sign in to the dashboard with the admin email and password, or call the API with the keys above.

Why Deploy Plunk on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Plunk on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Agent-ready - generated admin password and API keys that work on first boot, a contract block and one working script; no signup step.
Stable credentials - the login and both API keys are the same after every redeploy.
State survives redeploys - contacts, events and campaigns live in Postgres and the queue in Redis, each on a volume.
Closed signup - public registration is disabled, so only your admin account exists.
Pinned image - pinned by digest, so a redeploy never changes the server version underneath you.

Common Use Cases

Resend alternative for transactional email - send password resets and receipts through your own AWS SES at SES prices.
Product event tracking and automations - post events from your app and trigger emails from them.
Agent-driven email - let an AI agent create contacts, track events and send mail through the REST API.

Dependencies for Plunk Hosting

A Postgres database and a Redis instance, each with a volume (both included in this template).
An AWS SES account with verified sending identity, to deliver real email (set on plunk-api after deploy).

Deployment Dependencies

useplunk/plunk - upstream project
Plunk documentation - API reference and self-hosting notes
AWS SES - the email delivery provider