| name | lifecycle-messaging |
| description | Email/SMS lifecycle and deliverability framework for SMB Product-Builder products that send transactional or lifecycle messages (booking reminders, CRM sequences, receipts, win-back). Codifies provider selection (Resend/Postmark/Twilio/SendGrid), domain auth (SPF/DKIM/DMARC), consent and compliance (TCPA, CAN-SPAM, CASL, quiet hours, double opt-in), suppression-list discipline, and the transactional-vs-marketing split. Applied by integrations-engineer and senior-dev whenever a feature sends messages — so deliverability and consent are designed in, not bolted on after the first spam complaint. |
| when_to_use | Apply when a feature sends email or SMS:
- integrations-engineer designing a Twilio / email-provider integration
- senior-dev implementing booking reminders, CRM sequences, receipts, or win-back
- architect deciding the messaging provider + domain-auth setup for a crm/booking product
Do NOT apply for purely in-app notifications with no email/SMS leg.
|
| effort | medium |
| allowed-tools | Read, Write, Grep, Glob, WebFetch |
| paths | ["docs/integrations/**","docs/architecture/**"] |
Lifecycle messaging — deliverable, consented, compliant
Messages that don't arrive (poor deliverability) or that arrive without consent (TCPA/
CAN-SPAM violations) are both fatal for an SMB product. This skill makes both correct by
construction. Design the consent + deliverability posture before the first send.
1. Transactional vs marketing — split them
Decide per message which bucket it is; they have different rules and should use different
sending identities (often different subdomains / providers):
| Transactional | Marketing / lifecycle |
|---|
| Examples | receipt, booking confirm/reminder, password reset | win-back, promo, newsletter, nurture step |
| Consent | implied by the transaction | explicit opt-in required |
| Unsubscribe | not required (but honor STOP) | required, one-click, honored fast |
| Sending domain | txn. subdomain | mail./news. subdomain |
Never send marketing content on the transactional channel "because it delivers better" —
that's how the transactional domain gets burned.
2. Provider selection (pick one, justify it)
- Email — Postmark (best transactional deliverability, strict on marketing), Resend
(DX-first, good default), SendGrid (scale). Default: Resend for transactional,
add a marketing-grade ESP only when lifecycle volume justifies it.
- SMS — Twilio (messaging service + sender pool), or Telnyx. Use a Messaging Service,
not a single number, for scale + failover. A2P 10DLC registration is required for
US application-to-person SMS — register the brand/campaign before sending.
3. Domain authentication (non-negotiable for email)
- SPF — sender IP authorized in DNS.
- DKIM — provider signing key published; messages signed.
- DMARC — start
p=none with rua reporting, ramp to p=quarantine→p=reject once
aligned. Without DMARC alignment, lifecycle mail lands in spam.
- Warm up a new sending domain gradually; never blast from a cold domain.
4. Consent + compliance (US-first)
- CAN-SPAM (email) — valid physical postal address, accurate From/Subject, working
one-click unsubscribe honored within 10 days.
