Admin Email Management Guide

Event: user_signup
Template: welcome_new_user
Delay: 0 hours
Frequency: once
``` -->

**Story Reminders**
``` -->
Event: story_inactive
Template: story_reminder_weekly
Delay: 168 hours (1 week)
Frequency: weekly
Conditions: user has stories, user preferences allow
``` -->

**Family Invitations**
``` -->
Event: family_invitation_sent
Template: family_invitation
Delay: 0 hours
Frequency: unlimited
``` -->

### Frequency Management

**Once**: Send only one time ever
**Daily**: Maximum one per day
**Weekly**: Maximum one per week
**Monthly**: Maximum one per month
**Unlimited**: No frequency restrictions

## Analytics

### Performance Metrics

Access detailed analytics at `/dashboard/admin/email/analytics`.

**Delivery Metrics**
- **Sent**: Total emails dispatched
- **Delivered**: Successfully delivered to inbox
- **Bounced**: Failed delivery (hard/soft bounces)
- **Delivery Rate**: Percentage successfully delivered

**Engagement Metrics**
- **Opened**: Recipients who opened the email
- **Clicked**: Recipients who clicked links in email
- **Open Rate**: Percentage of delivered emails opened
- **Click Rate**: Percentage of opened emails clicked
- **Click-Through Rate**: Percentage of delivered emails clicked

**Template Performance**
- Compare metrics across different templates
- Identify top-performing subject lines and content
- Track performance trends over time

**Category Analysis**
- Performance breakdown by email category
- Identify which types of emails perform best
- Optimize category-specific strategies

### Analytics Dashboard Features

**Time Period Selection**
- Last 7 days, 30 days, 90 days, or custom range
- Compare performance across different time periods

**Template Filtering**
- Filter by specific templates or categories
- Compare template variants and versions

**Export Options**
- Download analytics data as CSV
- Generate performance reports for stakeholders

**Real-Time Updates**
- Live dashboard updates every 5 minutes
- Real-time queue status monitoring

## A/B Testing

### Setting Up A/B Tests

1. **Navigate** to `/dashboard/admin/email/ab-test/new`
2. **Select Base Template**: Choose existing template to test against
3. **Create Variant**:
   - **Subject Line**: Test different subject approaches
   - **Content**: Test different messaging or design
   - **Call-to-Action**: Test button text and placement

4. **Configure Test**:
   - **Test Percentage**: What % gets variant (rest gets original)
   - **Duration**: How long to run the test
   - **Success Metric**: Open rate, click rate, or conversions

5. **Launch Test**: Start sending emails with random variant assignment

### A/B Test Best Practices

**Test One Variable**
- Subject line OR content OR CTA, not multiple changes
- Makes it clear what caused performance differences

**Minimum Sample Size**
- At least 100 recipients per variant
- Run for minimum 1 week for statistical significance
- More recipients = more reliable results

**Test Duration**
- Run for full week to account for day-of-week patterns
- Don't stop tests early even if one variant is winning
- Plan test duration based on your email volume

**Statistical Significance**
- Wait for 95% confidence before declaring winner
- System automatically calculates significance
- Document learnings even if test is inconclusive

### Test Ideas

**Subject Line Tests**
- Personalization vs. generic
- Question vs. statement format
- Urgency vs. value-focused
- Emoji vs. text-only

**Content Tests**
- Short vs. long emails
- Image-heavy vs. text-focused
- Multiple CTAs vs. single CTA
- Different tone/voice

**Call-to-Action Tests**
- Button text variations
- Button color and size
- Button placement in email
- Text link vs. button

## Queue Management

### Monitor Email Queue

Access queue management at `/dashboard/admin/email/queue`.

**Queue Status**
- **Pending**: Emails waiting to be sent
- **Processing**: Currently being sent
- **Sent**: Successfully delivered
- **Failed**: Delivery failed (will retry)
- **Cancelled**: Manually cancelled

**Queue Actions**
- Pause/resume queue processing
- Cancel specific emails
- Retry failed emails
- Priority override for urgent emails

### Troubleshooting

**High Failure Rate**
- Check Resend service status and API limits
- Verify email template formatting
- Review recipient email addresses for validity
- Monitor for spam complaints

**Slow Processing**
- Check queue processing frequency
- Monitor server resources and performance
- Review email sending rate limits
- Scale processing workers if needed

**Template Errors**
- Validate template variables and formatting
- Test templates with sample data
- Check for missing required variables
- Review HTML validity

## Email Delivery Setup

### Resend Integration

Configure email sending through Resend service:

**API Configuration**
- Set `RESEND_API_KEY` in environment variables
- Configure `RESEND_FROM_EMAIL` for sender address
- Set up domain authentication for deliverability

**Domain Setup**
- Add DNS records for domain verification
- Configure SPF, DKIM, and DMARC records
- Monitor domain reputation and deliverability

### Sender Reputation

**Best Practices**
- Maintain low bounce and complaint rates
- Use double opt-in for marketing emails
- Provide clear unsubscribe options
- Monitor blacklist status regularly

**Deliverability Monitoring**
- Track delivery rates across email providers
- Monitor spam folder placement
- Watch for delivery delays or blocks
- Maintain sender score above 95%

## Security & Compliance

### Data Protection

**User Privacy**
- Respect user email preferences
- Provide easy unsubscribe options
- Don't share email addresses with third parties
- Secure storage of email content and analytics

**Template Security**
- Validate all template variables
- Sanitize user-generated content
- Prevent XSS in email content
- Use secure links and HTTPS

### Compliance Requirements

**CAN-SPAM Act**
- Include physical address in emails
- Provide clear unsubscribe mechanism
- Honor unsubscribe requests within 10 days
- Use accurate subject lines and sender information

**GDPR Compliance**
- Obtain consent for marketing emails
- Allow users to download their email data
- Provide right to erasure for email preferences
- Document legal basis for email processing

### Audit Trail

**Email Logs**
- Track all email sends and deliveries
- Log template changes and modifications
- Record admin actions and automation changes
- Maintain user preference change history

**Performance Monitoring**
- Monitor email system performance
- Track API usage and rate limits
- Alert on delivery failures or system issues
- Regular backup of email templates and settings

## Advanced Features

### Custom Email Templates

For complex use cases, you can create custom templates:

1. **HTML Email Builder**: Advanced editor for complex layouts
2. **Dynamic Content**: Conditional sections based on user data
3. **Personalization Engine**: Advanced user segmentation
4. **Multi-language Support**: Templates in different languages

### Integration APIs

**Webhook Integration**
- Receive delivery, open, and click events
- Integrate with external analytics platforms
- Custom event tracking and reporting

**Third-party Integration**
- Connect with marketing automation platforms
- Sync with CRM systems
- Export data to business intelligence tools

For technical implementation details, see the [Technical Architecture](./technical-architecture) and [API Reference](./api-reference) documentation.