# Email Updates & Newsletter System

This document explains the email functionality for **General Updates** and **Monthly Newsletter** in BUILDMATE.

## Overview

Users can subscribe to two types of email communications:
- **General Updates**: Important app updates, new features, bug fixes, and announcements
- **Monthly Newsletter**: Curated PC builds, component tips, market insights, and inspiration

## Email Endpoints

### 1. Welcome Email
**Endpoint:** `POST /api/emails/send-welcome-email`

Sent automatically to new users upon account creation.

**Request Body:**
```json
{
  "email": "user@example.com",
  "username": "BuilderJohn"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Welcome email sent successfully"
}
```

### 2. General Updates
**Endpoint:** `POST /api/emails/send-general-update`

Send a general update to all users who have enabled this preference.

**Request Body:**
```json
{
  "title": "🎉 New Feature: Build Comparison",
  "content": "We've added a powerful new feature that lets you compare two builds side-by-side. Check it out in your dashboard!",
  "actionUrl": "https://buildmate.com/compare",
  "actionText": "Try Comparison Tool"
}
```

**Response:**
```json
{
  "success": true,
  "message": "General update emails sent to 150 users (0 failures)",
  "sent": 150,
  "failed": 0
}
```

### 3. Newsletter
**Endpoint:** `POST /api/emails/send-newsletter`

Send a newsletter to all users who have enabled newsletter subscription.

**Request Body:**
```json
{
  "title": "March 2026 Newsletter - Budget Gaming Builds",
  "content": "This month we're focusing on building powerful gaming rigs under $1,200. From the latest GPU deals to CPU recommendations, we've got you covered.",
  "featuredBuilds": [
    {
      "id": 123,
      "name": "1440p Gaming Build - $1,100",
      "description": "High-performance 1440p gaming with RTX 4070",
      "createdBy": "BuilderAlex",
      "createdAt": "2026-03-01"
    },
    {
      "id": 124,
      "name": "Budget 1080p Streaming - $900",
      "description": "Perfect for content creators on a tight budget",
      "createdBy": "TechStreamer",
      "createdAt": "2026-02-28"
    }
  ]
}
```

**Response:**
```json
{
  "success": true,
  "message": "Newsletter sent to 320 users (2 failures)",
  "sent": 320,
  "failed": 2
}
```

## How to Use

### Sending General Updates

```bash
curl -X POST http://localhost:3000/api/emails/send-general-update \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Feature Released",
    "content": "Check out our new advanced filtering system!",
    "actionUrl": "https://buildmate.com/filters",
    "actionText": "Explore Filters"
  }'
```

### Sending Monthly Newsletter

```bash
curl -X POST http://localhost:3000/api/emails/send-newsletter \
  -H "Content-Type: application/json" \
  -d '{
    "title": "March Newsletter",
    "content": "This month: GPU price drops and new components!",
    "featuredBuilds": []
  }'
```

## User Preferences

Users can manage their email preferences in **Settings → Notification Preferences**:
- Toggle **General Updates** on/off
- Toggle **Monthly Newsletter** on/off

Preferences are stored in the `notification_preferences` table:
- `email_updates` (boolean) - Controls general updates
- `newsletter` (boolean) - Controls newsletter

## Database Schema

### notification_preferences Table
```sql
CREATE TABLE notification_preferences (
  user_id INTEGER PRIMARY KEY,
  email_updates BOOLEAN DEFAULT false,
  newsletter BOOLEAN DEFAULT false,
  build_likes BOOLEAN DEFAULT true,
  comments BOOLEAN DEFAULT true,
  followers BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);
```

## Default Preferences for New Users

When a user creates an account, they automatically get these defaults:
- ✅ Build Likes notifications (enabled)
- ✅ Comments notifications (enabled)
- ✅ Followers notifications (enabled)
- ❌ General Updates (disabled)
- ❌ Newsletter (disabled)

## Email Template Features

Both email types include:
- Dark theme design (responsive to BUILDMATE's aesthetic)
- User's name personalization
- Clear call-to-action buttons
- Links to manage preferences
- Footer with preference management link

## Sample Email Content Ideas

### General Updates
- New features or improvements
- Security updates or important notices
- Service maintenance announcements
- Seasonal promotions or events
- Community milestones ("We've hit 10,000 builders!")

### Newsletter
- Curated PC builds for different budgets
- Component price trends and deals
- New GPU/CPU releases and benchmarks
- Building tips and optimization guides
- Community spotlight: Featured builds
- Market analysis: What's trending

## Setting Up Scheduled Emails

To schedule these emails regularly, you can:

1. **Use a Cron Service** (Vercel, AWS Lambda, etc.):
   - Schedule POST requests to the endpoints
   - Run on specific days/times

2. **Manual Trigger**:
   - Create an admin dashboard
   - Add buttons to send emails on demand

3. **Webhook Integration**:
   - Trigger from external services
   - Call endpoints from backend jobs

## Troubleshooting

### Issue: "SMTP credentials are still placeholders"
- Update your `.env.local` with real SMTP credentials
- Required: `SMTP_HOST`, `SMTP_USER`, `SMTP_PASSWORD`

### Issue: No emails sent despite correct preferences
- Verify users have the preference enabled
- Check `notification_preferences` table for correct values
- Review SMTP configuration
- Check Node.js server logs for errors

### Issue: Emails going to spam
- Verify your SMTP sender email is legitimate
- Add SPF, DKIM, DMARC records for your domain
- Avoid spam words in email content
- Keep HTML emails clean and professional

## Best Practices

1. **Frequency**: Don't overwhelm users
   - General Updates: 2-4 times per month
   - Newsletter: Once per month

2. **Content Quality**: Keep emails valuable
   - Personalize with user's name
   - Include clear, actionable content
   - Respect users' time

3. **Segmentation**: Consider different user segments
   - New users vs. active builders
   - Different interest levels
   - Regional preferences

4. **Testing**: Test emails before sending
   - Send to yourself first
   - Check formatting on mobile
   - Verify links work

5. **Analytics**: Track engagement
   - Monitor open rates
   - Track click-through rates
   - Adjust based on performance