[pull] next from novuhq:next

.agents/skills/email-best-practices/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: email-best-practices
+description: Use when building email features, emails going to spam, high bounce rates, setting up SPF/DKIM/DMARC authentication, implementing email capture, ensuring compliance (CAN-SPAM, GDPR, CASL), handling webhooks, retry logic, or deciding transactional vs marketing.
+---
+
+# Email Best Practices
+
+Guidance for building deliverable, compliant, user-friendly emails.
+
+## Architecture Overview
+
+```
+[User] → [Email Form] → [Validation] → [Double Opt-In]
+                                              ↓
+                                    [Consent Recorded]
+                                              ↓
+[Suppression Check] ←──────────────[Ready to Send]
+        ↓
+[Idempotent Send + Retry] ──────→ [Email API]
+                                       ↓
+                              [Webhook Events]
+                                       ↓
+              ┌────────┬────────┬─────────────┐
+              ↓        ↓        ↓             ↓
+         Delivered  Bounced  Complained  Opened/Clicked
+                       ↓        ↓
+              [Suppression List Updated]
+                       ↓
+              [List Hygiene Jobs]
+```
+
+## Quick Reference
+
+| Need to... | See |
+|------------|-----|
+| Set up SPF/DKIM/DMARC, fix spam issues | [Deliverability](./resources/deliverability.md) |
+| Build password reset, OTP, confirmations | [Transactional Emails](./resources/transactional-emails.md) |
+| Plan which emails your app needs | [Transactional Email Catalog](./resources/transactional-email-catalog.md) |
+| Build newsletter signup, validate emails | [Email Capture](./resources/email-capture.md) |
+| Send newsletters, promotions | [Marketing Emails](./resources/marketing-emails.md) |
+| Ensure CAN-SPAM/GDPR/CASL compliance | [Compliance](./resources/compliance.md) |
+| Decide transactional vs marketing | [Email Types](./resources/email-types.md) |
+| Handle retries, idempotency, errors | [Sending Reliability](./resources/sending-reliability.md) |
+| Process delivery events, set up webhooks | [Webhooks & Events](./resources/webhooks-events.md) |
+| Manage bounces, complaints, suppression | [List Management](./resources/list-management.md) |
+
+## Start Here
+
+**New app?**
+Start with the [Catalog](./resources/transactional-email-catalog.md) to plan which emails your app needs (password reset, verification, etc.), then set up [Deliverability](./resources/deliverability.md) (DNS authentication) before sending your first email.
+
+**Spam issues?**
+Check [Deliverability](./resources/deliverability.md) first—authentication problems are the most common cause. Gmail/Yahoo reject unauthenticated emails.
+
+**Marketing emails?**
+Follow this path: [Email Capture](./resources/email-capture.md) (collect consent) → [Compliance](./resources/compliance.md) (legal requirements) → [Marketing Emails](./resources/marketing-emails.md) (best practices).
+
+**Production-ready sending?**
+Add reliability: [Sending Reliability](./resources/sending-reliability.md) (retry + idempotency) → [Webhooks & Events](./resources/webhooks-events.md) (track delivery) → [List Management](./resources/list-management.md) (handle bounces).

.agents/skills/email-best-practices/resources/branding.md

@@ -0,0 +1,5 @@
+# Email Branding
+
+## BIMI (Optional)
+
+Display brand logo in email clients. Requires DMARC `p=quarantine` or `p=reject`.

.agents/skills/email-best-practices/resources/compliance.md

@@ -0,0 +1,107 @@
+# Email Compliance
+
+Legal requirements for email by jurisdiction. **Not legal advice—consult an attorney for your specific situation.**
+
+## Quick Reference
+
+| Law | Region | Key Requirement | Penalty |
+|-----|--------|-----------------|---------|
+| CAN-SPAM | US | Opt-out mechanism, physical address | $53k/email |
+| GDPR | EU | Explicit opt-in consent | €20M or 4% revenue |
+| CASL | Canada | Express consent, opt-out mechanism | $1M (individual) to $10M (organization) CAD |
+
+## CAN-SPAM (United States)
+
+**Requirements:**
+- Accurate header info (From, To, Reply-To)
+- Non-deceptive subject lines
+- Physical mailing address in every email
+- Clear opt-out mechanism
+- Honor opt-out within 10 business days
+
+**Transactional emails:** Can send without opt-in if related to a transaction and not promotional.
+
+## GDPR (European Union)
+
+**Requirements:**
+- Explicit opt-in consent (not pre-checked boxes)
+- Consent must be freely given, specific, informed
+- Easy to withdraw consent (as easy as giving it)
+- Right to access data and deletion ("right to be forgotten")
+- Process unsubscribe immediately
+
+**Consent records:** Document who, when, how, and what they consented to.
+
+**Transactional emails:** Can send based on contract fulfillment or legitimate interest.
+
+## CASL (Canada)
+
+**Consent types:**
+- **Express consent:** Explicit opt-in (ideal)
+- **Implied consent:** Existing business relationship (2 years) or inquiry (6 months)
+
+**Requirements:**
+- Clear sender identification that will be valid for 60 days after send
+- Unsubscribe functional for 60 days after send
+- Process unsubscribe no later than 10 business days
+- Keep consent records 3 years after expiration
+
+## Other Regions
+
+| Region | Law | Key Points |
+|--------|-----|------------|
+| Australia | Spam Act 2003 | Consent required, honor unsubscribe within 5 days |
+| UK | PECR + GDPR | Same as GDPR |
+| Brazil | LGPD | Similar to GDPR, explicit consent for marketing |
+
+## Unsubscribe Requirements Summary
+
+| Law | Timing | Notes |
+|-----|--------|-------|
+| CAN-SPAM | 10 business days | Must work 30 days after send |
+| GDPR | Immediately | Must be as easy as opting in |
+| CASL | 10 business days | Must work 60 days after send |
+
+**Universal best practices:** Prominent link, one-click when possible, no login required, free, confirm action.
+
+## Managing preferences vs Unsubscribe from all
+
+Most legistlations require a one-click unsubscribe. `Managing preferences` is a nice-to-have and can lead to lower unsubscribe rate but doesn't replace `Unsubscribe`. If possible, offer both.
+
+## Consent Management
+
+**Record:**
+- Email address
+- Date/time of consent
+- Method (form, checkbox)
+- What they consented to
+- Source (which page/form)
+
+**Storage:** Database with timestamps, audit trail of changes, link to user account.
+
+## Data Retention
+
+| Law | Requirement |
+|-----|-------------|
+| GDPR | Keep only as long as necessary, delete when no longer needed |
+| CASL | Keep consent records 3 years after expiration |
+
+**Best practice:** Have clear retention policy, honor deletion requests promptly, review and clean regularly.
+
+## Privacy Policy Must Include
+
+- What data you collect
+- How you use data
+- Who you share data with
+- User rights (access, deletion)
+- How to contact about privacy
+
+## International Sending
+
+**Best practice:** Follow the most restrictive requirements (usually GDPR) to ensure compliance across all regions.
+
+## Related
+
+- [Email Capture](./email-capture.md) - Implement consent forms and double opt-in
+- [Marketing Emails](./marketing-emails.md) - Consent and unsubscribe requirements
+- [List Management](./list-management.md) - Handle unsubscribes and deletion requests

