Email Templates System

Complete email template management with variable substitution, multi-language support, and tenant isolation.

Features

1. Security

HTML Escaping: All user-provided variables are HTML-escaped to prevent XSS attacks
Command Injection Prevention: Variable names are sanitized to allow only A-Z, 0-9, and underscore
Template Validation: Templates are validated before saving to prevent dangerous code
Tenant Isolation: Each tenant has completely isolated templates

2. Template Management

8 Default Templates: Welcome, password reset, verify email, invite, password change, account update, notification, and alert
HTML + Plain Text: Each template has both HTML and plain text versions
Custom Templates: Upload and manage custom templates
Template Preview: Preview templates with sample data before sending
Backup System: Automatic backups when templates are edited or deleted

3. Multi-Language Support

Multiple Languages: Support for unlimited languages (en, es, fr, de, etc.)
Language Fallback: Automatically falls back to default language if translation is missing
Easy Translation: Copy templates from one language to another and translate

4. Variable Substitution

Global Variables: Brand name, app URL, logo URL, current year, etc.
User Variables: User name, email, ID
Template-Specific Variables: Reset URL, verify URL, invite URL, etc.
Safe Substitution: All values are HTML-escaped before insertion

5. Email Sending Integration

SMTP Support: Send emails via configured SMTP server
Docker Integration: Uses swaks in Docker for email testing
Multi-Format: Sends both HTML and plain text versions
Subject Line Rendering: Dynamic subject lines with variable substitution

6. Multi-Tenant Support

Isolated Templates: Each tenant has their own template directory
Tenant Variables: Tenant ID automatically included in emails
Custom SMTP: Tenants can have their own SMTP configuration (future)
Fallback to Default: Uses default templates if tenant templates don't exist

Usage

Initialize Email Templates

# Initialize with default templates
source src/lib/whitelabel/email-templates.sh
initialize_email_templates

List Available Templates

list_email_templates "en"

Output:

Email Templates (Language: en)
============================================================

welcome              Welcome email sent to new users upon registration
  Subject: Welcome to {{BRAND_NAME}}!
  Category: authentication

password-reset       Password reset email with secure reset link
  Subject: Reset Your Password
  Category: security

verify-email         Email verification with confirmation link
  Subject: Verify Your Email Address
  Category: authentication

...

Render a Template

# Render with custom variables
render_template "welcome" "en" "html" \
  "USER_NAME=John Doe" \
  "[email protected]" \
  "APP_URL=https://myapp.com"

Send an Email

# Send email using template
send_email_from_template "welcome" "[email protected]" "en" \
  "USER_NAME=John Doe" \
  "APP_URL=https://myapp.com"

Preview a Template

# Preview with sample data
preview_email_template "password-reset" "en" "html"

Edit a Template

# Edit template in default editor
edit_email_template "welcome" "en" "html"

# Edit plain text version
edit_email_template "welcome" "en" "txt"

Multi-Language Management

# Add a new language
set_email_language "es"

# Copy templates from English to Spanish
copy_templates_to_language "en" "es"

# List available languages
list_available_languages

Custom Templates

# Upload custom HTML template
upload_custom_template "newsletter" "/path/to/newsletter.html" "/path/to/newsletter.txt" "en"

# Delete custom template
delete_custom_template "newsletter" "en"

Template Validation

# Validate all templates in a language
validate_all_templates "en"

Export/Import Templates

# Export all templates
export_all_templates "en" "./my-templates"

# Import templates
import_all_templates "./my-templates" "en"

Multi-Tenant Operations

# Initialize templates for a tenant
initialize_tenant_templates "tenant123" "en"

# List tenant templates
list_tenant_templates "tenant123" "en"

# Send email using tenant templates
send_tenant_email "tenant123" "welcome" "[email protected]" "en" \
  "USER_NAME=John Doe"

# Render tenant template
render_tenant_template "tenant123" "welcome" "en" "html" \
  "USER_NAME=John Doe"

Statistics

# Show template system statistics
show_template_stats

Output:

Email Template System Statistics
============================================================

Languages: 3
  • en: 8 templates
  • es: 8 templates
  • fr: 8 templates

Tenant Templates: 5 tenants

Preview Files: 12
Backups: 3

Available Templates

1. Welcome (`welcome`)

Sent to new users upon registration.

Variables:

USER_NAME - User's display name
BRAND_NAME - Brand/company name
LOGO_URL - URL to brand logo
APP_URL - Main application URL
CURRENT_YEAR - Current year
COMPANY_ADDRESS - Company address

2. Password Reset (`password-reset`)

Sent when user requests password reset.

Variables:

