// Field Guide — Base Camp — entry 03

Configuration

All configuration lives under the :squatch_mail app env. SquatchMail.Config is the source of truth; this page is the trail map.

config :squatch_mail,
  repo: MyApp.Repo,          # required — the Ecto.Repo for SquatchMail's tables
  otp_app: :my_app,
  prefix: "squatch_mail",    # the Postgres schema its tables live in
  retention_days: 90,        # how long footprints stay in the forest
  capture: [
    store_html_body: true,   # keep rendered HTML for the inspector preview
    store_text_body: true,
    sample_rate: 1.0         # 1.0 = every send is a Sighting
  ],
  guard: [
    complaint_rate_threshold: 0.001,  # 0.1% — SES's own suspension line
    auto_pause: true,
    min_volume: 1_000                 # floor so 5 sends + 1 complaint ≠ 20%
  ],
  pruner: [
    interval: :timer.hours(6)
  ]

The essentials

repo (required)

The Ecto.Repo SquatchMail reads and writes through. Its tables live in their own Postgres schema (see prefix), so they never collide with your application’s tables. Your database, its own quiet corner of the forest.

prefix

The Postgres schema name, "squatch_mail" by default. Every SquatchMail Ecto schema sets this prefix — nothing ever assumes public.

retention_days

How long emails and their footprints are kept before SquatchMail.Pruner sweeps them. Webhook audit logs are pruned on a fixed 30-day window regardless. The forest does not accumulate footprints forever; neither should your database.

Capture options

SquatchMail.Capture observes Swoosh telemetry. Its options control what evidence gets bagged:

  • store_html_body / store_text_body — whether rendered bodies are retained for the Sighting inspector’s preview tabs. Turn off if your emails contain things you’d rather not archive.
  • sample_rate — capture a fraction of sends instead of all of them. High-volume senders can drop to 0.1 and still get statistically honest rates. (The footprints are big enough; you don’t need every single one.)

Guard options

SquatchMail.Guard is the complaint-rate circuit breaker — see Guardrails for the philosophy:

  • complaint_rate_threshold — defaults to 0.001 (0.1%), which is SES’s own account-suspension threshold. The Guard trips before AWS does, because AWS is less polite about it.
  • auto_pause — whether tripping the breaker actually pauses sending or just glows ember-orange on the dashboard.
  • min_volume — minimum sends before the rate is taken seriously. Five sends and one complaint is not a 20% complaint rate; it’s a rounding error with anxiety.

Pruner options

  • interval — how often the retention sweep runs. Six hours by default. The Pruner is the campsite raccoon of the system: quiet, nocturnal, surprisingly thorough.

AWS credentials

Two modes for the SES/SNS provisioning calls:

  • credentials_mode: "ambient" (default) — credentials come from the environment: an IAM instance role, or env vars injected by your platform. No keys ever touch your database. Strongly preferred.
  • credentials_mode: "static" — keys stored on the sources table. Currently plaintext columns; encryption at rest is a known gap tracked in SquatchMail.Source. Until that lands, stay ambient.

Dev preview

Working on SquatchMail itself, or just want to poke the dashboard without wiring a real app?

iex -S mix dev

boots a minimal Phoenix endpoint at http://localhost:4000/squatch with its own auto-migrated squatch_mail_dev database. Send test mail through SquatchMailDev.Mailer and watch the capture pipeline do its thing.