orion/docs/guides/email-templates.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

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 for full technical documentation.