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.
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
- 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.
- Add a domain. In trial mode use a reserved name such as
acme.test(.test,.localhost,.exampleand.invalidverify without DNS). - 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)