Update various configuration files, components, and assets; enhance notification system and API endpoints; improve documentation and styles across the application.
This commit is contained in:
Haqeem Solehan
211
docs/multi-provider-email-setup.md
Normal file
211
docs/multi-provider-email-setup.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user