orion/app/modules/messaging/docs/email-settings.md

# Email Settings Guide

This guide covers email configuration for both **stores** and **platform administrators**. The Orion platform uses a layered email system where stores manage their own email sending while the platform handles system-level communications.

## Overview

The email system has two distinct configurations:

| Aspect | Platform (Admin) | Store |
|--------|-----------------|--------|
| Purpose | System emails (billing, admin notifications) | Customer-facing emails (orders, marketing) |
| Configuration | Environment variables (.env) + Database overrides | Database (per-store) |
| Cost | Platform owner pays | Store pays |
| Providers | SMTP, SendGrid, Mailgun, SES | SMTP (all tiers), Premium providers (Business+) |

---

## Store Email Settings

### Getting Started

As a store, you need to configure email settings to send emails to your customers. This includes order confirmations, shipping updates, and marketing emails.

#### Accessing Email Settings

1. Log in to your Store Dashboard
2. Navigate to **Settings** from the sidebar
3. Click on the **Email** tab

### Available Providers

| Provider | Tier Required | Best For |
|----------|---------------|----------|
| SMTP | All tiers | Standard email servers, most common |
| SendGrid | Business+ | High-volume transactional emails |
| Mailgun | Business+ | Developer-friendly API |
| Amazon SES | Business+ | AWS ecosystem, cost-effective |

### Configuring SMTP

SMTP is available for all subscription tiers. Common SMTP providers include:
- Gmail (smtp.gmail.com:587)
- Microsoft 365 (smtp.office365.com:587)
- Your hosting provider's SMTP server

**Required Fields:**
- **From Email**: The sender email address (e.g., orders@yourstore.com)
- **From Name**: The sender display name (e.g., "Your Store")
- **SMTP Host**: Your SMTP server address
- **SMTP Port**: Usually 587 (TLS) or 465 (SSL)
- **SMTP Username**: Your login username
- **SMTP Password**: Your login password
- **Use TLS**: Enable for port 587 (recommended)
- **Use SSL**: Enable for port 465

### Configuring Premium Providers (Business+)

If you have a Business or Enterprise subscription, you can use premium email providers:

#### SendGrid
1. Create a SendGrid account at [sendgrid.com](https://sendgrid.com)
2. Generate an API key
3. Enter the API key in your store settings

#### Mailgun
1. Create a Mailgun account at [mailgun.com](https://mailgun.com)
2. Add and verify your domain
3. Get your API key from the dashboard
4. Enter the API key and domain in your settings

#### Amazon SES
1. Set up SES in your AWS account
2. Verify your sender domain/email
3. Create IAM credentials with SES permissions
4. Enter the access key, secret key, and region

### Verifying Your Configuration

After configuring your email settings:

1. Click **Save Settings**
2. Enter a test email address in the **Test Email** field
3. Click **Send Test**
4. Check your inbox for the test email

If the test fails, check:
- Your credentials are correct
- Your IP/domain is not blocked
- For Gmail: Allow "less secure apps" or use an app password

### Email Warning Banner

Until you configure and verify your email settings, you'll see a warning banner at the top of your dashboard. This ensures you don't forget to set up email before your store goes live.

---

## Platform Admin Email Settings

### Overview

Platform administrators can configure system-wide email settings for platform communications like:
- Subscription billing notifications
- Admin alerts
- Platform-wide announcements

### Configuration Sources

Admin email settings support two configuration sources:

1. **Environment Variables (.env)** - Default configuration
2. **Database Overrides** - Override .env via the admin UI

Database settings take priority over .env values.

### Accessing Admin Email Settings

1. Log in to the Admin Panel
2. Navigate to **Settings**
3. Click on the **Email** tab

### Viewing Current Configuration

The Email tab shows:
- **Provider**: Current email provider (SMTP, SendGrid, etc.)
- **From Email**: Sender email address
- **From Name**: Sender display name
- **Status**: Whether email is configured and enabled
- **DB Overrides**: Whether database overrides are active

### Editing Settings

Click **Edit Settings** to modify the email configuration:

1. Select the email provider
2. Enter the required credentials
3. Configure enabled/debug flags
4. Click **Save Email Settings**

### Resetting to .env Defaults

If you've made database overrides and want to revert to .env configuration:

1. Click **Reset to .env Defaults**
2. Confirm the action

This removes all email settings from the database, reverting to .env values.

### Testing Configuration

1. Enter a test email address
2. Click **Send Test**
3. Check your inbox

---

## Environment Variables Reference

For platform configuration via .env:

```env
# Provider: smtp, sendgrid, mailgun, ses
EMAIL_PROVIDER=smtp

# Sender identity
EMAIL_FROM_ADDRESS=noreply@yourplatform.com
EMAIL_FROM_NAME=Your Platform
EMAIL_REPLY_TO=support@yourplatform.com

# Behavior
EMAIL_ENABLED=true
EMAIL_DEBUG=false

# SMTP Configuration
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-username
SMTP_PASSWORD=your-password
SMTP_USE_TLS=true
SMTP_USE_SSL=false

# SendGrid
SENDGRID_API_KEY=your-api-key

# Mailgun
MAILGUN_API_KEY=your-api-key
MAILGUN_DOMAIN=mg.yourdomain.com

# Amazon SES
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=eu-west-1
```

---

## Tier-Based Branding

The email system includes tier-based branding for store emails:

| Tier | Branding |
|------|----------|
| Essential | "Powered by Orion" footer |
| Professional | "Powered by Orion" footer |
| Business | No branding (white-label) |
| Enterprise | No branding (white-label) |

Business and Enterprise tier stores get completely white-labeled emails with no Orion branding.

---

## Troubleshooting

### Common Issues

**"Email sending is disabled"**
- Check that `EMAIL_ENABLED=true` in .env
- Or enable it in the admin settings

**"Connection refused" on SMTP**
- Verify SMTP host and port
- Check firewall rules
- Ensure TLS/SSL settings match your server

**"Authentication failed"**
- Double-check username/password
- For Gmail, use an App Password
- For Microsoft 365, check MFA requirements

**"SendGrid error: 403"**
- Verify your API key has Mail Send permissions
- Check sender identity is verified

**Premium provider not available**
- Upgrade to Business or Enterprise tier
- Contact support if you have the right tier but can't access

### Debug Mode

Enable debug mode to log emails instead of sending them:
- Set `EMAIL_DEBUG=true` in .env
- Or enable "Debug mode" in admin settings

Debug mode logs the email content to the server logs without actually sending.

---

## Security Best Practices

1. **Never share API keys or passwords** in logs or frontend
2. **Use environment variables** for sensitive credentials
3. **Enable TLS** for SMTP connections
4. **Verify sender domains** with your email provider
5. **Monitor email logs** for delivery issues
6. **Rotate credentials** periodically