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
2. Generate an API key
3. Enter the API key in your store settings

Mailgun

1. Create a Mailgun account at 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:

# 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