Amazing.Module.EmailTemplate

A professional email template management module for Oqtane Framework with rich HTML editing, template variables, test email capabilities, and a public API for inter-module email sending.

---

Features

Email Template Management

• CRUD Operations - Create, read, update, and delete email templates
• Rich HTML Editor - Oqtane's RichTextEditor component (supports Radzen or QuillJS)
• Template Variables - Dynamic content replacement using {{VariableName}} syntax
• Category Organization - Group templates by functional area
• Active/Inactive Status - Control template availability
• Search Integration - Full-text search on template content
• Module Portability - Complete import/export support

Test Email Capability

• Send Test Emails - Validate templates before production use
• Sample Variable Input - Test variable replacement with JSON data
• Instant Feedback - Success/error messages with detailed logging
• Preview Your Templates - See exactly what recipients will receive

Public Email Service (For Developers)

• IEmailSendingService - Reusable service for other Oqtane modules
• Simple API - Send templated emails with 3 lines of code
• Template Discovery - List available templates by name or category
• Variable Replacement - Automatic processing of template variables
• Notification Integration - Uses Oqtane's built-in SMTP infrastructure

---

Quick Start

Installation

1. Download the module package from Releases
2. Install via Oqtane Admin ? Module Management ? Upload Module
3. Add the module to a page
4. Create your first email template

Creating Your First Template

1. Click "Add EmailTemplate"
2. Fill in the form:
   • Name: "Welcome Email"
   • Subject: Welcome {{FirstName}}!
   • Body: Use the rich text editor to create formatted content
   • Variables: {{FirstName}},{{LastName}},{{Email}}
   • Active: Check the box
3. Click Save

Testing Your Template

1. Click Edit on your template
2. Expand the "Test Email" section
3. Enter your email address
4. Add sample JSON variables:

   {
     "FirstName": "John",
     "LastName": "Doe",
     "Email": "john@example.com"
   }
   

5. Click "Send Test Email"
6. Check your inbox in 1-2 minutes

---

Documentation

For Site Administrators

• Quick Start Guide - Get started with test email feature
• Complete Module Summary - Full feature overview

For Module Developers

• Integration Guide - Complete API reference and patterns
• Example Integration - Copy-paste ready code examples

Technical Documentation

• Data Model Enhancement - Database schema and migrations
• Rich Text Editor Integration - QuillJS implementation details

---

Using This Module in Your Code

Other Oqtane modules can use this module as a centralized email service!

Simple Example

using Amazing.Module.EmailTemplate.Services;

public class YourModuleService
{
    private readonly IEmailSendingService _emailService;

    public YourModuleService(IEmailSendingService emailService)
    {
        _emailService = emailService;
    }

    public async Task SendWelcomeEmail(User user)
    {
        var variables = new Dictionary<string, string>
        {
            { "FirstName", user.FirstName },
            { "Email", user.Email }
        };

        var result = await _emailService.SendEmailByTemplateNameAsync(
            siteId: user.SiteId,
            templateName: "Welcome Email",
            toEmail: user.Email,
            variables: variables
        );

        if (result.Success)
        {
            _logger.LogInformation("Email sent: {Id}", result.NotificationId);
        }
    }
}

See Integration Guide for complete API documentation!

---

Use Cases

User Management

• Registration welcome emails
• Email verification
• Password reset requests
• Account locked notifications

Ecommerce

• Order confirmations
• Shipping notifications
• Payment receipts
• Refund confirmations

Content Management

• Comment notifications
• Content approval
• Subscription digests
• Newsletter campaigns

Events

• Event registration confirmation
• Event reminders
• Event cancellation
• Post-event surveys

---

Architecture

Technology Stack

• Framework: Oqtane 10.0.4 on .NET 10
• UI: Blazor Server + WebAssembly
• Database: Multi-database support (SQL Server, MySQL, PostgreSQL, SQLite)
• Email: Oqtane Notification System + MailKit
• Editor: Oqtane RichTextEditor (Radzen Blazor HTML Editor or QuillJS)

Module Structure

Amazing.Module.EmailTemplate/
|-- Shared/               # Models and interfaces
|   |-- Models/
|   |   |-- EmailTemplate.cs
|   |   |-- EmailSendResult.cs
|   |   +-- TemplateInfo.cs
|   +-- Services/
|       +-- IEmailSendingService.cs  (Public API)
|
|-- Server/               # Business logic and API
|   |-- Controllers/
|   |   +-- EmailTemplateController.cs
|   |-- Services/
|   |   |-- EmailTemplateService.cs    (Internal)
|   |   +-- EmailSendingService.cs     (Public)
|   +-- Repository/
|       +-- EmailTemplateRepository.cs
|
+-- Client/               # Blazor UI components
    +-- Modules/Amazing.Module.EmailTemplate/
        |-- Index.razor
        +-- Edit.razor

