Pixata.Email 2.2.0

Pixata.Email

An email service for use in .NET Core projects. Backed by Mailkit, it eases the effort needed to add email facilities to your project.

A Nuget package is available for this project.

Breaking change

As from version 2.0.0, this package does not use LanguageExt, but returns an ApiResponse from the Pixata.Extensions package to indicate success or failure. See the comments at the bottom of this document for how this will change your code.

Setup

First thing you need to do is add your SMTP server and "From" details to your application. There are a few ways to do this, the most simple of which is to use appSettings.json...

  "Smtp": {
    "Server": "your.smtp.server",
    "Port": 999,
    "UseSsl": "true",
    "UserName": "your.username",
    "Password": "your.password",
    "FromEmail": "jim@spriggs.com",
    "FromName": "Jim Spriggs"
  }

Unless your name is Jim Spriggs, you'll need to change these to you own name and server settings!

Then add the following lines...

// .NET5 - Goes in Startup.cs
SmtpSettings smtpSettings = Configuration.GetSection("Smtp").Get<SmtpSettings>();
services.AddSingleton(smtpSettings);
services.AddTransient<PixataEmailService>();

// .NET6+ - Goes in Program.cs
SmtpSettings smtpSettings = builder.Configuration.GetSection("Smtp").Get<SmtpSettings>();
builder.Services.AddSingleton(smtpSettings);
builder.Services.AddTransient<PixataEmailService>();

This allows you to inject an instance of PixataEmailService into your code as usual, and it will have the settings baked in for you.

If you store your mail settings in secrets, environmental variables, etc, then you'll need to retrieve them from there and set up an instance of SmtpSettings from that.

If you are into interfaces, you can register that instead...

services.AddTransient<PixataEmailServiceInterface, PixataEmailService>();

Allowing multiple email servers or accounts

Note that this feature is only available from v1.2.4 onwards

If you need to be able to send emails from multiple servers or accounts, you can set up a default SmtpSettings as above, and then when you want to send from a different server or account, just change the SmtpSettings property on the service to use the appropriate settings...

SmtpSettings myStmpSettings = // Pick them up from wherever you store them
_emailService.SmtpSettings = myStmpSettings;

Usage

There are two overloads of the SendEmail method. Easiest to use is a simple one that just takes the recipient's email address, the subject and the HTML body...

(await _emailService.SendEmailAsync("billy@shears.com", "Hello from Jim Spriggs", htmlBody)))
  .Match(_ => /* code on success */, ex => /* code on failure */);

If you want more control over what is sent and how, the second overload takes an EmailParameters object. The various constructors allow you to specify more detail, as well as adding multiple recipients. You can also add attachments, which are tuples of the form (string FileName, string MimeType, byte[] Data).

See the EmailParameters code for more details.

Breaking change in version 2.0.0

As from version 2.0.0, the service uses an ApiResponse from the Pixata.Extensions package to indicate success or failure. Previous versions used LanguageExt, which has now been removed from this package.

If you are upgrading from a LanguageExt version, then you will need to change the code in the failure lambda. The LanguageExt version passed in a System.Exception, whereas the new version passes a string containing the error message. For example, you would change...

(await _emailService.SendEmailAsync("billy@shears.com", "Hello from Jim Spriggs", htmlBody)))
  // Note that ex is an Exception, so we need to use the Message property to get the details
  .Match(_ => /* code on success */, ex => Console.WriteLine(ex.Message));

...to...

(await _emailService.SendEmailAsync("billy@shears.com", "Hello from Jim Spriggs", htmlBody)))
  // Note that we use ex directly, as it is a string, not an Exception, so we don't have a Message property
  .Match(_ => /* code on success */, ex => Console.WriteLine(ex));

You will need also to make sure you wrap the first line in brackets (as shown above). This was not necessary before.

If your code captures the return value from SendEmailAsync in a local variable, then you will need to add a using statement for Pixata.Email and change the type of the variable from TryAsync<Unit> to ApiResponse<Yunit> (unless you use var in which case the compiler will correctly infer the return type). However, this is not a common pattern when using this service.