Skip to content

dimesoftware/facteur

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

66 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Logo

Facteur

Facteur (French for mailman) is a library for sending emails in .NET. Its modular approach allows you to assemble a mail system rather than having to use a take-it-or-leave it service.

Check out the 📚 docs » for more info.

About the project

The entire premise of this project is to provide a flexible and modular mailing and templating kit. Applications should not be bound by one specific mailing service; like when you get blacklisted by a mailing service or when the performance is unacceptable, you should be able to swap providers without having to modify a single line of code.

This is why we created Facteur. The desire to create a flexible and vendor-independent framework is clearly reflected in the library's architecture.

There are a few moving parts:

  • Composers
  • Compilers
  • Resolvers
  • Template providers
  • Endpoints

Composers enable you to create an email request, which contains the email variables like subject, body and the email addresses to send the mail to.

Compilers are a part of the email composition in that it allows to fetch a template and populate the email body with data from a custom view model.

The templates can be stored anywhere. By default they are stored in the folder where the application is hosted but it can also be retrieved from an Azure blob, FTP drive, etc. Using template providers and resolvers, you can write your own logic to fetch the right template for the job.

Lastly and obviously, there are the various mail services, also known as endpoints in Facteur. emails can be sent with good old SMTP, Microsoft Graph API, SendGrid, etc.

Installation

Use the package manager NuGet to install the base library of Facteur:

dotnet add package Facteur

Next it is up to you to decide which endpoint you want to use:

Service Command
Microsoft Graph API dotnet add package Facteur.MsGraph
SMTP dotnet add package Facteur.Smtp
SendGrid dotnet add package Facteur.SendGrid

Next, you should decide which compiler to use to generate the body of your email. The following packages are available:

Resolvers Command
Scriban dotnet add package Facteur.Compilers.Scriban

You also have a choice in the template providers. Templates can be stored on a regular file drive but it might as well be stored on a blob on Azure.

Providers Command
IO dotnet add package Facteur.TemplateProviders.IO

The resolvers are the glue between the storage of templates and the runtime. Resolvers enable you to map templates to models.

Resolvers Command
View dotnet add package Facteur.Resolvers.ViewModel

Finally, there are some ancillary packages:

Purpose Command
.NET Core DI dotnet add package Facteur.Extensions.DependencyInjection

Configuration

With .NET's dependency injection, hooking up the mailer can be done by adding a few lines to the Startup class:

serviceCollection.AddFacteur(x =>
{
    x.WithMailer(y => new SmtpMailer(credentials, y.GetService<IEmailComposer>()))
    .WithCompiler<ScribanCompiler>()
    .WithTemplateProvider(x => new AppDirectoryTemplateProvider("Templates", ".sbnhtml"))
    .WithResolver<ViewModelTemplateResolver>()
    .WithDefaultComposer();
});

Usage

The power of this project is to create a dynamic mail body as you can populate any template with any type of data. This is when the compilers, providers and resolvers come in. They can be produced using the implementation of IEmailCompiler, which orchestrates the process of retrieving and populating the template. It is ultimately up to the instance of the IMailer to actually send the email.

public async Task SendConfirmationMail(string customerMail, string customerName)
{
  EmailComposer composer = new(
    new ScribanCompiler(),
    new AppDirectoryTemplateProvider("Templates", ".sbnhtml"),
    new ViewModelTemplateResolver());

  EmailRequest request = await composer      
      .SetSubject("Hello world")
      .SetFrom("info@facteur.com")
      .SetTo("guy.gadbois@facteur.com")
      .SetCc("jacques.clouseau@facteur.com")
      .SetBcc("charles.dreyfus@facteur.com")
      .BuildAsync(new TestMailModel { Email = customerMail, Name = customerMail });

  SmtpCredentials credentials = new("smtp.gmail.com", "587", "false", "true", "myuser@gmail.com", "mypassword");
  IMailer mailer = new SmtpMailer(credentials);
  await mailer.SendMailAsync(request);
}

If you use DI, you can just use IMailer and use the overload that exposes the composer:

public async Task SendConfirmationMail(string customerMail, string customerName)
{
  await mailer.SendMailAsync(x =>  x      
      .SetSubject("Hello world")
      .SetFrom("info@facteur.com")
      .SetTo("guy.gadbois@facteur.com")
      .SetCc("jacques.clouseau@facteur.com")
      .SetBcc("charles.dreyfus@facteur.com")
      .BuildAsync(new TestMailModel { Email = customerMail, Name = customerMail }));
}

This particular example uses scriban templates that are stored inside the application's directory. Inside the HTML template, you will find scriban syntax:

<p>Hi {{name}},</p>

This text template is resolved using the model that is passed to the EmailRequest instance, which in this sample is of the TestMailModel type:

public class TestMailModel
{
  public string Name { get; set; }
  public string Email { get; set; }
}

The resolver is responsible for locating the right file name. In this example, the ViewModelTemplateResolver is used. This class essentially strips the 'MailModel' or 'ViewModel' of the name of the mail request's model. After that, the provider (AppDirectoryTemplateProvider) will make the system to look for file in the application's Templates directory with the .sbnhtml file and with the name 'Test' (from TestMailModel).

The IEmailComposer brings everything together and generates a populated mail body. Then it's up to the ÃŒMailer to merely send the mail.

Contributing

Pull requests are welcome. Please check out the contribution and code of conduct guidelines.

License