---

Security

Authorization

• View Permission - See template list and preview
• Edit Permission - Create, edit, delete, and send test emails
• Site-Scoped - Templates isolated per site
• Public API - No permission required (authorization in calling module)

Data Protection

• Multi-tenant isolation
• No cross-site email sending
• Audit trail for all operations
• Active/inactive status control

---

Configuration Requirements

Rich Text Editor

This module uses Oqtane's RichTextEditor component, which can be configured to use:

• Radzen Blazor HTML Editor (default in Oqtane 10+) - Modern, feature-rich editor
• QuillJS (legacy option) - JavaScript-based editor

The editor is configured in Admin ? Site Settings ? Advanced Settings ? Rich Text Editor Provider.

Your module will automatically use whichever editor is configured for the site.

SMTP Setup (Required for Email Delivery)

1. Navigate to Admin ? Site Settings ? SMTP Settings
2. Configure:
   • Host: Your SMTP server (e.g., smtp.gmail.com)
   • Port: SMTP port (e.g., 587)
   • SSL: SSL/TLS options
   • Username/Password: SMTP credentials
   • Sender: From email address

NotificationJob (Required)

1. Navigate to Admin ? Scheduled Jobs
2. Find "Notification Job"
3. Set Enabled = Yes
4. Set Frequency = Minute, Interval = 1

---

Database Schema

Table: AmazingEmailTemplate

| Column | Type | Description | |--------|------|-------------| | EmailTemplateId | int | Primary key | | ModuleId | int | Module reference | | Name | nvarchar(100) | Template name | | Subject | nvarchar(200) | Email subject (with variables) | | Body | nvarchar(MAX) | HTML email content | | Category | nvarchar(50) | Template category | | IsActive | bit | Active status | | TemplateVariables | nvarchar(2000) | Available variables | | Description | nvarchar(500) | Template notes | | CreatedBy, CreatedOn, ModifiedBy, ModifiedOn | | Audit fields |

---

Template Variable Syntax

Templates support dynamic content via double-brace variables:

Subject: Welcome {{FirstName}} {{LastName}}!

Body:

<h1>Hello {{FirstName}}!</h1>
<p>Your email address is: {{Email}}</p>
<p>Order #{{OrderNumber}} total: ${{OrderTotal}}</p>

Sample Data (JSON):

{
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "john@example.com",
  "OrderNumber": "12345",
  "OrderTotal": "99.99"
}

Result:

Subject: Welcome John Doe!
Body: 
Hello John!
Your email address is: john@example.com
Order #12345 total: $99.99

---

API Reference

IEmailSendingService Methods

1. SendEmailByTemplateNameAsync (Recommended)

Task<EmailSendResult> SendEmailByTemplateNameAsync(
    int siteId,
    string templateName,
    string toEmail,
    Dictionary<string, string> variables,
    string toDisplayName = null
)

2. SendEmailByTemplateIdAsync

Task<EmailSendResult> SendEmailByTemplateIdAsync(
    int siteId,
    int templateId,
    string toEmail,
    Dictionary<string, string> variables,
    string toDisplayName = null
)

3. GetAvailableTemplatesAsync

Task<List<TemplateInfo>> GetAvailableTemplatesAsync(int siteId)

4. GetTemplatesByCategoryAsync

Task<List<TemplateInfo>> GetTemplatesByCategoryAsync(
    int siteId,
    string category
)

See Integration Guide for detailed API documentation.

---

Testing

Unit Testing

[Fact]
public async Task SendEmail_WithValidTemplate_ReturnsSuccess()
{
    var mockService = new Mock<IEmailSendingService>();
    mockService
        .Setup(s => s.SendEmailByTemplateNameAsync(
            It.IsAny<int>(),
            "Welcome Email",
            It.IsAny<string>(),
            It.IsAny<Dictionary<string, string>>(),
            It.IsAny<string>()
        ))
        .ReturnsAsync(new EmailSendResult 
        { 
            Success = true, 
            NotificationId = 123 
        });

    var service = new YourService(mockService.Object);
    await service.RegisterUser(t