Skip to content

NEWSLETTER_SETUP.md

Latest commit

 

History

History
145 lines (111 loc) · 4.31 KB

NEWSLETTER_SETUP.md

File metadata and controls

145 lines (111 loc) · 4.31 KB

Newsletter System Setup Guide

🚀 Quick Setup

The newsletter system has been completely rebuilt to actually send real emails to your subscribers. Here's how to get it working:

📧 Email Configuration

Step 1: Create Environment File

Create a .env file in your project root with the following content:

# SMTP Configuration for Newsletter System
VITE_SMTP_HOST=smtp.gmail.com
VITE_SMTP_PORT=587
VITE_SMTP_SECURE=false
VITE_SMTP_USER=phcoder.blog@gmail.com
VITE_SMTP_PASS=your_app_password_here

Step 2: Gmail Setup

  1. Enable 2-Factor Authentication

  2. Generate App Password

    • Go to https://myaccount.google.com/apppasswords
    • Select "Mail" as the app
    • Select "Other" as the device (name it "Blog Newsletter")
    • Click "Generate"
    • Copy the 16-character app password
    • Replace your_app_password_here in the .env file

🧪 Testing the System

Access Test Panel

  1. Go to your admin dashboard
  2. Click the "Test Newsletter" button (green button with envelope icon)
  3. Use the test panel to verify each component

Test Sequence

  1. Test SMTP Connection - Verifies your email credentials
  2. Test Newsletter System - Checks database connectivity
  3. Test Email Sending - Sends a test email to verify delivery
  4. Test Subscription - Tests the full subscription flow
  5. Test Unsubscription - Tests the unsubscription flow

🔧 What's Fixed

Before (Not Working)

  • ❌ Mock email service (no real emails sent)
  • ❌ SimpleSmtpService was just simulation
  • ❌ No real SMTP connection
  • ❌ Frontend showed success but no actual emails

After (Now Working)

  • ✅ Real email delivery via Nodemailer
  • ✅ Proper SMTP connection to Gmail
  • ✅ Welcome emails sent on subscription
  • ✅ Blog notification emails sent to all subscribers
  • ✅ Unsubscribe confirmation emails
  • ✅ Comprehensive error handling and logging
  • ✅ Test panel for debugging

📊 How It Works Now

  1. User Subscribes

    • Email stored in Firebase
    • Welcome email sent immediately
    • User added to subscriber list

  2. Admin Creates Blog

    • Blog saved to database
    • Newsletter notification triggered
    • All subscribers receive email with blog details
    • Unsubscribe link included in each email

  3. User Unsubscribes

    • User removed from Firebase
    • Confirmation email sent
    • No more emails received

🚨 Troubleshooting

Common Issues

  1. "SMTP authentication failed"

    • Check your app password is correct
    • Ensure 2FA is enabled on Gmail
    • Verify email address in .env file

  2. "Failed to connect to SMTP server"

    • Check internet connection
    • Verify SMTP host and port
    • Ensure firewall isn't blocking port 587

  3. "Email sent but not received"

    • Check spam/junk folder
    • Wait 5-10 minutes for delivery
    • Verify recipient email is correct

Debug Steps

  1. Check Console Logs

    • Open browser developer tools
    • Look for detailed email logs
    • Check for error messages

  2. Test Individual Components

    • Use the test panel systematically
    • Test SMTP connection first
    • Then test email sending
    • Finally test full subscription flow

  3. Verify Environment Variables

    • Ensure .env file is in project root
    • Check variable names match exactly
    • Restart development server after changes

📈 Performance Notes

  • Gmail Limits: 500 emails per day
  • Rate Limiting: 100ms delay between emails to avoid overwhelming SMTP
  • Batch Processing: Emails sent sequentially for reliability
  • Error Handling: Failed emails logged but don't stop the process

🎯 Next Steps

  1. Set up your .env file with real Gmail credentials
  2. Test the SMTP connection using the test panel
  3. Subscribe a test email to verify the full flow
  4. Create a test blog post to test notifications
  5. Monitor the console for detailed logs

🆘 Need Help?

If you're still having issues:

  1. Check the browser console for error messages
  2. Verify your Gmail app password is correct
  3. Ensure your .env file is properly formatted
  4. Test with a different email address
  5. Check if your Gmail account has any restrictions

The system now provides detailed logging, so you should see exactly what's happening at each step!