MyClub/DOCS/NEWSLETTER_TESTING_GUIDE.md

Newsletter Testing Guide

🧪 Complete Test Suite for All Newsletter Types

This guide shows how to test every newsletter function from the admin panel.

📬 Available Test Types

API Endpoint

POST /api/v1/admin/newsletter/test
Authorization: Bearer {admin_token}
Content-Type: application/json

Request Body

{
  "email": "your-test@email.com",  // or use "emails": ["email1@test.com", "email2@test.com"]
  "type": "test_type_here"
}

---

✅ Test Cases (All Newsletter Functions)

1. Subscription Flow Tests

A. Setup Email (Initial Token Email)

curl -X POST http://localhost:8080/api/v1/admin/newsletter/test \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "type": "setup"
  }'

Tests:

• ✅ Initial subscription email with token
• ✅ Link to preference setup page
• ✅ Token generation and URL formatting

B. Welcome Email

curl -X POST http://localhost:8080/api/v1/admin/newsletter/test \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "type": "welcome"
  }'

Tests:

• ✅ Welcome introduction email
• ✅ Unsubscribe/manage links
• ✅ Club branding

C. Welcome Back Email (Resubscribe)

curl -X POST http://localhost:8080/api/v1/admin/newsletter/test \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "type": "welcome_back"
  }'

Tests:

• ✅ Resubscription email
• ✅ Preference restoration

---

2. Týdenní Přehled (Weekly Overview)

curl -X POST http://localhost:8080/api/v1/admin/newsletter/test \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "type": "weekly"
  }'

Tests:

• ✅ Weekly digest with all content
• ✅ Blogs section
• ✅ Events section
• ✅ Upcoming matches section
• ✅ Recent scores section
• ✅ Preference-based filtering
• ✅ Category filtering

Individual Sections:

# Test only blogs
"type": "blogs"

# Test only events  
"type": "events"

# Test only matches
"type": "matches"

# Test only scores
"type": "scores"

---

3. Nadcházející Zápasy (Match Reminders)

A. 48-Hour Reminder

curl -X POST http://localhost:8080/api/v1/admin/newsletter/test \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "type": "match_reminder_48h"
  }'

Tests:

• ✅ 48h before match alert
• ✅ Match category display
• ✅ Teams display
• ✅ Date and time
• ✅ Place/venue
• ✅ Proper formatting

B. Day-of Reminder

curl -X POST http://localhost:8080/api/v1/admin/newsletter/test \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "type": "match_reminder_today"
  }'

Tests:

• ✅ Same-day match alert
• ✅ All match details
• ✅ Urgency messaging

---

4. Blog Notifications

curl -X POST http://localhost:8080/api/v1/admin/newsletter/test \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "type": "blog_notification"
  }'

Tests:

• ✅ New blog release notification
• ✅ Article title and excerpt
• ✅ Link to full article
• ✅ Call-to-action button
• ✅ Proper styling

---

5. Výsledky Zápasu (Match Results)

curl -X POST http://localhost:8080/api/v1/admin/newsletter/test \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "type": "match_result"
  }'

Tests:

• ✅ Match result notification
• ✅ Final score display
• ✅ Date and competition
• ✅ Result formatting
• ✅ Victory/defeat messaging

---

6. Basic SMTP Test

curl -X POST http://localhost:8080/api/v1/admin/newsletter/test \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "type": "newsletter"
  }'

Tests:

• ✅ SMTP configuration
• ✅ Email delivery
• ✅ Basic template rendering

---

🎯 Complete Test Checklist

Use this checklist to verify all newsletter functions:

Subscription & Onboarding

• setup - Initial setup email with token ✉️
• welcome - Welcome email with manage/unsubscribe ✉️
• welcome_back - Resubscribe email ✉️

Content Newsletters

• weekly - Full weekly digest (all sections) 📅
• blogs - Blog-only digest 📰
• events - Events-only digest 🎉
• matches - Matches-only digest ⚽
• scores - Scores-only digest 🏆

