orion/app/modules/cms/docs/email-templates-guide.md

# Email Templates Guide

## Overview

The Orion platform provides a comprehensive email template system that allows:

- **Platform Administrators**: Manage all email templates across the platform
- **Stores**: Customize customer-facing emails with their own branding

This guide covers how to use the email template system from both perspectives.

---

## For Stores

### Accessing Email Templates

1. Log in to your store dashboard
2. Navigate to **Settings** > **Email Templates** in the sidebar
3. You'll see a list of all customizable email templates

### Understanding Template Status

Each template shows its customization status:

| Status | Description |
|--------|-------------|
| **Platform Default** | Using the standard Orion template |
| **Customized** | You have created a custom version |
| Language badges (green) | Languages where you have customizations |

### Customizing a Template

1. Click on any template to open the edit modal
2. Select the language tab you want to customize (EN, FR, DE, LB)
3. Edit the following fields:
   - **Subject**: The email subject line
   - **HTML Body**: The rich HTML content
   - **Plain Text Body**: Fallback for email clients that don't support HTML

4. Click **Save** to save your customization

### Template Variables

Templates use special variables that are automatically replaced with actual values. Common variables include:

| Variable | Description |
|----------|-------------|
| `{{ customer_name }}` | Customer's first name |
| `{{ order_number }}` | Order reference number |
| `{{ store_name }}` | Your store name |
| `{{ platform_name }}` | Platform name (Orion or your whitelabel name) |

Each template shows its available variables in the reference panel.

### Previewing Templates

Before saving, you can preview your template:

1. Click **Preview** in the edit modal
2. A preview window shows how the email will look
3. Sample data is used for all variables

### Testing Templates

To send a test email:

1. Click **Send Test Email** in the edit modal
2. Enter your email address
3. Click **Send**
4. Check your inbox to see the actual email

### Reverting to Platform Default

If you want to remove your customization and use the platform default:

1. Open the template edit modal
2. Click **Revert to Default**
3. Confirm the action

Your customization will be deleted and the platform template will be used.

### Available Templates for Stores

| Template | Category | Description |
|----------|----------|-------------|
| Welcome Email | AUTH | Sent when a customer registers |
| Password Reset | AUTH | Password reset link |
| Order Confirmation | ORDERS | Sent after order placement |
| Shipping Notification | ORDERS | Sent when order is shipped |

**Note:** Billing and subscription emails are platform-only and cannot be customized.

---

## For Platform Administrators

### Accessing Email Templates

1. Log in to the admin dashboard
2. Navigate to **System** > **Email Templates** in the sidebar
3. You'll see all platform templates grouped by category

### Template Categories

| Category | Description | Store Override |
|----------|-------------|-----------------|
| AUTH | Authentication emails | Allowed |
| ORDERS | Order-related emails | Allowed |
| BILLING | Subscription/payment emails | **Not Allowed** |
| SYSTEM | System notifications | Allowed |
| MARKETING | Promotional emails | Allowed |

### Editing Platform Templates

1. Click on any template to open the edit modal
2. Select the language tab (EN, FR, DE, LB)
3. Edit the subject and body content
4. Click **Save**

**Important:** Changes to platform templates affect:
- All stores who haven't customized the template
- New stores automatically

### Creating New Templates

To add a new template:

1. Use the database seed script or migration
2. Define the template code, category, and languages
3. Set `is_platform_only` if stores shouldn't override it

### Viewing Email Logs

To see email delivery history:

1. Open a template
2. Click **View Logs**
3. See recent emails sent using this template

Logs show:
- Recipient email
- Send date/time
- Delivery status
- Store (if applicable)

### Template Best Practices

1. **Use all 4 languages**: Provide content in EN, FR, DE, and LB
2. **Test before publishing**: Always send test emails
3. **Include plain text**: Not all email clients support HTML
4. **Use consistent branding**: Follow Orion brand guidelines
5. **Keep subjects short**: Under 60 characters for mobile

---

## Language Resolution

When sending an email, the system determines the language in this order:

1. **Customer's preferred language** (if set in their profile)
2. **Store's storefront language** (if customer doesn't have preference)
3. **Platform default** (French - "fr")

### Template Resolution for Stores

1. System checks if store has a custom override
2. If yes, uses store's template
3. If no, falls back to platform template
4. If requested language unavailable, falls back to English

---

## Branding

### Standard Stores

Standard stores' emails include Orion branding:
- Orion logo in header
- "Powered by Orion" footer

### Whitelabel Stores

Enterprise-tier stores with whitelabel enabled:
- No Orion branding
- Store's logo in header
- Custom footer (if configured)

---

## Email Template Variables Reference

### Authentication Templates

#### signup_welcome
```
{{ first_name }}        - Customer's first name
{{ merchant_name }}      - Store merchant name
{{ email }}             - Customer's email
{{ login_url }}         - Link to login page
{{ trial_days }}        - Trial period length
{{ tier_name }}         - Subscription tier
```

#### password_reset
```
{{ customer_name }}     - Customer's name
{{ reset_link }}        - Password reset URL
{{ expiry_hours }}      - Link expiration time
```

### Order Templates

#### order_confirmation
```
{{ customer_name }}     - Customer's name
{{ order_number }}      - Order reference
{{ order_total }}       - Order total amount
{{ order_items_count }} - Number of items
{{ order_date }}        - Order date
{{ shipping_address }}  - Delivery address
```

### Common Variables (All Templates)

```
{{ platform_name }}     - "Orion" or whitelabel name
{{ platform_logo_url }} - Platform logo URL
{{ support_email }}     - Support email address
{{ store_name }}       - Store's business name
{{ store_logo_url }}   - Store's logo URL
```

---

## Troubleshooting

### Email Not Received

1. Check spam/junk folder
2. Verify email address is correct
3. Check email logs in admin dashboard
4. Verify SMTP configuration

### Template Not Applying

1. Clear browser cache
2. Verify the correct language is selected
3. Check if store override exists
4. Verify template is not platform-only

### Variables Not Replaced

1. Check variable spelling (case-sensitive)
2. Ensure variable is available for this template
3. Wrap variables in `{{ }}` syntax
4. Check for typos in variable names

---

## API Reference

For developers integrating with the email system:

### Sending a Template Email

```python
from app.services.email_service import EmailService

email_service = EmailService(db)
email_service.send_template(
    template_code="order_confirmation",
    to_email="customer@example.com",
    to_name="John Doe",
    language="fr",
    variables={
        "customer_name": "John",
        "order_number": "ORD-12345",
        "order_total": "99.99",
    },
    store_id=store.id,
    related_type="order",
    related_id=order.id,
)
```

See [Email Templates Architecture](../cms/email-templates.md) for full technical documentation.