# SquatchMail v0.1.0 - Table of Contents

> A self-hosted Amazon SES email dashboard for Phoenix apps, shipped as an embeddable Hex package.

## Pages

- [README](readme.md)
- [Changelog](changelog.md)
- [Security Policy](security.md)
- [SquatchMail — Research &amp; Architecture Recommendations](research.md)
- [SquatchMail feature inventory (derived from LaraSend source, 2026-07-08)](features.md)
- [SquatchMail Dashboard Design Spec](design.md)

## Modules

- [SquatchMail](SquatchMail.md): SquatchMail is a self-hosted Amazon SES email dashboard, shipped as an
embeddable Hex package for Phoenix applications.
- [SquatchMail.Adapters.Watchtower](SquatchMail.Adapters.Watchtower.md): An opt-in Swoosh adapter that enforces `SquatchMail.Guard`'s guardrails
ahead of a wrapped real adapter.
- [SquatchMail.Capture](SquatchMail.Capture.md): Observes every `Swoosh.Mailer.deliver/2` and `deliver_many/2` call in the
host application via `:telemetry`, with zero changes to the host's mailer
or adapter.
- [SquatchMail.Capture.Recorder](SquatchMail.Capture.Recorder.md): Persists captured emails off the process that sent them.
- [SquatchMail.Config](SquatchMail.Config.md): Reads SquatchMail's application configuration.
- [SquatchMail.Email](SquatchMail.Email.md): A captured or sent email and its lifecycle status.
- [SquatchMail.EmailAttachment](SquatchMail.EmailAttachment.md): Metadata about an attachment on an email.
- [SquatchMail.EmailEvent](SquatchMail.EmailEvent.md): A downstream event observed for an email (delivery, open, click, bounce, etc.).
- [SquatchMail.EmailRecipient](SquatchMail.EmailRecipient.md): A normalized recipient of an email (a to/cc/bcc address).
- [SquatchMail.Guard](SquatchMail.Guard.md): Pre-send guardrails: suppression enforcement and the complaint-rate
auto-pause.
- [SquatchMail.Migrations](SquatchMail.Migrations.md): Versioned migrations for SquatchMail's database tables.
- [SquatchMail.Pruner](SquatchMail.Pruner.md): Periodically prunes data older than the configured retention window.
- [SquatchMail.PublicId](SquatchMail.PublicId.md): Generates prefixed, URL-safe public identifiers backed by random bytes.
- [SquatchMail.SES](SquatchMail.SES.md): Amazon SES v2 / SNS integration for SquatchMail.
- [SquatchMail.SNS.MessageVerifier](SquatchMail.SNS.MessageVerifier.md): Hand-written verification of Amazon SNS message signatures.
- [SquatchMail.SNS.Processor](SquatchMail.SNS.Processor.md): Orchestrates inbound SNS webhook delivery: token auth, signature
verification, SES event normalization, persistence, and suppression rules.
- [SquatchMail.SNS.RawBodyReader](SquatchMail.SNS.RawBodyReader.md): A `Plug.Parsers` body reader that caches the raw request body in
`conn.assigns[:raw_body]` before returning it for JSON parsing.
- [SquatchMail.Source](SquatchMail.Source.md): The (single-row) SES connection configuration.
- [SquatchMail.Suppression](SquatchMail.Suppression.md): An address that should not be sent to.
- [SquatchMail.Tracker](SquatchMail.Tracker.md): The persistence context for SquatchMail's observability data.
- [SquatchMail.Web.ActivityExportController](SquatchMail.Web.ActivityExportController.md): Streams the Trail Log's current filter set as a CSV download —
`GET <dashboard_path>/activity/export.csv`.
- [SquatchMail.Web.AssetController](SquatchMail.Web.AssetController.md): Serves SquatchMail's self-contained CSS/JS bundle (plus the logo PNG) with
content-hashed, immutable-cached paths.
- [SquatchMail.Web.Components](SquatchMail.Web.Components.md): Shared design-system components for SquatchMail dashboard pages: badges,
stat cards, the live indicator, and empty states. Every visual rule here
traces back to a rule in `DESIGN.md` — see that file before changing colors,
radii, or copy.

- [SquatchMail.Web.Components.Icons](SquatchMail.Web.Components.Icons.md): The SquatchMail footprint mark and small outlined nav icons.
- [SquatchMail.Web.Layouts](SquatchMail.Web.Layouts.md): Root and app layouts for the SquatchMail dashboard.
- [SquatchMail.Web.Live.BaseCamp](SquatchMail.Web.Live.BaseCamp.md): Base Camp — `GET <dashboard_path>/base-camp`, the SES connection/setup page.
- [SquatchMail.Web.Live.Sighting](SquatchMail.Web.Live.Sighting.md): The Sighting inspector — `GET <dashboard_path>/sightings/:public_id`.
- [SquatchMail.Web.Live.Suppressions](SquatchMail.Web.Live.Suppressions.md): The Do-Not-Disturb registry — `GET <dashboard_path>/suppressions`.
- [SquatchMail.Web.Live.TrailLog](SquatchMail.Web.Live.TrailLog.md): The Trail Log — SquatchMail's default landing page (`squatch_mail_dashboard`
mounted at `/`), showing the live activity feed: stat strip, filters, and
the sent-email activity table.
- [SquatchMail.Web.OnMount](SquatchMail.Web.OnMount.md): The default `on_mount` hook and `live_session` session builder for the
SquatchMail dashboard.
- [SquatchMail.Web.Plugs.Auth](SquatchMail.Web.Plugs.Auth.md): Enforces layers (b) and (c) of `SquatchMail.Web.Router`'s security model.
- [SquatchMail.Web.Router](SquatchMail.Web.Router.md): Mounts the SquatchMail dashboard in a host Phoenix router.
- [SquatchMail.Web.WebhookController](SquatchMail.Web.WebhookController.md): Receives inbound Amazon SNS/SES event notifications at
`POST <dashboard_path>/webhooks/sns/:token`.
- [SquatchMail.WebhookLog](SquatchMail.WebhookLog.md): A raw audit record of an inbound webhook payload (typically SNS/SES).

## Mix Tasks

- [mix squatch_mail.copy_css](Mix.Tasks.SquatchMail.CopyCss.md): Builds `priv/static/squatch_mail.css` by concatenating
`assets/css/fonts.css` (the base64-embedded Bebas Neue / Space Mono
`@font-face` rules) with the hand-written `assets/css/squatch_mail.css`.
- [mix squatch_mail.install](Mix.Tasks.SquatchMail.Install.md): Install and configure SquatchMail for use in this application.

