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:

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:

{
  "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

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

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