# Research Dossiers

Five focused research reports informing the `mailing-list-cli` design. Each was generated by a parallel research agent investigating a specific dimension of the problem.

| File | Topic |
|---|---|
| [01-modern-creator-newsletters.md](./01-modern-creator-newsletters.md) | Beehiiv, Buttondown, Substack — what creators with 5k–100k subscribers actually use |
| [02-marketing-platforms.md](./02-marketing-platforms.md) | MailChimp, MailerLite, Kit — the SMB feature surface and data model |
| [03-resend-native.md](./03-resend-native.md) | Resend's native API surface vs the gap this CLI must fill |
| [04-deliverability-compliance.md](./04-deliverability-compliance.md) | Non-negotiables for safe scale operation, GDPR / CAN-SPAM / CASL, sender reputation |
| [05-templates.md](./05-templates.md) | Template format choice, merge tag syntax, agent authoring guidelines |

These dossiers feed into the design spec (next step) and ultimately the implementation plan.

## Top-line findings

- **The 80/20 of a mailing list collapses to ~8 commands**: compose+send, contact CRUD/import, tags+segments, send-to-segment, subject A/B, per-campaign analytics, automatic suppression, basic welcome drip. Everything else is differentiator.
- **Resend already provides** Broadcasts, Audiences, Contacts, Topics, Templates, hosted unsubscribe, open/click tracking, and an 11-event webhook stream including bounce subtypes. We lean on these — but indirectly, through [`email-cli`](https://github.com/paperfoot/email-cli), which is the sole Resend API client. `mailing-list-cli` never opens an HTTP connection to Resend.
- **Resend does not provide** bulk CSV import via API, programmatic suppression list access, double opt-in workflow, A/B testing, engagement-based segmentation, in-flight broadcast pause/resume, or geo/device enrichment. These are exactly the gaps `mailing-list-cli` fills.
- **Twelve compliance features are non-negotiable** for safe operation at 10k+ subscribers, including a global suppression list enforced at dispatch time, RFC 8058 one-click unsubscribe, double opt-in by default, GDPR erasure, and CAN-SPAM physical address injection.
- **For templates, the right pick is MJML compiled in-process via the `mrml` Rust crate**, with Handlebars-style `{{ snake_case }}` merge tags. No Node dependency, no external runtime, and the format an LLM can author most reliably.

## Architecture note

The original architectural plan called for `mailing-list-cli` to wrap Resend's API directly. After more thought, the cleaner split is for `mailing-list-cli` to shell out to `email-cli` for every Resend touchpoint. This keeps `email-cli` as the only binary with Resend credentials and rate-limit handling, and lets `mailing-list-cli` stay focused on the orchestration / segmentation / suppression / template / analytics layer that no transactional email tool covers. The five research dossiers below remain valid — what changes is the implementation channel, not the feature set.