USER_NAME - User's display name
BRAND_NAME - Brand/company name
RESET_URL - Password reset URL with token
EXPIRY_TIME - Link expiration time (e.g., "1 hour")
CURRENT_YEAR - Current year

3. Verify Email (`verify-email`)

Sent to verify user's email address.

Variables:

USER_NAME - User's display name
VERIFY_URL - Email verification URL with token
EXPIRY_TIME - Link expiration time

4. Invite (`invite`)

Sent when a user invites someone.

Variables:

RECIPIENT_NAME - Name of invited person
SENDER_NAME - Name of user sending invite
BRAND_NAME - Brand/company name
INVITE_URL - Invitation acceptance URL

5. Password Change (`password-change`)

Confirmation that password was changed.

Variables:

USER_NAME - User's display name
CHANGE_DATE - Date of password change

6. Account Update (`account-update`)

Notification of account information changes.

Variables:

USER_NAME - User's display name
UPDATE_DESCRIPTION - Description of what changed

7. Notification (`notification`)

Generic notification template.

Variables:

NOTIFICATION_TITLE - Notification headline
NOTIFICATION_MESSAGE - Notification body
ACTION_URL - Call-to-action URL
ACTION_TEXT - Button text

8. Alert (`alert`)

Alert/warning notifications.

Variables:

ALERT_TITLE - Alert headline
ALERT_MESSAGE - Alert message
ACTION_REQUIRED - Required action description

File Structure

branding/
├── email-templates/
│   ├── VARIABLES.md                    # Variable reference documentation
│   ├── languages/
│   │   ├── en/
│   │   │   ├── welcome.html            # HTML version
│   │   │   ├── welcome.txt             # Plain text version
│   │   │   ├── welcome.json            # Metadata (subject, variables, etc.)
│   │   │   ├── password-reset.html
│   │   │   ├── password-reset.txt
│   │   │   ├── password-reset.json
│   │   │   └── ...
│   │   ├── es/
│   │   │   └── ...
│   │   └── fr/
│   │       └── ...
│   ├── previews/                       # Preview files
│   │   ├── welcome-en.html
│   │   └── ...
│   └── backups/                        # Automatic backups
│       ├── 20260130_120000/
│       └── ...
└── tenants/                            # Multi-tenant isolation
    ├── tenant123/
    │   └── email-templates/
    │       ├── VARIABLES.md
    │       └── languages/
    │           └── en/
    │               └── ...
    └── tenant456/
        └── ...

Security Considerations

1. XSS Prevention

All user-provided variables are HTML-escaped before insertion:

# Input: <script>alert('xss')</script>
# Output: &lt;script&gt;alert('xss')&lt;/script&gt;

2. Command Injection Prevention

Variable names are sanitized to prevent command injection:

# Input: USER$(whoami)_NAME
# Output: USER_NAME  # $(whoami) removed

3. Template Validation

Templates are validated before saving to prevent dangerous code:

# Rejected patterns: $(), `, eval, exec, source, bash, sh

4. Tenant Isolation

Each tenant has isolated templates in their own directory:

branding/tenants/tenant123/email-templates/  # Tenant 123
branding/tenants/tenant456/email-templates/  # Tenant 456

5. Directory Traversal Protection

Tenant IDs are sanitized to prevent directory traversal:

# Input: ../../../etc/passwd
# Output: etcpasswd  # ../ removed

Integration with nself CLI

# Via nself whitelabel command
nself whitelabel email-templates list
nself whitelabel email-templates preview welcome
nself whitelabel email-templates edit welcome
nself whitelabel email-templates test welcome [email protected]
nself whitelabel email-templates validate
nself whitelabel email-templates stats

Environment Variables

# SMTP Configuration (used for sending emails)
AUTH_SMTP_HOST=smtp.example.com
AUTH_SMTP_PORT=587
[email protected]
AUTH_SMTP_PASS=your-password
[email protected]

# Brand Configuration
BRAND_NAME="My App"
BASE_DOMAIN="myapp.com"
APP_URL="https://myapp.com"
LOGO_URL="https://myapp.com/logo.png"
COMPANY_ADDRESS="123 Main St, City, Country"
SUPPORT_EMAIL="[email protected]"

Testing

Run the comprehensive test suite:

bash src/tests/unit/test-email-templates.sh

Tests cover:

HTML escaping and XSS prevention
Variable name sanitization
Template validation
Variable substitution
Template rendering
Multi-language support
Tenant isolation
Directory traversal protection
Template backup on edit
Custom template upload
Export/import functionality
Subject line rendering

Best Practices

