broadcast-newsletter

name	broadcast-newsletter
description	End-to-end newsletter pipeline: investigate recent features, draft, send via API endpoint, and track delivery/open/click metrics.

Broadcast Newsletter Skill

End-to-end newsletter pipeline: investigate recent features, draft a newsletter, send it to all users via a backend API, and track delivery/open/click metrics.

When to Use

• User says "send a newsletter", "broadcast email", "email all users", "send an update"
• User asks to check broadcast stats, open rates, or click rates for a past newsletter

Pipeline Overview

Run stages in order, get user approval between stages.

---

Stage 1: Investigate Recent Features

1. Run git log --since="N days ago" --oneline --no-merges in the product repo
2. Read CHANGELOG.json for user-facing descriptions
3. Group commits into top-level features, ignore refactors/CI
4. Present top 3 features ranked by "wow factor" and ask which to focus on

Stage 2: Deep-Dive the Selected Feature

Use an Explore agent to read relevant source files. Understand how it works, what the user sees, key capabilities. Report back for alignment.

Stage 3: Draft the Newsletter

• Tone: Short, casual, founder-to-user. Not marketing-speak.
• Structure: Lead with main feature (1-2 paragraphs), bullet list of other changes, CTA, founder sign-off
• Length: ~150 words max

CTA Rules (non-negotiable)

Every newsletter MUST have at least one CLICKABLE CTA. Instructions like "open Settings > Remote Control" don't count: there's nothing to click, and the open-but-don't-click pattern will tank CTR. Use at least one of:

