Orchardcore Email

OrchardCore.Email Module

The OrchardCore.Email module provides email functionality for Orchard Core applications. It supports multiple email providers, Liquid-based templates for dynamic content, workflow integration, and both admin UI and recipe-based configuration.

Email Providers

Orchard Core ships with built-in support for the following email providers:

• SMTP (MailKit) — Uses MailKitSmtpService to deliver messages through any standard SMTP server.
• Azure Communication Services — Sends email through the Azure Communication Services Email API using the OrchardCore.Email.Azure module.

Enable the relevant feature depending on your provider:

• OrchardCore.Email — Core email abstractions and admin settings.
• OrchardCore.Email.Smtp — SMTP delivery via MailKit.
• OrchardCore.Email.Azure — Azure Communication Services delivery.

Configuring SMTP Settings

Via Admin UI

Navigate to Configuration → Settings → Email in the admin dashboard. The SMTP settings section allows you to specify:

Via Recipe

Configure SMTP settings declaratively using a Settings recipe step targeting SmtpSettings:

{
  "steps": [
    {
      "name": "Settings",
      "SmtpSettings": {
        "DefaultSender": "noreply@example.com",
        "Host": "smtp.example.com",
        "Port": 587,
        "EncryptionMethod": "STARTTLS",
        "AutoSelectEncryption": false,
        "RequireCredentials": true,
        "UserName": "smtp-user",
        "Password": "smtp-password",
        "ProxyHost": null,
        "ProxyPort": 0
      }
    }
  ]
}

Via Configuration Provider

SMTP settings can also be supplied through appsettings.json or environment variables using the OrchardCore_Email_Smtp configuration section:

{
  "OrchardCore_Email_Smtp": {
    "DefaultSender": "noreply@example.com",
    "Host": "smtp.example.com",
    "Port": 587,
    "EncryptionMethod": "STARTTLS",
    "RequireCredentials": true,
    "UserName": "smtp-user",
    "Password": "smtp-password"
  }
}

Configuring Azure Communication Services Email

Enable the OrchardCore.Email.Azure feature, then configure settings in the admin under Configuration → Settings → Email → Azure Communication Services, or via configuration:

{
  "OrchardCore_Email_Azure": {
    "DefaultSender": "DoNotReply@your-azure-domain.azurecomm.net",
    "ConnectionString": "endpoint=https://your-resource.communication.azure.com/;accesskey=YOUR_ACCESS_KEY"
  }
}

Or supply the connection string as a recipe step:

{
  "steps": [
    {
      "name": "Settings",
      "AzureEmailSettings": {
        "DefaultSender": "DoNotReply@your-azure-domain.azurecomm.net",
        "ConnectionString": "endpoint=https://your-resource.communication.azure.com/;accesskey=YOUR_ACCESS_KEY"
      }
    }
  ]
}

Sending Emails Programmatically

Using ISmtpService

Inject ISmtpService to send emails from custom code. Build a MailMessage and call SendAsync:

using Microsoft.Extensions.Localization;
using OrchardCore.Email;

public sealed class OrderConfirmationService
{
    private readonly ISmtpService _smtpService;
    private readonly IStringLocalizer S;

    public OrderConfirmationService(
        ISmtpService smtpService,
        IStringLocalizer<OrderConfirmationService> stringLocalizer)
    {
        _smtpService = smtpService;
        S = stringLocalizer;
    }

    public async Task<SmtpResult> SendOrderConfirmationAsync(
        string recipientEmail,
        string orderId)
    {
        var message = new MailMessage
        {
            To = recipientEmail,
            Subject = S["Order Confirmation - {0}", orderId].Value,
            Body = $"<p>Your order <strong>{orderId}</strong> has been confirmed.</p>",
            IsHtmlBody = true
        };

        return await _smtpService.SendAsync(message);
    }
}

Register the service in your module's Startup:

using Microsoft.Extensions.DependencyInjection;
using OrchardCore.Modules;

public sealed class Startup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddScoped<OrderConfirmationService>();
    }
}

Checking the Result

SmtpResult indicates whether the send operation succeeded:

var result = await _smtpService.SendAsync(message);

if (!result.Succeeded)
{
    foreach (var error in result.Errors)
    {
        logger.LogError("Email send failed: {Error}", error.Value);
    }
}

MailMessage Properties

The MailMessage class exposes these key properties:

Sending with Attachments

public sealed class ReportEmailService
{
    private readonly ISmtpService _smtpService;

    public ReportEmailService(ISmtpService smtpService)
    {
        _smtpService = smtpService;
    }

