Structr
Search
K
Comment on page

Email

Structr.Email package is intended to help sending email notifications.

Installation

Email package is available on NuGet.
dotnet add package Structr.Email

Setup

Setup basic email service:
// Configure email address.
services.AddEmail("[email protected]")
/* Setup one of email clients here. */;
// Configure email address of a sender with name and email templates root directory path.
services.AddEmail(new EmailAddress("[email protected]", "Example"), options => {
options.TemplateRootPath = "C:\\Templates";
})
/* Setup one of email clients here. */;
AddEmail() extension method performs registration email service IEmailSender. Additionally configure IEmailSender service used EmailOptions class. EmailOptions properties:
Property name
Property type
Description
From
EmailAddress
Email address of a sender. Required option, which configuring with AddEmail() method.
TemplateRootPath
string?
Root directory path with email templates (needed if using email templates), default value is null.
Email service uses different email clients. For example: File-client, SMTP-client, clients for cloud-based email delivery platform (like SendGrid, MailChimp etc.) or something else. You can use one of default implemented email client from list:

SMTP-client

An SMTP-client allows sending of email notifications using a SMTP server. Setup email service with SMTP-client:
services.AddEmail("[email protected]")
.AddSmtpClient(host: "127.0.0.1", port: 25, options => {
options.User = "user";
options.Password = "password";
options.IsSslEnabled = true;
});
Additionally configure SMTP-client used SmtpOptions class. SmtpOptions properties:
Property name
Property type
Description
Host
string
Domain name or IP address (IPv4) of the host used for SMTP transactions. Required option, which configuring with AddSmtpClient() method.
Port
int
Port used for SMTP transactions. Required option, which configuring with AddSmtpClient() method, default value is 25.
User
string?
User name used to authenticate a sender, default value is null.
Password
string?
User password used to authenticate a sender, default value is null.
IsSslEnabled
bool
Specify whether the SMTP-client uses SSL to encrypt a connection, default value is false.

File-client

An File-client allows preserving of email notifications to file system. This behavior can be useful in development environment for example. Setup email service with File-client:
services.AddEmail("[email protected]")
.AddFileClient("C:\\Emails"); // All sending emails preserves in "C:\\Emails" directory.
You also can use clients depending on the environment. For example you can use File-client for development environment and SMTP-client for production environment.
EmailServiceBuilder builder = services.AddEmail("[email protected]");
#if DEBUG
builder.AddFileClient("C:\\Emails");
#else
builder.AddSmtpClient(host: "127.0.0.1", port: 25);
#endif

Usage

After setup you can inject IEmailSender service and use it for sending email notifications:
public class ReportService : IReportService
{
private readonly IDbContext _dbContext;
private readonly IEmailSender _emailSender;
public ReportService(IDbContext dbContext, IEmailSender emailSender)
{
_dbContext = dbContext;
_emailSender = emailSender;
}
public async Task<bool> SendReportAsync(int userId, string subject, string message, string reportFilePath)
{
var to = await _dbContext.Users
.Where(x => x.Id == userId)
.Select(x => x.Email)
.SingleOrDefaultAsync();
var emailMessage = new EmailMessage(to, message)
{
Subject = subject,
Attachments = new[] {
new EmailAttachment(reportFilePath, "text/html")
}
};
return await _emailSender.SendEmailAsync(emailMessage);
}
}

Templates

You can use EmailTemplateMessage, EmailTemplateFileMessage classes to sending email notifications generating via templates. By default templates constructing via "{{" and "}}", for example "{{UserName}}".
Example of using dynamic template:
// Define Model class for template.
class Recipient
{
public string Name { get; set; }
}
// Create instance of Model class.
var model = new Recipient { Name = "Peter Parker" };
// Create message
var message = new EmailTemplateMessage("[email protected]", "Hello, {{Name}}!", model);
// Send email notification with text "Hello, Peter Parker!".
await _emailSender.SendEmailAsync(message);
Example of using static template:
// Define Model class for template.
class Recipient
{
public string Name { get; set; }
}
// Define static template
class RecipientEmailTemplateMessage : EmailTemplateMessage<Recipient>
{
public override string Template => "Hello, {{Name}}!";
public RecipientEmailTemplateMessage(string to, Recipient model)
: base(new EmailAddress(to), model)
{}
}
// Create instance of Model class.
var model = new Recipient { Name = "Peter Parker" };
// Create message
var message = new RecipientEmailTemplateMessage("[email protected]", model);
// Send email notification with text "Hello, Peter Parker!".
await _emailSender.SendEmailAsync(message);
See example of using template file in Razor section.
Last modified 1yr ago