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

97 lines
3.0 KiB
YAML

# Scribase Mail: self-host stack (web + Postgres + Redis, plus Mailpit for
# local trials). Start it with ./scripts/selfhost.sh, which writes .env with
# generated secrets and runs `docker compose up -d`.
#
# Dashboard http://localhost:3000
# Resend-compatible API http://localhost:3000/api/resend (RESEND_BASE_URL)
# Native REST API http://localhost:3000/api/v1
# Mailpit (caught mail) http://localhost:8025 (profile "mailpit")
#
# Real delivery: point SMTP_* in .env at your relay and drop "mailpit" from
# COMPOSE_PROFILES. See docs/SELF-HOSTING.md.
name: scribase-mail-selfhost
services:
postgres:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_USER: ${POSTGRES_USER:-scribase_mail}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?run ./scripts/selfhost.sh or set POSTGRES_PASSWORD in .env}
POSTGRES_DB: ${POSTGRES_DB:-scribase_mail}
volumes:
- postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 5s
timeout: 5s
retries: 20
redis:
image: redis:7-alpine
restart: unless-stopped
# BullMQ needs noeviction; AOF keeps queued jobs across restarts.
command: ["redis-server", "--maxmemory-policy", "noeviction", "--appendonly", "yes"]
volumes:
- redis:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 5s
retries: 20
mailpit:
image: axllent/mailpit:v1.27
restart: unless-stopped
profiles: [mailpit]
ports:
- "${SCRIBASE_MAIL_BIND:-127.0.0.1}:${MAILPIT_PORT:-8025}:8025"
# Pre-send address verification (reacherhq/check-if-email-exists). Opt-in:
# needs outbound port 25 open to do a real SMTP handshake. Start with
# `docker compose --profile reacher up -d` and set REACHER_API_URL to
# http://reacher:8080 in .env.
reacher:
image: reacherhq/backend:latest
restart: unless-stopped
profiles: [reacher]
healthcheck:
test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:8080 || exit 0"]
interval: 10s
timeout: 5s
retries: 10
web:
image: ${SCRIBASE_MAIL_IMAGE:-ghcr.io/caelum0x/scribase-mail-studio:latest}
build:
context: .
dockerfile: docker/Dockerfile
args:
IS_CLOUD: "false"
restart: unless-stopped
env_file: .env
environment:
HOSTNAME: 0.0.0.0
PORT: "3000"
NEXT_PUBLIC_IS_CLOUD: "false"
DATABASE_URL: postgresql://${POSTGRES_USER:-scribase_mail}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-scribase_mail}
REDIS_URL: redis://redis:6379
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
ports:
- "${SCRIBASE_MAIL_BIND:-127.0.0.1}:${SCRIBASE_MAIL_PORT:-3000}:3000"
healthcheck:
test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:3000/api/health || exit 1"]
interval: 10s
timeout: 5s
retries: 30
start_period: 30s
volumes:
postgres:
redis: