scribase-mail-studio/docs/SELF-HOSTING.md
caelum0x e91eb482bb feat(send): verify recipient addresses with reacherhq before every send
Wires reacherhq/check-if-email-exists (self-hosted, MIT licensed) as a
pre-send validator in the queue worker, right before the provider dispatch
that every send path (API, SMTP proxy, campaigns, scheduled, double opt-in)
shares. Recipients confirmed undeliverable are dropped before a send credit
is spent instead of bouncing after the fact.

Fails open by design: disabled, unconfigured, slow, or unreachable verifier
means every recipient is treated as unverified and the send proceeds
unchanged. A down validator must never silently drop a legitimate send.

- apps/web/src/server/service/address-verification-service.ts: REST client
  for the reacherhq/backend HTTP API (POST /v0/check_email), batched,
  timeout-bounded, never throws.
- apps/web/src/server/service/email-queue-service.ts: call the verifier
  right before provider.sendRawEmail; reject with status REJECTED when
  every recipient is invalid, otherwise send to the deliverable subset only.
- apps/web/src/env.js: REACHER_ENABLED / REACHER_API_URL / REACHER_API_KEY /
  REACHER_TIMEOUT_MS / REACHER_BLOCK_VERDICTS.
- compose.yml: optional `reacher` sidecar behind a profile (needs outbound
  port 25, so it's opt-in, not part of the default self-host stack).
- docs/SELF-HOSTING.md, .env.example, .env.selfhost.example: how to turn it
  on.

25 new/updated unit tests (12 for the service in isolation covering block,
allow, fail-open on error/timeout/non-2xx, disabled, unconfigured, batching,
custom block list; 13 in the queue worker covering full-block, partial-block,
and the default pass-through path). Full web unit suite: 574/574 passing.
2026-10-16 17:50:06 +03:00

3.6 KiB

Self-hosting Scribase Mail

Requirements: Docker with Compose v2, about 2 GB RAM.

One command

git clone https://github.com/caelum0x/scribase-mail-studio && cd scribase-mail-studio && ./scripts/selfhost.sh

scripts/selfhost.sh creates .env from .env.selfhost.example with generated secrets, pulls ghcr.io/caelum0x/scribase-mail-studio:latest (or builds it from the checkout when the image is unavailable; --build forces a local build), starts Postgres, Redis, the web app and Mailpit, and waits until the app is healthy.

What URL
Dashboard http://localhost:3000
Resend-compatible API (RESEND_BASE_URL) http://localhost:3000/api/resend
Native REST API http://localhost:3000/api/v1
Mailpit, catches all mail in trial mode http://localhost:8025

First send

  1. Open http://localhost:3000, sign in with any email address and read the code in Mailpit. The first account owns the installation; later accounts need a team invite.
  2. Add a domain. In trial mode use a reserved name such as acme.test (.test, .localhost, .example and .invalid verify without DNS).
  3. Create an API key (Developer settings > API keys) and send with the official Resend SDK:
// npm i resend
import { Resend } from "resend";

// RESEND_BASE_URL=http://localhost:3000/api/resend
const resend = new Resend(process.env.RESEND_API_KEY);

await resend.emails.send({
  from: "Acme <hello@acme.test>",
  to: ["you@example.com"],
  subject: "Hello from Scribase Mail",
  html: "<p>It works.</p>",
});

The message shows up in Mailpit with a DKIM-Signature header.

Real delivery

Edit .env:

EMAIL_PROVIDER="smtp"
SMTP_HOST="smtp.your-relay.example"
SMTP_PORT="587"
SMTP_USER="..."
SMTP_PASS="..."
SMTP_REQUIRE_TLS="true"
SMTP_SPF_RECORD="v=spf1 include:your-relay.example ~all"
NEXTAUTH_URL="https://mail.example.com"
FROM_EMAIL="Mail <noreply@example.com>"
COMPOSE_PROFILES=""

then run ./scripts/selfhost.sh again. For each sending domain publish the DKIM TXT and SPF TXT records shown on the domain page. Put a TLS reverse proxy (Caddy, nginx) in front of port 3000; set SCRIBASE_MAIL_BIND=0.0.0.0 only if you expose the port directly. For the API on its own host (like mail-api.scribase.com), rewrite every path to /api/resend{uri}; see deploy/scribase-mail.caddy.

With EMAIL_PROVIDER="smtp" bounces and complaints come from your relay's behaviour only (no provider log polling). EMAIL_PROVIDER="oci" uses Oracle Cloud Email Delivery with managed DKIM, the suppression list and delivery logs; see the OCI section of .env.selfhost.example and deploy/DEPLOY.md.

Pre-send address verification (optional)

Every send checks each recipient against reacherhq/check-if-email-exists (MIT licensed, self-hosted, no SaaS fee) right before it reaches the relay. Addresses confirmed undeliverable are dropped before a send credit is spent; if the verifier is disabled, unset, or unreachable the check fails open and every recipient still sends (it never silently drops a legitimate send).

docker compose --profile reacher up -d

then set in .env:

REACHER_API_URL="http://reacher:8080"

See REACHER_* in .env.selfhost.example for the timeout and which is_reachable verdicts to block (default: invalid only).

Operations

docker compose logs -f web      # logs
docker compose pull && docker compose up -d   # upgrade (migrations run on start)
docker compose exec postgres pg_dump -U scribase_mail scribase_mail > backup.sql
docker compose down             # stop (data kept in volumes)