@ivannxbt/ai-config 0.1.0

package/.agents/skills/email-best-practices/resources/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.yourdomain.com` for transactional, `m.yourdomain.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/.agents/skills/email-best-practices/resources/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/.agents/skills/email-best-practices/resources/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

package/.agents/skills/email-best-practices/resources/sending-reliability.md

@@ -0,0 +1,155 @@
+# Sending Reliability
+
+Ensuring emails are sent exactly once and handling failures gracefully.
+
+## Idempotency
+
+Prevent duplicate emails when retrying failed requests.
+
+### The Problem
+
+Network issues, timeouts, or server errors can leave you uncertain if an email was sent. Retrying without idempotency risks sending duplicates.
+
+### Solution: Idempotency Keys
+
+Send a unique key with each request. If the same key is sent again, the server returns the original response instead of sending another email.
+
+```typescript
+// Generate deterministic key based on the business event
+const idempotencyKey = `password-reset-${userId}-${resetRequestId}`;
+
+await resend.emails.send({
+  from: 'noreply@example.com',
+  to: user.email,
+  subject: 'Reset your password',
+  html: emailHtml,
+}, {
+  headers: {
+    'Idempotency-Key': idempotencyKey
+  }
+});
+```
+
+### Key Generation Strategies
+
+| Strategy | Example | Use When |
+|----------|---------|----------|
+| Event-based | `order-confirm-${orderId}` | One email per event (recommended) |
+| Request-scoped | `reset-${userId}-${resetRequestId}` | Retries within same request |
+| UUID | `crypto.randomUUID()` | No natural key (generate once, reuse on retry) |
+
+**Best practice:** Use deterministic keys based on the business event. If you retry the same logical send, the same key must be generated. Avoid `Date.now()` or random values generated fresh on each attempt.
+
+**Key expiration:** Idempotency keys are typically cached for 24 hours. Retries within this window return the original response. After expiration, the same key triggers a new send—so complete your retry logic well within 24 hours.
+
+## Retry Logic
+
+Handle transient failures with exponential backoff.
+
+### When to Retry
+
+| Error Type | Retry? | Notes |
+|------------|--------|-------|
+| 5xx (server error) | ✅ Yes | Transient, likely to resolve |
+| 429 (rate limit) | ✅ Yes | Wait for rate limit window |
+| 4xx (client error) | ❌ No | Fix the request first |
+| Network timeout | ✅ Yes | Transient |
+| DNS failure | ✅ Yes | May be transient |
+
+### Exponential Backoff
+
+```typescript
+async function sendWithRetry(emailData, maxRetries = 3) {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await resend.emails.send(emailData);
+    } catch (error) {
+      if (!isRetryable(error) || attempt === maxRetries - 1) {
+        throw error;
+      }
+      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
+      await sleep(delay + Math.random() * 1000); // Add jitter
+    }
+  }
+}
+
+function isRetryable(error) {
+  return error.statusCode >= 500 ||
+         error.statusCode === 429 ||
+         error.code === 'ETIMEDOUT';
+}
+```
+
+**Backoff schedule:** 1s → 2s → 4s → 8s (with jitter to prevent thundering herd)
+
+## Error Handling
+
+### Common Error Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 400 | Bad request | Fix payload (invalid email, missing field) |
+| 401 | Unauthorized | Check API key |
+| 403 | Forbidden | Check permissions, domain verification |
+| 404 | Not found | Check endpoint URL |
+| 422 | Validation error | Fix request data |
+| 429 | Rate limited | Back off, retry after delay |
+| 500 | Server error | Retry with backoff |
+| 503 | Service unavailable | Retry with backoff |
+
+### Error Handling Pattern
+
+```typescript
+try {
+  const result = await resend.emails.send(emailData);
+  await logSuccess(result.id, emailData);
+} catch (error) {
+  if (error.statusCode === 429) {
+    await queueForRetry(emailData, error.retryAfter);
+  } else if (error.statusCode >= 500) {
+    await queueForRetry(emailData);
+  } else {
+    await logFailure(error, emailData);
+    await alertOnCriticalEmail(emailData); // For password resets, etc.
+  }
+}
+```
+
+## Queuing for Reliability
+
+For critical emails, use a queue to ensure delivery even if the initial send fails.
+
+**Benefits:**
+- Survives application restarts
+- Automatic retry handling
+- Rate limit management
+- Audit trail
+
+**Simple pattern:**
+1. Write email to queue/database with "pending" status
+2. Process queue, attempt send
+3. On success: mark "sent", store message ID
+4. On retryable failure: increment retry count, schedule retry
+5. On permanent failure: mark "failed", alert
+
+## Timeouts
+
+Set appropriate timeouts to avoid hanging requests.
+
+```typescript
+const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), 10000);
+
+try {
+  await resend.emails.send(emailData, { signal: controller.signal });
+} finally {
+  clearTimeout(timeout);
+}
+```
+
+**Recommended:** 10-30 seconds for email API calls.
+
+## Related
+
+- [Webhooks & Events](./webhooks-events.md) - Process delivery confirmations and failures
+- [List Management](./list-management.md) - Handle bounces and suppress invalid addresses