Nas-Notification/docs/multi-provider-email-setup.md

# Multi-Provider Email Configuration

This document explains how to configure multiple email providers (Mailtrap and AWS SES) in the notification system.

## Overview

The system now supports storing **multiple email provider configurations** simultaneously. Each provider's configuration is saved independently, allowing you to:
- Switch between providers without losing configurations
- Keep backup provider credentials ready
- Test different providers easily

## Database Changes

### Migration Required

Run this migration to enable multi-provider support:

```bash
mysql -h <host> -u <user> -p <database> < database/migrations/005_support_multiple_email_providers.sql
```

### What Changed

1. **Removed** unique constraint on `channel_type`
2. **Added** unique constraint on `(channel_type, provider)` combination
3. **Added** `is_active` column to track active provider
4. Now supports multiple rows per channel_type with different providers

**Before:**
```
id | channel_type | provider   | is_enabled
1  | email        | Mailtrap   | true
```

**After:**
```
id | channel_type | provider   | is_enabled | is_active
1  | email        | Mailtrap   | true       | true
2  | email        | AWS SES    | false      | false
```

## How It Works

### 1. **API Behavior**

**GET `/api/notifications/delivery/email-config`**
- Returns ALL provider configurations
- Indicates which provider is active
- Response format:
```json
{
  "success": true,
  "data": {
    "providers": {
      "mailtrap": {
        "enabled": true,
        "provider": "Mailtrap",
        "config": { "host": "...", ... },
        "status": "Connected",
        "successRate": 99.5
      },
      "aws-ses": {
        "enabled": false,
        "provider": "AWS SES",
        "config": { "host": "...", ... },
        "status": "Not Configured",
        "successRate": 0
      }
    },
    "activeProvider": "mailtrap"
  }
}
```

**PUT `/api/notifications/delivery/email-config`**
- Saves configuration for specific provider
- If enabling a provider, **automatically disables others**
- Only ONE provider can be `is_enabled: true` at a time

### 2. **UI Behavior**

**Provider Dropdown:**
- Shows: Mailtrap, AWS SES
- Switching providers loads that provider's saved configuration
- If no config exists, loads default template

**Saving Configuration:**
- Saves to database for the selected provider
- Does NOT overwrite other providers' configs
- Enabling saves current provider and disables others

**Configuration Persistence:**
- Each provider's config is stored separately
- Switching between providers preserves both configurations
- Form fields update automatically when switching

### 3. **Email Sending**

The `emailService.js` looks for:
1. Any `is_enabled: true` config in database
2. Falls back to `.env` variables if no enabled config

Both Mailtrap and AWS SES use **nodemailer SMTP**, so no backend code changes needed.

## Setup Instructions

### Step 1: Run Migration

```bash
mysql -h <host> -u <user> -p <database> < database/migrations/005_support_multiple_email_providers.sql
```

This will:
- ✅ Update schema to support multiple providers
- ✅ Create placeholder rows for Mailtrap and AWS SES
- ✅ Preserve existing configuration

### Step 2: Update Prisma Schema

```bash
npx prisma generate
```

This regenerates the Prisma client with the updated schema.

### Step 3: Configure Providers via UI

1. Go to `/notification/delivery`
2. Select **Mailtrap** from dropdown
3. Fill in Mailtrap credentials
4. Click **Save**
5. Switch to **AWS SES** from dropdown
6. Fill in AWS SES credentials
7. Click **Save**

Both configurations are now saved!

### Step 4: Switch Between Providers

To change active provider:
1. Select desired provider from dropdown
2. Toggle **Enable Email Delivery** to ON
3. Click **Save**

This automatically:
- ✅ Enables selected provider
- ✅ Disables other provider
- ✅ Updates email service to use new provider

## Provider-Specific Configuration

### Mailtrap

**Required Fields:**
- SMTP Host: `live.smtp.mailtrap.io`
- SMTP Port: `587`
- SMTP Username: `apismtp@mailtrap.io`
- SMTP Password: Your Mailtrap API token
- Sender Email: Your verified sender email
- Sender Name: (Optional)

### AWS SES

**Required Fields:**
- SMTP Host: `email-smtp.<region>.amazonaws.com` (e.g., `email-smtp.us-east-1.amazonaws.com`)
- SMTP Port: `587` (STARTTLS) or `465` (TLS)
- SMTP Username: AWS SES SMTP username (NOT IAM user)
- SMTP Password: AWS SES SMTP password (NOT secret key)
- Sender Email: Must be verified in AWS SES
- Sender Name: (Optional)
- AWS Region: e.g., `us-east-1`
- Configuration Set: (Optional) For tracking

**Note:** AWS SES requires:
1. Verified sender email/domain in SES console
2. SMTP credentials generated from SES (not IAM credentials)
3. Account moved out of sandbox for production sending

## Troubleshooting

### Configuration Not Saving
- Check database migration ran successfully
- Verify unique constraint exists: `SHOW INDEX FROM notification_delivery_config;`
- Should see `channel_type_provider` unique index

### Wrong Provider Being Used
- Check `is_enabled` column in database
- Only ONE provider should have `is_enabled = true`
- Run: `SELECT * FROM notification_delivery_config WHERE channel_type = 'email';`

### Form Fields Don't Update When Switching
- Clear browser cache
- Check browser console for errors
- Verify API returns all provider configs

## Files Modified

### Backend
- `server/api/notifications/delivery/email-config.get.js` - Returns all providers
- `server/api/notifications/delivery/email-config.put.js` - Saves per provider
- `prisma/schema.prisma` - Updated unique constraint

### Frontend
- `pages/notification/delivery/index.vue` - Multi-provider UI
- `pages/notification/delivery/providers.vue` - Provider list

### Database
- `database/migrations/005_support_multiple_email_providers.sql` - Schema migration

### Documentation
- `docs/multi-provider-email-setup.md` - This file