Match Notifications

• match_reminder_48h - 48h before match ⏰
• match_reminder_today - Day-of match ⏰

Special Notifications

• blog_notification - New blog release 📝
• match_result - Post-match result 🎯

System Test

• newsletter - Basic SMTP test 🔧

---

🖥️ Admin UI Test Buttons (Implementation Guide)

To add test buttons to your admin panel, create a test page with these buttons:

// Example React/TypeScript implementation
const newsletterTests = [
  { type: 'setup', label: 'Setup Email', icon: '⚙️', category: 'Subscription' },
  { type: 'welcome', label: 'Welcome Email', icon: '👋', category: 'Subscription' },
  { type: 'welcome_back', label: 'Welcome Back', icon: '🔄', category: 'Subscription' },
  
  { type: 'weekly', label: 'Weekly Digest', icon: '📅', category: 'Digests' },
  { type: 'blogs', label: 'Blogs Only', icon: '📰', category: 'Digests' },
  { type: 'events', label: 'Events Only', icon: '🎉', category: 'Digests' },
  { type: 'matches', label: 'Matches Only', icon: '⚽', category: 'Digests' },
  { type: 'scores', label: 'Scores Only', icon: '🏆', category: 'Digests' },
  
  { type: 'match_reminder_48h', label: '48h Match Alert', icon: '⏰', category: 'Alerts' },
  { type: 'match_reminder_today', label: 'Today Match Alert', icon: '🔔', category: 'Alerts' },
  { type: 'blog_notification', label: 'Blog Release', icon: '📝', category: 'Alerts' },
  { type: 'match_result', label: 'Match Result', icon: '🎯', category: 'Alerts' },
  
  { type: 'newsletter', label: 'SMTP Test', icon: '🔧', category: 'System' },
];

async function sendTest(type: string, email: string) {
  const response = await fetch('/api/v1/admin/newsletter/test', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${adminToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ type, email }),
  });
  
  if (response.ok) {
    alert(`Test email "${type}" sent to ${email}`);
  } else {
    alert('Failed to send test email');
  }
}

UI Layout Suggestion

┌─────────────────────────────────────────┐
│   Newsletter Testing Panel              │
├─────────────────────────────────────────┤
│                                         │
│  Test Email: [________________] 📧      │
│                                         │
│  ┌─── Subscription Flow ───────────┐   │
│  │  [⚙️ Setup Email]                │   │
│  │  [👋 Welcome Email]              │   │
│  │  [🔄 Welcome Back]               │   │
│  └──────────────────────────────────┘   │
│                                         │
│  ┌─── Content Digests ─────────────┐   │
│  │  [📅 Weekly Digest]              │   │
│  │  [📰 Blogs] [🎉 Events]          │   │
│  │  [⚽ Matches] [🏆 Scores]         │   │
│  └──────────────────────────────────┘   │
│                                         │
│  ┌─── Match Alerts ────────────────┐   │
│  │  [⏰ 48h Reminder]               │   │
│  │  [🔔 Today Reminder]             │   │
│  │  [🎯 Match Result]               │   │
│  └──────────────────────────────────┘   │
│                                         │
│  ┌─── Special Notifications ───────┐   │
│  │  [📝 Blog Release]               │   │
│  └──────────────────────────────────┘   │
│                                         │
│  ┌─── System ──────────────────────┐   │
│  │  [🔧 SMTP Test]                  │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘

---

🔍 Verification Steps

After Sending Each Test:

1. Check Email Inbox

   • Verify email received
   • Check sender name and address
   • Verify subject line

2. Verify Content

   • Check all text renders correctly
   • Verify images load (if any)
   • Test all links work
   • Check responsive design (mobile/desktop)

3. Test Interactive Elements

   • Click article links (should track)
   • Click unsubscribe (should work with token)
   • Click manage preferences (should load page)

4. Verify Analytics

   • Check email_log table for entry
   • Open email and verify email_event logs "open"
   • Click link and verify email_event logs "click"

