Resend Contacts and Segments — who gets the Broadcast

How this differs from sibling playbooks

This page owns who is on the list. Resend bilingual newsletter owns domain, signup copy, and the Dashboard-first path. Resend Broadcast drafts owns the draft and the STOP before Send. This page does not create or send a Broadcast.

Who it’s for / not for

Stack (spine only)

Secondary (later): Contact properties API, Contact imports, Automations “Add to Segment”, MCP / CLI deep-dive, suppression list ops.

• Global Contacts — one email = one Contact across the team (Contacts intro)
• Segments API — internal groups; Contacts never see Segment names (manage Segments). POST /segments create, GET /segments list, PATCH /segments/:id rename, DELETE /segments/:id delete, GET /segments/:id/contacts list members
• Contacts API — POST /contacts create; POST /contacts/:id|email/segments/:segmentId add; DELETE the same path to remove
• Topics (mention only) — recipient-facing prefs; pair with Segments when you Send
• Audiences API — deprecated; still works for now and will be removed. Prefer Segments (create Audience, migration)

Bot vs human

Numbered steps

1. Prerequisites. Verified sending domain and an API key in env you control (docs). Signup and consent language come from Resend bilingual newsletter. Human must verify DNS, that the key is not in the repo, and that you are not building a cold-email list.
2. Mental model (Nov 2025+ Global Contacts) (migration). Before: the same email in two Audiences was two Contact objects. Now: a Contact is global; a Segment is an internal group; a Contact can be in zero, one, or many Segments. A Topic is what kind of mail (user prefs); a Segment is who you intend to target. A Contact must be in a Segment to receive a Broadcast. If unsubscribed: true or on the Suppression List, Resend will not send even if Segment membership exists.
3. Create a Segment. POST https://api.resend.com/segments with { "name": "…" } (create-segment). Names you can change: playbook-subscribers (main list) and playbook-preview (you and testers). The response returns id and name. Sketch — do not run with a live key in chat: resend.segments.create({ name: 'playbook-subscribers' }). data.id is the segment_id for a later Broadcast draft.
4. List / rename / delete. List: GET /segments. Rename: PATCH /segments/:id with a new name. Delete: DELETE /segments/:id — does not delete Contacts; it only removes Segment membership. Human must verify before delete if any scheduled Broadcast still targets that Segment.
5. Create Contacts (opt-in only). POST /contacts with at least email; optional first_name, last_name, unsubscribed, segments, and topic subscriptions (create-contact). STOP: only add addresses that actively opted in (consent KB). Pre-checked ToS clauses and assumed opt-in are not valid permission per that guide. Sketch: resend.contacts.create({ email, firstName, unsubscribed: false }).
6. Add / remove Contact ↔ Segment. Resend says you do not need separate consent to move someone between Segments once they are a Contact — you still needed consent to email them at all. For this hub, only Segment people who opted into the newsletter. Add: POST /contacts/:contactId/segments/:segmentId or the email form of that path. Remove: DELETE the same path. List members: GET /segments/:segmentId/contacts. You can list members for a check; you confirm before a Broadcast.
7. Hand off to the Broadcast human-gate. Pass the verified segment_id into Resend Broadcast drafts with send omitted or false. Optional topic_id so prefs are respected. This playbook does not create or send Broadcasts.
8. If you still have Audiences code. Those endpoints are deprecated. Migrate to Segments and global Contacts. Prefer Topics for unsubscribe granularity; keep Segments for internal targeting.

Failure modes / HK caveats

• Spam / purchased lists — STOP. High complaint rates can pause accounts. Not PDPO legal advice.
• Secrets in chat/git — any re_ key in markdown or agent logs → rotate. Env only.
• Wrong Segment on a Broadcast — preview vs full list. List contacts and check the Dashboard count first.
• Audiences vs Segments drift — new work uses /segments only.
• Delete Segment ≠ delete people — Contacts remain.
• Global unsubscribe / suppression — adding to a Segment does not override unsubscribed or the Suppression List.
• Bot must not Send.
• Keep Contact properties to what the person opted into.

Newsletter CTA

The path: opt-in, then a Segment, then a Broadcast draft, then you send.

Human must verify

1. Consent wording on signup (unchecked, specific) and a privacy notice for HK readers.
2. API key storage (env only); no keys in chat, queue markdown, or git.
3. Segment naming, and which Segment is preview vs live subscribers.
4. Every Contact added via an agent came from a real opt-in source you can point to.
5. Dashboard count matches GET /segments/:id/contacts before the first Broadcast.
6. Topics strategy (if any) aligned with unsubscribe prefs.
7. No Audiences-only code left on the production signup path.
8. You press Send on a Broadcast (other playbook).
9. PDPO / retention: not certified here — escalate if you collect more than email and name.

Doc gaps

Exact contact quotas and plan limits are not frozen here (check Billing). Contact Import API and Automations “Add to Segment” are not stepped. The MCP/CLI matrix is deferred. HK PDPO is outside Resend docs — confirm with counsel if you need to. Not legal advice.

Docs cited

• Contacts introduction · 2026-10-16
• Managing Segments · 2026-10-16
• Migrating from Audiences to Segments · 2026-10-16
• Create Segment · 2026-10-16
• Create Contact · 2026-10-16
• Add Contact to a Segment · 2026-10-16
• Create Audience (deprecated) · 2026-10-16
• What counts as email consent? · 2026-10-16

Related playbooks

• Resend bilingual newsletter
• HK PDPO newsletter consent
• Resend Broadcast drafts
• Cancel or duplicate a Broadcast