Skip to content

README.md

Latest commit

 

History

History
25 lines (18 loc) · 2.94 KB

README.md

File metadata and controls

25 lines (18 loc) · 2.94 KB
Raw

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 Beehiiv, Buttondown, Substack — what creators with 5k–100k subscribers actually use
02-marketing-platforms.md MailChimp, MailerLite, Kit — the SMB feature surface and data model
03-resend-native.md Resend's native API surface vs the gap this CLI must fill
04-deliverability-compliance.md Non-negotiables for safe scale operation, GDPR / CAN-SPAM / CASL, sender reputation
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, 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.