-- Check email logs
SELECT * FROM email_log ORDER BY created_at DESC LIMIT 10;

-- Check events
SELECT * FROM email_event ORDER BY created_at DESC LIMIT 10;

---

🐛 Troubleshooting

Email Not Received?

1. Check SMTP Configuration

   SELECT smtp_host, smtp_port, smtp_from 
   FROM settings LIMIT 1;
   

2. Check Spam Folder

   • Test emails might be flagged as spam
   • Add sender to whitelist

3. Check Server Logs

   # Look for SMTP errors
   grep -i "smtp" logs/app.log
   grep -i "newsletter" logs/app.log
   

4. Verify Email Address

   • Ensure email format is valid
   • Try different email provider

Wrong Content?

1. Check Cache Files

   ls -la cache/prefetch/
   # Should have: articles.json, events_upcoming.json, facr_club_info.json
   

2. Refresh Cache

   • Wait for prefetcher cycle (30 minutes)
   • Or manually trigger: POST /api/v1/admin/prefetch/trigger

Links Not Working?

1. Check Frontend URL

   echo $FRONTEND_BASE_URL
   # Should be: http://localhost:3000 (dev) or https://your-domain.com (prod)
   

2. Verify Token Generation

   echo $JWT_SECRET
   # Should NOT be: "default-secret-key-change-in-production"
   

---

📊 Test Results Log Template

Use this to track your testing:

## Newsletter Test Results - [Date]

### Subscription Flow
- [ ] Setup Email - ✅/❌ - Notes: _______
- [ ] Welcome Email - ✅/❌ - Notes: _______
- [ ] Welcome Back - ✅/❌ - Notes: _______

### Content Digests
- [ ] Weekly Digest - ✅/❌ - Notes: _______
- [ ] Blogs Only - ✅/❌ - Notes: _______
- [ ] Events Only - ✅/❌ - Notes: _______
- [ ] Matches Only - ✅/❌ - Notes: _______
- [ ] Scores Only - ✅/❌ - Notes: _______

### Match Alerts
- [ ] 48h Reminder - ✅/❌ - Notes: _______
- [ ] Today Reminder - ✅/❌ - Notes: _______
- [ ] Match Result - ✅/❌ - Notes: _______

### Special Notifications
- [ ] Blog Release - ✅/❌ - Notes: _______

### System
- [ ] SMTP Test - ✅/❌ - Notes: _______

### Analytics Verification
- [ ] Open tracking works - ✅/❌
- [ ] Click tracking works - ✅/❌
- [ ] Blog link tracking works - ✅/❌
- [ ] Unsubscribe works - ✅/❌

### Issues Found:
1. _______________________
2. _______________________
3. _______________________

---

🚀 Quick Test All (Bash Script)

Save this as test-newsletters.sh:

#!/bin/bash

TOKEN="YOUR_ADMIN_TOKEN"
EMAIL="your-test@email.com"
API="http://localhost:8080/api/v1/admin/newsletter/test"

test_types=(
  "setup"
  "welcome"
  "welcome_back"
  "weekly"
  "blogs"
  "events"
  "matches"
  "scores"
  "match_reminder_48h"
  "match_reminder_today"
  "blog_notification"
  "match_result"
  "newsletter"
)

for type in "${test_types[@]}"; do
  echo "Testing: $type"
  curl -X POST "$API" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"email\":\"$EMAIL\",\"type\":\"$type\"}"
  echo ""
  sleep 2  # Delay between requests
done

echo "All tests sent to $EMAIL"

Usage:

chmod +x test-newsletters.sh
./test-newsletters.sh

---

✅ Summary

Total Test Types Available: 13

Category	Test Types	Count
Subscription	setup, welcome, welcome_back	3
Digests	weekly, blogs, events, matches, scores	5
Alerts	match_reminder_48h, match_reminder_today, blog_notification, match_result	4
System	newsletter	1

All newsletter functions can be tested individually from the admin panel! 🎉