MailerSendNetCore

MailerSend SDK for .NET

This project provides an easy way to interact with the MailerSend API using C# and .NET. It targets .NET 10 (net10.0) and uses Newtonsoft.Json for JSON serialization and deserialization.

This is an unofficial SDK for MailerSend and does not claim to be complete.

Getting Started

To start using this SDK, you will need to install it via NuGet or cloning and adding a reference in your project.

Installation

Install-Package MailerSendNetCore

Usage

Add "MailerSend" section to appsettings.json

  "MailerSend": {
    "ApiUrl": "https://api.mailersend.com/v1",
    "ApiToken": "<your MailerSend api token>",
    "UseRetryPolicy": true,
    "RetryCount": 5,
    "RetryDelayInMilliseconds": 5000
  },

Configure the client using one of the following methods:

//METHOD #1: Read options from configuration (RECOMMENDED)
builder.Services.AddMailerSendEmailClient(builder.Configuration.GetSection("MailerSend"));

//METHOD #2: Set options from configuration manually
builder.Services.AddMailerSendEmailClient(options =>
{
    options.ApiUrl = builder.Configuration["MailerSend:ApiUrl"];
    options.ApiToken = builder.Configuration["MailerSend:ApiToken"];
});

//METHOD #3: Add custom options instance
builder.Services.AddMailerSendEmailClient(new MailerSendEmailClientOptions
{
    ApiUrl = builder.Configuration["MailerSend:ApiUrl"],
    ApiToken = builder.Configuration["MailerSend:ApiToken"]
});

Inject the client into your service, controller or handler

private readonly IMailerSendEmailClient _mailerSendEmailClient;

public EmailService(IMailerSendEmailClient mailerSendEmailClient)
{
    _mailerSendEmailClient = mailerSendEmailClient;
}

Send Emails

public async Task<string> SendEmail(string templateId, string senderName, string senderEmail, string[] to, string subject, MailerSendEmailAttachment[] attachments, IDictionary<string, string>? variables, CancellationToken cancellationToken = default)
{
    var parameters = new MailerSendEmailParameters();
    parameters
        .WithTemplateId(templateId)
        .WithFrom(senderEmail, senderName)
        .WithTo(to)
        .WithAttachment(attachments)
        .WithSubject(subject);

    if (variables is { Count: > 0 })
    {
        foreach (var recipient in to)
        {
            parameters.WithPersonalization(recipient, variables);
        }
    }

    var response = await _mailerSendEmailClient.SendEmailAsync(parameters, cancellationToken);
    if (response is { Errors.Count: > 0 })
    {
        //handle errors                
    }

    return response.MessageId;
}

Attachment disposition (inline / attachment)

MailerSendEmailAttachment supports an optional Disposition value:

• inline for CID-based content (for example embedded images),
• attachment for regular file attachments.

When using inline, provide a non-empty Id so it can be referenced from HTML using cid:<id>.

var parameters = new MailerSendEmailParameters()
    .WithFrom("sender@example.com", "Sender")
    .WithTo("recipient@example.com")
    .WithSubject("Inline image example")
    .WithHtmlBody("<p>Logo:</p><img src=\"cid:logo-company\" />")
    .WithAttachment("logo-company", "logo.png", "<base64content>", "inline")
    .WithAttachment("doc-1", "file.pdf", "<base64content>", "attachment");

Additional Resources

• MailerSend developer site
• Newtonsoft.Json documentation
• .NET documentation