    public async Task<SmtpResult> SendReportAsync(
        string recipientEmail,
        string reportName,
        Stream reportStream)
    {
        var message = new MailMessage
        {
            To = recipientEmail,
            Subject = $"Report: {reportName}",
            Body = "<p>Please find the attached report.</p>",
            IsHtmlBody = true
        };

        message.Attachments.Add(new MailMessageAttachment
        {
            Filename = $"{reportName}.pdf",
            Stream = reportStream
        });

        return await _smtpService.SendAsync(message);
    }
}

Liquid Email Templates

Orchard Core's Liquid integration allows you to build dynamic email bodies. Use ILiquidTemplateManager to render templates before sending:

using OrchardCore.Liquid;
using OrchardCore.Email;

public sealed class TemplatedEmailService
{
    private readonly ISmtpService _smtpService;
    private readonly ILiquidTemplateManager _liquidTemplateManager;

    public TemplatedEmailService(
        ISmtpService smtpService,
        ILiquidTemplateManager liquidTemplateManager)
    {
        _smtpService = smtpService;
        _liquidTemplateManager = liquidTemplateManager;
    }

    public async Task<SmtpResult> SendWelcomeEmailAsync(
        string recipientEmail,
        string userName)
    {
        var template = @"
<h1>Welcome, {{ UserName }}!</h1>
<p>Thank you for registering on our site.</p>
<p>Your account is now active and ready to use.</p>
";

        var model = new { UserName = userName };
        var body = await _liquidTemplateManager.RenderStringAsync(
            template,
            System.Text.Encodings.Web.HtmlEncoder.Default,
            model);

        var message = new MailMessage
        {
            To = recipientEmail,
            Subject = $"Welcome, {userName}!",
            Body = body,
            IsHtmlBody = true
        };

        return await _smtpService.SendAsync(message);
    }
}

Liquid Syntax in Email Templates

Common Liquid constructs for email templates:

• Variable output: {{ Model.PropertyName }}
• Conditionals: {% if Model.IsVip %} ... {% endif %}
• Loops: {% for item in Model.Items %} ... {% endfor %}
• Filters: {{ Model.Date | date: "%B %d, %Y" }}
• Content items: {% contentitem id: Model.ContentItemId, assign_model: "item" %}

Email Workflow Activities

When the OrchardCore.Email feature is enabled alongside OrchardCore.Workflows, a Send Email activity becomes available in the workflow editor.

Send Email Activity Properties

In workflow Liquid expressions, access the current workflow context with {{ Workflow }} and the triggering content item with {{ ContentItem }}.

Example Workflow: Notify Admin on Content Publication

Create a workflow that sends an email when a content item is published:

1. Add a Content Published Event as the starting activity.
2. Connect it to a Send Email activity with:
   • Recipients: admin@example.com
   • Subject: Content Published: {{ ContentItem.DisplayText }}
   • Body:

     <p>The content item <strong>{{ ContentItem.DisplayText }}</strong> of type
     <em>{{ ContentItem.ContentType }}</em> was published.</p>
     <p>Published by: {{ Workflow.Input.Owner }}</p>
     

Email Notification Events

Orchard Core raises email-related events that modules can hook into. Implement IEmailNotificationEvents or listen for specific email notification events to customize behavior before or after emails are sent.

Custom Email Event Handler

using OrchardCore.Email;
using OrchardCore.Email.Events;

public sealed class EmailAuditHandler : IEmailNotificationEvents
{
    private readonly ILogger<EmailAuditHandler> _logger;

    public EmailAuditHandler(ILogger<EmailAuditHandler> logger)
    {
        _logger = logger;
    }

    public Task SendingAsync(MailMessage message)
    {
        _logger.LogInformation(
            "Sending email to {Recipients} with subject '{Subject}'.",
            message.To,
            message.Subject);

        return Task.CompletedTask;
    }

    public Task SentAsync(MailMessage message)
    {
        _logger.LogInformation(
            "Email sent to {Recipients} successfully.",
            message.To);

        return Task.CompletedTask;
    }

    public Task FailedAsync(MailMessage message)
    {
        _logger.LogWarning(
            "Failed to send email to {Recipients}.",
            message.To);

        return Task.CompletedTask;
    }
}

Register the handler:

using Microsoft.Extensions.DependencyInjection;
using OrchardCore.Email.Events;
using OrchardCore.Modules;

public sealed class Startup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddScoped<IEmailNotificationEvents, EmailAuditHandler>();
    }
}

Testing Email Configuration

Use the admin Email Test page at Configuration → Settings → Email → Test to send a test message. This validates that SMTP or Azure Communication Services settings are correctly configured.

Troubleshooting