vybekiit 0.7.4 → 0.7.7

package/dist/global-skills/email-best-practices/references/deliverability.md

@@ -0,0 +1,121 @@
+# 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@example.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 example.com +short
+
+# DKIM record (replace 'resend' with your selector)
+dig TXT resend._domainkey.example.com +short
+
+# DMARC record
+dig TXT _dmarc.example.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.example.com` for transactional emails and `m.example.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. List-Unsubscribe header — required by Gmail/Yahoo since Feb 2024 (see [Compliance](./compliance.md))
+3. Sender reputation (blacklists, complaint rates)
+4. Content
+5. Sending patterns (sudden volume spikes)
+
+**Diagnostic tools:**
+- [Google Postmaster Tools](https://postmaster.google.com) - Domain reputation and spam rates
+- [mail-tester.com](https://www.mail-tester.com) - Send a test email, get deliverability score
+- [MXToolbox](https://mxtoolbox.com/blacklists.aspx) - Check blacklist status
+
+## Related
+
+- [List Management](./list-management.md) - Handle bounces and complaints to protect reputation
+- [Sending Reliability](./sending-reliability.md) - Retry logic and error handling

package/dist/global-skills/email-best-practices/references/email-capture.md

@@ -0,0 +1,129 @@
+# Email Capture Best Practices
+
+Collecting email addresses responsibly with validation, verification, and proper consent.
+
+## Email Validation
+
+### Client-Side
+
+**HTML5:**
+```html
+<input type="email" required>
+```
+
+**Best practices:**
+- Validate on blur or with short debounce
+- Show clear error messages
+- Don't be too strict (allow unusual but valid formats)
+- Client-side validation ≠ deliverability
+
+### Server-Side (Recommended)
+
+Always validate server-side—client-side can be bypassed.
+
+**Check:**
+- Email format (RFC 5322)
+- Domain exists (DNS lookup)
+- Domain has MX records
+- Optionally: disposable email detection
+
+Recommended tools: https://resend.com/blog/best-email-verification-apis
+
+## Double opt-in
+
+Confirms address belongs to user and is deliverable.
+
+### Process
+
+1. User submits email
+2. Send verification email with unique link/token
+3. User clicks link
+4. Mark as verified
+5. Allow access/add to list
+
+**Timing:** Send immediately, include expiration (24-48 hours), allow resend after 60 seconds, limit resend attempts (3/hour).
+
+### Single vs Double Opt-In
+
+| | Single Opt-In | Double Opt-In |
+|--|---------------|---------------|
+| **Process** | Add to list immediately | Require email confirmation first |
+| **Pros** | Lower friction, faster growth | Verified addresses, better engagement, meets GDPR/CASL |
+| **Cons** | Higher invalid rate, lower engagement | Some users don't confirm |
+| **Use for** | Account creation, transactional | Marketing lists, newsletters |
+
+**Recommendation:** Double opt-in for all marketing emails.
+
+## Form Design
+
+### Email Input
+
+- Use `type="email"` for mobile keyboard
+- Include placeholder ("you@example.com")
+- Clear error messages ("Please enter a valid email address" not "Invalid")
+
+### Consent Checkboxes (Marketing)
+
+- **Unchecked by default** (required)
+- Specific language about what they're signing up for
+- Separate checkboxes for different email types
+- Link to privacy policy
+
+```
+☐ Subscribe to our weekly newsletter with product updates
+☐ Send me promotional offers and deals
+```
+
+**Don't:** Pre-check boxes, use vague language, hide in terms.
+
+### Form Layout
+
+- Keep simple and focused
+- One primary action
+- Clear value proposition
+- Mobile-friendly
+- Accessible (labels, ARIA)
+
+## Error Handling
+
+### Invalid Email
+
+- Show clear error message
+- Suggest corrections for common typos (@gmial.com → @gmail.com)
+- Allow user to fix and resubmit
+
+### Already Registered
+
+- Accounts: "This email is already registered. [Sign in]"
+- Marketing: "You're already subscribed! [Manage preferences]"
+- Don't reveal if account exists (security)
+
+### Rate Limiting
+
+- Limit verification emails (3/hour per email)
+- Rate limit form submissions
+- Use CAPTCHA sparingly if needed
+- Monitor for abuse patterns
+
+## Verification Emails
+
+**Content:**
+- Clear purpose ("Verify your email address")
+- Prominent verification button
+- Expiration time
+- Resend option
+- "I didn't request this" notice
+- Don't include OTP/2FA codes in subject line or preview text as it discourages opens
+
+**Design:**
+- Mobile-friendly
+- Large, tappable button
+- Clear call-to-action
+
+See [Transactional Emails](./transactional-emails.md) for detailed email design guidance.
+
+## Related
+
+- [Compliance](./compliance.md) - Legal requirements for consent (GDPR, CASL)
+- [Marketing Emails](./marketing-emails.md) - What happens after capture
+- [Deliverability](./deliverability.md) - How validation improves sender reputation

package/dist/global-skills/email-best-practices/references/email-types.md

@@ -0,0 +1,173 @@
+# Email Types: Transactional vs Marketing
+
+Understanding the difference between transactional and marketing emails is crucial for compliance, deliverability, and user experience. This guide explains the distinctions and provides a catalog of transactional emails your app should include.
+
+## When to Use This
+
+- Deciding whether an email should be transactional or marketing
+- Understanding legal distinctions between email types
+- Planning what transactional emails your app needs
+- Ensuring compliance with email regulations
+- Setting up separate sending infrastructure
+
+## Transactional vs Marketing: Key Differences
+
+### Transactional Emails
+
+**Definition:** Emails that facilitate or confirm a transaction the user initiated or expects. They're directly related to an action the user took or are legal notices you're required to serve.
+
+**Characteristics:**
+- User-initiated or expected
+- Time-sensitive and actionable
+- Required for the user to complete an action
+- Does not include promotional material or offers
+- Can be sent without explicit opt-in (with limitations)
+
+**Examples:**
+- Password reset links
+- Order confirmations
+- Account verification
+- OTP/2FA codes
+- Shipping notifications
+
+**Analogy:**
+Think of transactional emails for everything that would leave you with a paper receipt in the real world: invoices, parking ticket, booking confirmation, etc.
+
+### Marketing Emails
+
+**Definition:** Emails sent for promotional, advertising, or informational purposes that are not directly related to a specific transaction or legal requirement.
+
+**Characteristics:**
+- Promotional or informational content
+- Not time-sensitive to complete a transaction
+- Require explicit opt-in (consent)
+- Must include unsubscribe options
+- Subject to stricter compliance requirements
+
+**Examples:**
+- Newsletters
+- Abandoned cart
+- Product announcements
+- Promotional offers
+- Company updates
+- Educational content
+
+## Legal Distinctions
+
+### CAN-SPAM Act (US)
+
+**Transactional emails:**
+- Can be sent without opt-in
+- Must be related to a transaction
+- Cannot contain promotional content (with exceptions)
+- Must identify sender and provide contact information
+
+**Marketing emails:**
+- Require opt-out mechanism (not opt-in in US)
+- Must include clear sender identification
+- Must include physical mailing address
+- Must honor opt-out requests within 10 business days
+
+### GDPR (EU)
+
+**Transactional emails:**
+- Can be sent based on legitimate interest or contract fulfillment
+- Must be necessary for service delivery
+- Cannot contain marketing content without consent
+
+**Marketing emails:**
+- Require explicit opt-in consent
+- Must clearly state purpose of data collection
+- Must provide easy unsubscribe
+- Subject to data protection requirements
+
+### CASL (Canada)
+
+**Transactional emails:**
+- Can be sent without consent if related to ongoing business relationship
+- Must be factual and not promotional
+
+**Marketing emails:**
+- Require express or implied consent
+- Must include unsubscribe mechanism
+- Must identify sender clearly
+
+## When to Use Each Type
+
+### Use Transactional When:
+
+- User needs the email to complete an action
+- Email confirms a transaction or account change
+- Email provides security-related information
+- Email is expected based on user action
+- Content is time-sensitive and actionable
+- You're required to serve a notification for compliance
+
+### Use Marketing When:
+
+- Promoting products or services
+- Sending newsletters or updates
+- Sharing educational content
+- Announcing features or company news
+- Content is not required for a transaction
+
+## Hybrid Emails: The Gray Area
+
+Some emails mix transactional and marketing content. This isn't best practice and should be avoided.
+
+**Best practice:** Keep transactional and marketing separate. 
+
+**Example of problematic hybrid:**
+- Newsletter (marketing) with a small order status update (transactional)
+
+## Transactional Email Catalog
+
+For a complete catalog of transactional emails and recommended combinations by app type, see [Transactional Email Catalog](./transactional-email-catalog.md).
+
+**Quick reference - Essential emails for most apps:**
+1. **Email verification** - Required for account creation
+2. **Password reset** - Required for account recovery
+3. **Welcome email** - Good user experience
+
+The catalog includes detailed guidance for:
+- Authentication-focused apps
+- Newsletter / content platforms
+- E-commerce / marketplaces
+- SaaS / subscription services
+- Financial / fintech apps
+- Social / community platforms
+- Developer tools / API platforms
+- Healthcare / HIPAA-compliant apps
+
+## Sending Infrastructure
+
+### Separate subdomains
+
+**Best practice:** Use separate sending subdomains for transactional and marketing emails.
+
+**Benefits:**
+- Protect transactional deliverability
+- Different authentication domains
+- Independent reputation
+- Easier compliance management
+
+**Implementation:**
+- Use different subdomains (e.g., `t.example.com` for transactional, `m.example.com` for marketing)
+
+### Email Service Considerations
+
+Choose an email service that:
+- Provides reliable delivery for transactional emails
+- Offers separate sending domains
+- Has good API for programmatic sending
+- Provides webhooks for delivery events
+- Supports authentication setup (SPF, DKIM, DMARC)
+
+Services like Resend are designed for transactional emails and provide the infrastructure and tools needed for reliable delivery. They also offer powerful marketing features.
+
+## Related Topics
+
+- [Transactional Emails](./transactional-emails.md) - Best practices for sending transactional emails
+- [Marketing Emails](./marketing-emails.md) - Best practices for marketing emails
+- [Compliance](./compliance.md) - Legal requirements for each email type
+- [Deliverability](./deliverability.md) - Ensuring transactional emails are delivered

package/dist/global-skills/email-best-practices/references/list-management.md

@@ -0,0 +1,157 @@
+# List Management
+
+Maintaining clean email lists through suppression, hygiene, and data retention.
+
+## Suppression Lists
+
+A suppression list prevents sending to addresses that should never receive email.
+
+### What to Suppress
+
+| Reason | Action | Can Unsuppress? |
+|--------|--------|-----------------|
+| Hard bounce | Add immediately | No (address invalid) |
+| Complaint (spam) | Add immediately | No (legal requirement) |
+| Soft bounce (3x) | Add after threshold | Yes, after 30-90 days |
+| Manual removal | Add on request | Only if user requests |
+
+### Implementation
+
+```typescript
+// Suppression list schema
+interface SuppressionEntry {
+  email: string;
+  reason: 'hard_bounce' | 'complaint' | 'unsubscribe' | 'soft_bounce' | 'manual';
+  created_at: Date;
+  source_email_id?: string; // Which email triggered this
+}
+
+// Check before every send
+async function canSendTo(email: string): Promise<boolean> {
+  const suppressed = await db.suppressions.findOne({ email });
+  return !suppressed;
+}
+
+// Add to suppression list
+async function suppressEmail(email: string, reason: string, sourceId?: string) {
+  await db.suppressions.upsert({
+    email: email.toLowerCase(),
+    reason,
+    created_at: new Date(),
+    source_email_id: sourceId,
+  });
+}
+```
+
+### Pre-Send Check
+
+**Always check suppression before sending:**
+
+```typescript
+async function sendEmail(to: string, emailData: EmailData) {
+  if (!await canSendTo(to)) {
+    console.log(`Skipping suppressed email: ${to}`);
+    return { skipped: true, reason: 'suppressed' };
+  }
+
+  return await resend.emails.send({ to, ...emailData });
+}
+```
+
+## List Hygiene
+
+Regular maintenance to keep lists healthy.
+
+### Automated Cleanup
+
+| Task | Frequency | Action |
+|------|-----------|--------|
+| Remove hard bounces | Real-time (via webhook) | Immediate suppression |
+| Remove complaints | Real-time (via webhook) | Immediate suppression |
+| Process unsubscribes | Real-time | Remove from marketing lists |
+| Review soft bounces | Daily | Suppress after 3 failures |
+| Remove inactive | Monthly | Re-engagement → remove |
+
+Learn more: https://resend.com/docs/knowledge-base/audience-hygiene
+
+### Re-engagement Campaigns
+
+Before removing inactive subscribers:
+
+1. **Identify inactive:** No opens/clicks in 45-90 days
+2. **Send re-engagement:** "We miss you" or "Still interested?"
+3. **Wait 14-30 days** for response
+4. **Remove non-responders** from active lists
+
+```typescript
+async function runReengagement() {
+  const inactive = await getInactiveSubscribers(90); // 90 days
+
+  for (const subscriber of inactive) {
+    if (!subscriber.reengagement_sent) {
+      await sendReengagementEmail(subscriber);
+      await markReengagementSent(subscriber.email);
+    } else if (daysSince(subscriber.reengagement_sent) > 30) {
+      await removeFromMarketingLists(subscriber.email);
+    }
+  }
+}
+```
+
+## Data Retention
+
+### Email Logs
+
+| Data Type | Recommended Retention | Notes |
+|-----------|----------------------|-------|
+| Send attempts | 90 days | Debugging, analytics |
+| Delivery status | 90 days | Compliance, reporting |
+| Bounce/complaint events | 3 years | Required for CASL |
+| Suppression list | Indefinite | Never delete |
+| Email content | 30 days | Storage costs |
+| Consent records | 3 years after expiry | Legal requirement |
+
+### Retention Policy Implementation
+
+```typescript
+// Daily cleanup job
+async function cleanupOldData() {
+  const now = new Date();
+
+  // Delete old email logs (keep 90 days)
+  await db.emailLogs.deleteMany({
+    created_at: { $lt: subDays(now, 90) }
+  });
+
+  // Delete old email content (keep 30 days)
+  await db.emailContent.deleteMany({
+    created_at: { $lt: subDays(now, 30) }
+  });
+
+  // Never delete: suppressions, consent records
+}
+```
+
+## Metrics to Monitor
+
+| Metric | Target | Alert Threshold |
+|--------|--------|-----------------|
+| Bounce rate | <2% | >2% |
+| Complaint rate | <0.05% | >0.05% |
+| Suppression list growth | Stable | Sudden spike |
+
+## Transactional vs Marketing Lists
+
+**Keep separate:**
+- Transactional: Can send to anyone with account relationship
+- Marketing: Only opted-in subscribers
+
+**Suppression applies to both:** Hard bounces and complaints suppress across all email types.
+
+**Unsubscribe is marketing-only:** User unsubscribing from marketing can still receive transactional emails (password resets, order confirmations).
+
+## Related
+
+- [Webhooks & Events](./webhooks-events.md) - Receive bounce/complaint notifications
+- [Deliverability](./deliverability.md) - How list hygiene affects sender reputation
+- [Compliance](./compliance.md) - Legal requirements for data retention

package/dist/global-skills/email-best-practices/references/marketing-emails.md

@@ -0,0 +1,115 @@
+# Marketing Email Best Practices
+
+Promotional emails that require explicit consent and provide value to recipients.
+
+## Core Principles
+
+1. **Consent first** - Explicit opt-in required (especially GDPR/CASL)
+2. **Value-driven** - Provide useful content, not just promotions
+3. **Respect preferences** - Let users control frequency and content types
+
+## Opt-In Requirements
+
+### Explicit Opt-In
+
+**What counts:**
+- User checks unchecked box
+- User clicks "Subscribe" button
+- User completes form with clear subscription intent
+
+**What doesn't count:**
+- Pre-checked boxes
+- Opt-out model
+- Assumed consent from purchase
+- Purchased/rented lists
+
+### Informed Consent
+
+Disclose: email types, frequency, sender identity, how to unsubscribe.
+
+✅ "Subscribe to our weekly newsletter with product updates and tips"
+❌ "Sign up for emails"
+
+### Double Opt-In (Recommended)
+
+1. User submits email
+2. Send confirmation email with verification link
+3. User clicks to confirm
+4. Add to list only after confirmation
+
+Benefits: Verifies deliverability, confirms intent, reduces complaints, required in some regions (Germany).
+
+## Unsubscribe Requirements
+
+**Must be:**
+- Prominent in every email
+- One-click (preferred)
+- Immediate (GDPR) or within 10 days (CAN-SPAM) (immediate preferred)
+- Free, no login required
+
+**Preference center options:** Frequency (daily/weekly/monthly), content types, complete unsubscribe.
+
+## Content and Design
+
+### Subject Lines
+
+- Clear and specific (50 chars or less for mobile)
+- Create curiosity without misleading
+- A/B test regularly
+
+✅ "Your weekly digest: 5 productivity tips"
+❌ "You won't believe what happened!"
+
+### Structure
+
+**Above fold:** Value proposition, primary CTA, engaging visual
+
+**Body:** Scannable (short paragraphs, bullets), clear hierarchy, multiple CTAs
+
+**Footer:** Unsubscribe link, company info, physical address (CAN-SPAM), social links
+
+### Mobile-First
+
+- Single column layout
+- 44x44px minimum buttons
+- 16px minimum text
+- Test on iOS, Android, dark mode
+
+## Segmentation
+
+**Segment by:** Behavior (purchases, activity), demographics, preferences, engagement level, signup source.
+
+Benefits: Higher open/click rates, lower unsubscribes, better experience.
+
+## Personalization
+
+**Options:** Name in subject/greeting, location-specific content, behavior-based recommendations, purchase history.
+
+**Don't over-personalize** - can feel intrusive. Use data you have permission to use.
+
+## Frequency and Timing
+
+**Frequency:** Start conservative, increase based on engagement, let users set preferences, monitor unsubscribe rates.
+
+**Timing:** Weekday mornings (9-11 AM local), Tuesday-Thursday often best. Test your specific audience.
+
+## List Hygiene
+
+**Remove immediately:** Hard bounces, unsubscribes, complaints
+
+**Remove after inactivity:** Send re-engagement campaign first, then remove non-responders
+
+**Monitor:** Bounce rate <2%, complaint rate <0.05%
+
+## Required Elements (All Marketing Emails)
+
+- Clear sender identification
+- Physical mailing address (CAN-SPAM)
+- Unsubscribe mechanism
+- Indication it's marketing (GDPR)
+
+## Related
+
+- [Compliance](./compliance.md) - Detailed legal requirements by region
+- [Email Capture](./email-capture.md) - Collecting consent properly
+- [List Management](./list-management.md) - Maintaining list hygiene