docs: migrate module documentation to single source of truth
Move 39 documentation files from top-level docs/ into each module's docs/ folder, accessible via symlinks from docs/modules/. Create data-model.md files for 10 modules with full schema documentation. Replace originals with redirect stubs. Remove empty guide stubs. Modules migrated: tenancy, billing, loyalty, marketplace, orders, messaging, cms, catalog, inventory, hosting, prospecting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
287
app/modules/cms/docs/email-templates-guide.md
Normal file
287
app/modules/cms/docs/email-templates-guide.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user