Always provide both HTML and plain text versions - Some email clients prefer plain text
Test templates before production use - Use preview_email_template and test_email_template
Use semantic variable names - Clear names like USER_NAME instead of VAR1
Validate all templates - Run validate_all_templates before deployment
Backup regularly - Backups are automatic, but export important customizations
Translate completely - Don't leave English text in non-English templates
Use tenant isolation - Keep tenant templates separate for white-label deployments
Review security - Never include user input directly without HTML escaping
Monitor sending - Log email sends and check for failures
Keep it simple - Complex templates are harder to maintain

Troubleshooting

Templates Not Found

# Initialize templates first
initialize_email_templates

# Check if templates exist
ls -la "$TEMPLATES_DIR/languages/en/"

SMTP Not Configured

# Configure SMTP first
nself email setup

# Test SMTP connection
nself email check

Variables Not Substituting

# Check variable format (must be UPPERCASE with underscores)
# Correct: {{USER_NAME}}
# Wrong: {{userName}}, {{user-name}}

# Verify variables are passed correctly
render_template "welcome" "en" "html" "USER_NAME=Test"

Tenant Templates Not Working

# Initialize tenant templates first
initialize_tenant_templates "tenant123" "en"

# Verify tenant directory exists
ls -la "$(get_tenant_templates_dir 'tenant123')"

Permission Errors

# Fix permissions on template directory
chmod -R 755 "$PROJECT_ROOT/branding/email-templates"

# Fix ownership
chown -R $(whoami) "$PROJECT_ROOT/branding/email-templates"

API Reference

See /Users/admin/Sites/nself/src/lib/whitelabel/email-templates.sh for full API documentation.

Core Functions

initialize_email_templates() - Initialize template system
render_template(type, lang, format, vars...) - Render a template
send_email_from_template(type, email, lang, vars...) - Send email
list_email_templates(lang) - List available templates

Security Functions

html_escape(input) - Escape HTML special characters
sanitize_variable_name(var_name) - Sanitize variable names
validate_template_content(file) - Validate template file
substitute_template_variables(content, vars...) - Safe variable substitution

Management Functions

edit_email_template(name, lang, format) - Edit template
preview_email_template(name, lang, format) - Preview template
upload_custom_template(type, html, txt, lang) - Upload custom template
delete_custom_template(type, lang) - Delete custom template

Multi-Language Functions

set_email_language(lang) - Initialize new language
list_available_languages() - List configured languages
copy_templates_to_language(src, dst) - Copy templates between languages

Multi-Tenant Functions

initialize_tenant_templates(tenant_id, lang) - Initialize tenant templates
render_tenant_template(tenant_id, type, lang, format, vars...) - Render tenant template
send_tenant_email(tenant_id, type, email, lang, vars...) - Send tenant email
list_tenant_templates(tenant_id, lang) - List tenant templates

Batch Operations

validate_all_templates(lang) - Validate all templates
export_all_templates(lang, output_dir) - Export templates
import_all_templates(source_dir, lang) - Import templates
show_template_stats() - Show system statistics

License

Part of nself v0.9.0 - White-Label & Customization (Sprint 14, 60pts)

EMAIL TEMPLATES - nself-org/cli GitHub Wiki

Email Templates System

Features

1. Security

2. Template Management

3. Multi-Language Support

4. Variable Substitution

5. Email Sending Integration

6. Multi-Tenant Support

Usage

Initialize Email Templates

List Available Templates

Render a Template

Send an Email

Preview a Template

Edit a Template

Multi-Language Management

Custom Templates

Template Validation

Export/Import Templates

Multi-Tenant Operations

Statistics

Available Templates

1. Welcome (welcome)

2. Password Reset (password-reset)

3. Verify Email (verify-email)

4. Invite (invite)

5. Password Change (password-change)

6. Account Update (account-update)

7. Notification (notification)

8. Alert (alert)

File Structure

Security Considerations

1. XSS Prevention

2. Command Injection Prevention

3. Template Validation

4. Tenant Isolation

5. Directory Traversal Protection

Integration with nself CLI

Environment Variables

Testing

Best Practices

Troubleshooting

Templates Not Found

SMTP Not Configured

Variables Not Substituting

Tenant Templates Not Working

Permission Errors

API Reference

Core Functions

Security Functions

Management Functions

Multi-Language Functions

Multi-Tenant Functions

Batch Operations

License

⚠️ **GitHub.com Fallback** ⚠️

1. Welcome (`welcome`)

2. Password Reset (`password-reset`)

3. Verify Email (`verify-email`)

4. Invite (`invite`)

5. Password Change (`password-change`)

6. Account Update (`account-update`)

7. Notification (`notification`)

8. Alert (`alert`)

⚠️ GitHub.com Fallback ⚠️