.agents/skills/email-best-practices/resources/deliverability.md

@@ -0,0 +1,117 @@
+# Email Deliverability
+
+Maximizing the chances that your emails are delivered successfully to the recipients.
+
+## Email Authentication
+
+**Required by Gmail/Yahoo/Microsoft** - unauthenticated emails will be rejected or spam-filtered.
+
+### SPF (Sender Policy Framework)
+
+Specifies which servers can send email for your domain.
+
+```
+v=spf1 include:amazonses.com ~all
+```
+
+- Add TXT record to DNS
+- Use `~all` (soft fail)
+
+### DKIM (DomainKeys Identified Mail)
+
+Cryptographic signature proving email authenticity.
+
+- Your email service will provide you with a TXT record
+
+### DMARC
+
+Policy for handling SPF/DKIM failures + reporting.
+
+```
+v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com
+```
+
+**Rollout:** `p=none` (monitor) → `p=quarantine; pct=25` → `p=reject`
+
+Learn more: https://resend.com/blog/dmarc-policy-modes 
+
+### Verify Your Setup
+
+Check DNS records directly:
+
+```bash
+# SPF record
+dig TXT yourdomain.com +short
+
+# DKIM record (replace 'resend' with your selector)
+dig TXT resend._domainkey.yourdomain.com +short
+
+# DMARC record
+dig TXT _dmarc.yourdomain.com +short
+```
+
+**Expected output:** Each command should return your configured record. No output = record missing.
+
+## Sender Reputation
+
+### IP Warming
+
+New IP/domain? Gradually increase volume:
+
+| Week | Daily Volume |
+|------|-------------|
+| 1 | 50-100 |
+| 2 | 200-500 |
+| 3 | 1,000-2,000 |
+| 4 | 5,000-10,000 |
+
+Start with engaged users. Send consistently. Don't rush.
+
+Learn more: https://resend.com/docs/knowledge-base/warming-up
+
+### Maintaining Reputation
+
+**Do:** Send to engaged users, keep bounce <4%, complaints <0.1%, remove inactive subscribers.
+
+**Don't:** Send to purchased lists, ignore bounces/complaints, send inconsistent volumes
+
+## Bounce Handling
+
+| Type | Cause | Action |
+|------|-------|--------|
+| Hard bounce | Permanent failure to deliver | Remove immediately |
+| Soft bounce | Transient failure to deliver | Retry: 1h → 4h → 24h, remove after 3-5 failures |
+
+**Targets:** <1% good, 1-3% acceptable, 3-4% concerning, >4% critical
+
+## Complaint Handling
+
+**Targets:** <0.01% excellent, 0.01-0.05% good, >0.05% critical
+
+**Reduce complaints:**
+- Only send to opted-in users
+- Make unsubscribe easy and immediate
+- Use clear sender names and "From" addresses
+
+**Feedback loops:** Set up with Gmail (Postmaster Tools), Yahoo, Microsoft SNDS. Remove complainers immediately.
+
+## Infrastructure
+
+**Dedicated sending domain:** Use different subdomains for different sending purposes (e.g., `t.yourdomain.com` for transactional emails and `m.yourdomain.com` for marketing emails). 
+
+**DNS TTL:** Low (300s) during setup, high (3600s+) after stable.
+
+## Troubleshooting
+
+**Emails going to spam?** Check in order:
+1. Authentication (SPF, DKIM, DMARC)
+2. Sender reputation (blacklists, complaint rates)
+3. Content
+4. Sending patterns (sudden volume spikes)
+
+**Diagnostic tools:** [Google Postmaster Tools](https://postmaster.google.com)
+
+## Related
+
+- [List Management](./list-management.md) - Handle bounces and complaints to protect reputation
+- [Sending Reliability](./sending-reliability.md) - Retry logic and error handling