• A real deep link or URL users can tap right now (chat.fazm.ai, a fazm:// URL scheme, a specific landing page). The URL must be a complete clickable thing in the email, not "go to fazm.ai then click X".
• A 10-second starter prompt ("try this right now: open chat.fazm.ai on your phone, type 'summarize my last 3 emails'"). Removes "what would I even ask it" paralysis.
• Reply-as-CTA ("hit reply with X, I'll send you Y"). Replies are the strongest engagement signal you can get; they beat clicks and start a thread.

Bold the primary action with **...** so the eye lands on it. Never make the only link a generic "Download here" line, existing users don't need it and it's noise.

The May 12, 2026 send (47% open / 3% CTR) failed exactly here: the only link was "Download" and the feature CTA pointed to in-app menus with nothing to click. 250 people opened, 16 clicked.

Present the draft to the user for approval before proceeding.

---

Stage 4: Send the Newsletter

All broadcasts go through the production API endpoint. No scripts, no direct DB/Resend calls.

Endpoint: POST https://<your-dashboard-domain>/api/crm/broadcast Auth: Authorization: Bearer $CRON_SECRET

Dry run first (always)

curl -X POST https://<your-domain>/api/crm/broadcast \
  -H "Authorization: Bearer <CRON_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"product":"fazm","subject":"Your subject","body":"Body text...","dry_run":true}'

Response includes recipient_count, first 10 recipients, and a tracking block:

"tracking": {
  "html_body_length": 2876,
  "text_body_length": 1783,
  "will_track_opens_and_clicks": true
}

Always verify will_track_opens_and_clicks is true and html_body_length > 50 before showing the dry run to the user. If it's false, opens and clicks will silently record as zero (this is what happened to the May 5, 2026 "ChatGPT 5.5" broadcast: 516 sends, 0 tracked opens). The route will also hard-fail a real send if HTML can't be derived.

Test email to yourself

curl -X POST https://<your-domain>/api/crm/broadcast \
  -H "Authorization: Bearer <CRON_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"product":"fazm","subject":"Your subject","body":"Body text...","test_email":"[e-mail]"}'

Sends only to that address with [TEST] prefix. Bypasses unsubscribe check.

Real send (only after user confirms)

curl -X POST https://<your-domain>/api/crm/broadcast \
  -H "Authorization: Bearer <CRON_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"product":"fazm","subject":"Your subject","body":"Body text..."}'

Response: { success, total, sent, skipped, failed, errors }

skipped = unsubscribed or dedup-blocked (normal). failed = actual errors.

Embedding an image or GIF

The endpoint accepts an optional image_url field. The image is injected into the derived HTML between the lead paragraph and the rest of the body. Plain-text recipients see nothing (no inline image fallback), so don't put critical info in the visual.

curl -X POST https://<your-domain>/api/crm/broadcast \
  -H "Authorization: Bearer <CRON_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"product":"fazm","subject":"...","body":"...","image_url":"https://fazm.ai/agents.gif"}'

Hosting pattern: drop the file in ~/fazm-website/public/<filename> and push. It serves at https://fazm.ai/<filename> automatically via Vercel (e.g. agents.gif → https://fazm.ai/agents.gif). Verify with curl -I returning 200 before sending.

GIF sizing recipe (known-good for inbox preview without hurting deliverability):

• Target file size: 1-2 MB (3 MB is the ceiling)
• Width: ~260px for vertical/portrait source; ~480px for landscape
• Frame rate: 8 fps, loop length 5-8s
• Convert MP4 with: ffmpeg -i input.mp4 -vf "fps=8,scale=260:-1:flags=lanczos" -loop 0 output.gif
• Anything > 3 MB risks Gmail clipping the email and slow loads on mobile

After test send, open the email in Gmail web to verify the image actually loads. Gmail proxies images and occasionally blocks self-hosted GIFs on the first send to a domain.

What the API handles automatically

• Unsubscribe filtering: drops recipients who unsubscribed or whose address bounced/complained (handled inside sendEmail, before any Resend API call)
• Unsubscribe footer: auto-appends clickable "Unsubscribe" link to the HTML body and raw URL to the text body (appendUnsubscribeHtml / appendUnsubscribeText in src/lib/resend.ts)
• One-click unsubscribe headers: sets List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click on every send (required by Gmail/Yahoo bulk-sender rules)
• HTML auto-derivation: you pass plain text only; the API generates the HTML version via textToHtml() so open/click tracking pixels get inserted. If derivation produces empty HTML, the real send is rejected with a 400
• Dedup guard: skips if an outbound email was sent to the same address within the last 6 hours (counted as skipped, not failed)
• Persistence: every send is written to fazm_emails / assrt_emails with status transitions driven by Resend webhooks
• Rate limiting: 600ms between sends, plus a 3s pause every 10

---

Stage 5: Track Results

SELECT
  COUNT(*) as total_sent,
  COUNT(*) FILTER (WHERE status = 'delivered') as delivered,
  COUNT(*) FILTER (WHERE opened_at IS NOT NULL) as opened,
  COUNT(*) FILTER (WHERE clicked_at IS NOT NULL) as clicked
FROM fazm_emails
WHERE direction = 'outbound'
  AND subject = '<SUBJECT>'
  AND created_at > NOW() - INTERVAL '7 days';

Stats arrive via Resend webhooks. Check after 1h, 24h, and 48h.

Engagement Benchmarks

What "good" looks like for a Fazm-scale broadcast (~500 engaged Mac app users). Anything below the floor means something broke or the content failed.

Metric	Floor (something is wrong)	OK	Strong
Delivery rate	< 92%	92-97%	97%+
Open rate	< 35%	35-50%	50%+
CTR (of delivered)	< 3%	3-5%	5-10%+
Reply rate	n/a	any reply is a win	5+ replies

The metric that actually matters: clicks per send. Opens are vanity at this scale. 250 opens with 16 clicks (May 12, 2026 send) means you woke up 250 people and converted 16. That's the funnel leak. If clicks < 20 on a 500-person send, the CTA was structural, not vibes; revisit the Stage 3 CTA rules.

Transactional sends have different thresholds. The "Your Fazm download link" emails routinely hit 60%+ open and 50%+ CTR because users need that link. Don't compare a feature-update broadcast to a transactional send.

Downstream conversion is the only real KPI. Tie clicks to the PostHog distinct_id via fazm_workflow_users.posthog_distinct_id and check activation within 48h. A broadcast that drives 30 clicks and 0 activations is worse than one that drives 10 clicks and 5 activations.

---

Checklist

• Draft has at least one CLICKABLE CTA (URL, deep link, or reply-ask), bold-formatted
• Dry run shows correct recipient count, shown to user
• Dry-run tracking.will_track_opens_and_clicks is true and html_body_length > 50
• If using image_url: URL returns 200 via curl -I before send
• Test email sent and visually verified (open in Gmail web, confirm GIF loads if used)
• After test email lands, confirm the DB row has a non-null body_html (sanity check that tracking is wired)
• Content reviewed and approved
• User has explicitly confirmed "send it"

Known Failure Modes

• Plain-text-only sends → zero tracking. Resend's open pixel and click-rewrites only exist in HTML. If body_html is null or empty for the recipient row, opens and clicks will record as zero no matter what. The May 5, 2026 ChatGPT 5.5 broadcast hit this. The dry-run tracking block and the route's hard-fail guard exist to prevent a repeat.
• Webhook lag. Resend webhooks can take minutes to hours to update open/click stats. Don't panic at low open rates in the first hour after send; recheck at 1h, 24h, 48h.
• status column is the latest state, not a count. A row that moves sent → delivered → opened → clicked overwrites earlier statuses. For accurate rates, count via opened_at IS NOT NULL and clicked_at IS NOT NULL, not via status = 'opened'.