Self-host MailySend on a plain Node server

01What is different without Workers

Less than you would expect. The build emits a Worker-shaped module — { fetch, queue, email, scheduled } — because that is what the whole codebase is written against, and the Node listener’s entire job is to open a socket and turn Node streams into Request and Response.

The seam is one package, not a runtime branch. Everything platform-shaped — the database, the queue, the blob store, the key-value cache — is reached through @mailysend/platform rather than imported directly, which is what makes “the Node target runs the same code” checkable by reading rather than by trusting. node-server.mjs is deliberately one file with no dependencies for the same reason, and it does exactly two things worth knowing about: prerendered HTML and hashed assets are served straight from .output/client without touching the application, and everything else goes to the same fetch the Workers runtime would have called.

What the adapters do instead

If you would rather not have a Cloudflare account in the picture at all, the other three transports — SES, Resend and generic SMTP — need nothing from that last row; the transport guide has the real ceilings for each.

02Build the Node target

Two commands.

$ pnpm install --frozen-lockfile
$ pnpm build:node
Prerendered 42 pages
llms: wrote .output/client/sitemap.xml

Prerendering is not decoration. Every public page — marketing, docs and every guide — is rendered to static HTML at build time from one list that also drives sitemap.xml, llms.txt and robots.txt, so those four cannot drift apart. Link crawling and auto-discovery are both off, deliberately: crawling minted a sitemap URL per deep anchor, and auto-discovery swept the per-user dashboard screens into the static output and the sitemap, where they must never be cached or indexed. A prerender error fails the build, because the alternative — the setting that let it pass — once produced “Prerendered 0 pages”, a zero exit code, and a deploy with no static HTML at all.

This is the bug that hid the longest. MS_PUBLIC_URL lives in the .env the process manager loads at run time, and nothing put it into the shell during pnpm build:node. So the sitemap host resolved to undefined, the sitemap was silently disabled, and robots.txt advertised a URL that returned 404 for the life of the site. A build that still has no host now ships a robots.txt with no Sitemap: line at all, rather than pointing crawlers at a page that is not there — and only a build with MS_LANDING=marketing may publish mailysend.com as its canonical host, because a sitemap naming somebody else’s host is worse than no sitemap.

You do not need a real signing secret to build. The prerendering server wants one, so the build generates a random build-scoped value when MS_SECRET is unset: nothing prerendered is signed, and the value dies with the process. A real secret in the environment still wins.

03Run it behind nginx

One process on a loopback port, nginx in front of it, and a process manager to restart it. Nothing more exotic is needed, and anything more exotic has a cost you should be choosing deliberately.

$ pm2 start ecosystem.config.cjs
mailysend │ fork │ online │ 127.0.0.1:8917
$ pm2 save && pm2 startup

map $http_x_forwarded_proto $ms_forwarded_proto {
    ""      $scheme;
    default $http_x_forwarded_proto;
}

server {
  server_name mail.yourdomain.com;
  client_max_body_size 200M;

  location / {
    proxy_pass http://127.0.0.1:8917;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $ms_forwarded_proto;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

04The environment variables that matter

Five variables carry the weight.

Where each one lives

# /srv/mailysend/.env — read by the runtime and by the build
MS_PUBLIC_URL=https://mail.yourdomain.com
MS_SECRET=…                 # openssl rand -hex 32
SES_REGION=…                # only needed before anyone has signed in

That is the practical consequence of the build reading .env: setting MS_PUBLIC_URL in one file is what makes sitemap.xml exist for a self-hosted deployment, and it does so without a build environment that has to be kept in sync with a runtime one by hand.

Back up the data directory, not the checkout. MS_DATA_DIR holds mailysend.db — contacts, messages, events, settings, the queue spool, the local analytics table — and a blobs/ directory with raw inbound MIME and attachments. Everything else on the box is reproducible from git.

05Upgrading without downtime you will notice

Pull, build, reload. There is no migrate step to remember.

$ cp -a .data .data.bak
$ git fetch && git checkout <tag>
$ pnpm install --frozen-lockfile && pnpm build:node
$ pm2 reload mailysend

Migrations run themselves. The first touch after a restart runs any migration the _migrations table does not already list, then ensures the workspace exists — both idempotent, so the cost on every later cold start is one indexed lookup. This is the same code path the Cloudflare deployment runs on its first request, which is why there is one migration set for D1 and node:sqlite rather than two that can disagree.

pm2 reload drains rather than kills. A hard kill mid-batch is survivable — a send attempt holds a lease, the lease expires, and the work is picked up again — but a clean drain is cheaper and does not produce a minute of confusing telemetry. With one fork-mode process there is no zero-downtime handover to be had, so expect a short gap; nginx will return 502 during it, and that is the honest behaviour rather than a queue of requests waiting on a process that may not come back.

Common questions