MailerSend SDK for .NET

https://github.com/yanezricardo/mailersendnetcore
Admin
MailerSend SDK for .NET is an unofficial client library that provides an easy way to interact with...
Tokens:6,626
Snippets:47
Trust Score:7.1
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install MailerSendNetCore via NuGet

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/README.md

Installs the MailerSendNetCore NuGet package into the project.

```powershell
Install-Package MailerSendNetCore
```

--------------------------------

### Configure MailerSend client with AddMailerSendEmailClient

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/README.md

Three ways to configure the MailerSend email client in DI. Method #1 reads from the "MailerSend" configuration section and is recommended; methods #2 and #3 set options manually.

```csharp
//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"]
});
```

--------------------------------

### Enable package validation

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/docs/plan-mailersendnetcore-0.3.0.md

Enable .NET SDK Package Validation against published version 0.2.0. Run baseline validation in compatibility mode, not strict equality mode.

```xml
<EnablePackageValidation>true</EnablePackageValidation>
<PackageValidationBaselineVersion>0.2.0</PackageValidationBaselineVersion>
```

--------------------------------

### Send email with inline and attachment dispositions

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/README.md

Creates email parameters with inline and attachment dispositions. For inline, provide a non-empty Id (e.g., "logo-company") to reference via cid:<id> in HTML; attachment is for regular file attachments.

```csharp
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");
```

--------------------------------

### Final validation commands

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/docs/plan-mailersendnetcore-0.3.0.md

Run these commands in order to validate the MailerSendNetCore solution: restore, build, test, check for deprecated and vulnerable packages, pack the release artifact, and verify no uncommitted changes.

```bash
dotnet restore MailerSendNetCore.sln --configfile nuget.config
dotnet build MailerSendNetCore.sln --configuration Release --no-restore
dotnet test MailerSendNetCore.sln --configuration Release --no-build
dotnet package list \
  --project src/MailerSendNetCore/MailerSendNetCore.csproj \
  --include-transitive \
  --deprecated
dotnet package list \
  --project src/MailerSendNetCore/MailerSendNetCore.csproj \
  --include-transitive \
  --vulnerable
dotnet pack src/MailerSendNetCore/MailerSendNetCore.csproj \
  --configuration Release \
  --no-build \
  --output artifacts
git diff --check
```

--------------------------------

### Inject IMailerSendEmailClient into a service

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/README.md

Inject IMailerSendEmailClient into a service, controller, or handler via constructor injection.

```csharp
private readonly IMailerSendEmailClient _mailerSendEmailClient;

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

--------------------------------

### Expected dependency graph

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/docs/plan-mailersendnetcore-0.3.0.md

Expected dependency graph after applying the technical decisions for the 0.3.0 release. It confirms the removal of deprecated packages and the retention of Polly 8.

```text
Microsoft.Extensions.Http.Polly: absent
Polly.Extensions.Http: absent
Polly 8: retained
Deprecated packages: zero
Known vulnerabilities: zero
```

--------------------------------

### Handle accepted responses and suppressions

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/README.md

Handles 202 Accepted responses with warning details. IsSuppressed indicates ALL_SUPPRESSED (no message queued, MessageId absent); WarningItems contains the complete response collection for SOME_SUPPRESSED. The legacy Warnings property remains available and contains the first warning.

```csharp
var response = await _mailerSendEmailClient.SendEmailAsync(parameters, cancellationToken);

if (response.IsSuppressed)
{
    // ALL_SUPPRESSED: no message was queued and MessageId is absent.
}
else if (response.WarningItems.Count > 0)
{
    // SOME_SUPPRESSED: inspect all warning details.
}

if (response.IsQueued)
{
    Console.WriteLine(response.MessageId);
}
```

--------------------------------

### Add MailerSend section to appsettings.json

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/README.md

Configuration section for the MailerSend client. UseRetryPolicy=false is recommended unless the application explicitly accepts the retry trade-off; enabling retries can duplicate email delivery on transient failures.

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

--------------------------------

### Centralize provider warning types

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/docs/plan-mailersendnetcore-0.3.0.md

Internal static class to centralize provider warning type constants. Compare with StringComparison.OrdinalIgnoreCase.

```csharp
internal static class MailerSendWarningTypes
{
    public const string SomeSuppressed = "SOME_SUPPRESSED";
    public const string AllSuppressed = "ALL_SUPPRESSED";
}
```

--------------------------------

### Add new response properties

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/docs/plan-mailersendnetcore-0.3.0.md

Add these properties to the response class. WarningItems supports object initialization and serializer construction while storing a defensive read-only snapshot. IsQueued is true only when MessageId exists. IsSuppressed is true when WarningItems contains ALL_SUPPRESSED. HasErrors is true when Errors is not empty.

```csharp
private IReadOnlyList<MailerSendEmailWarningResponse> _warningItems =
    Array.Empty<MailerSendEmailWarningResponse>();

public IReadOnlyList<MailerSendEmailWarningResponse> WarningItems
{
    get => _warningItems;
    init => _warningItems = Array.AsReadOnly(
        (value ?? Array.Empty<MailerSendEmailWarningResponse>()).ToArray());
}

public bool IsQueued { get; }
public bool IsSuppressed { get; }
public bool HasErrors { get; }
```

--------------------------------

### Add exception properties

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/docs/plan-mailersendnetcore-0.3.0.md

Add these properties to ApiException. Do not add an exception hierarchy. Caller cancellation must remain OperationCanceledException.

```csharp
public HttpStatusCode HttpStatusCode { get; }
public TimeSpan? RetryAfter { get; }
public bool IsTransient { get; }
```

--------------------------------

### Keep unchanged response properties

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/docs/plan-mailersendnetcore-0.3.0.md

These properties must remain unchanged in the response class to maintain compatibility.

```csharp
public string? MessageId { get; set; }
public string? Message { get; set; }
public IDictionary<string, string[]>? Errors { get; set; }
public MailerSendEmailWarningResponse? Warnings { get; set; }
```

--------------------------------

### Send email with MailerSendEmailParameters

Source: https://github.com/yanezricardo/mailersendnetcore/blob/master/README.md

Sends an email using MailerSendEmailParameters with template, sender, recipients, attachments, subject, and optional personalization variables. Handles validation errors (422) and returns the response MessageId.

```csharp
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.HasErrors)
    {
        // Handle the existing 422 validation response.
    }

    return response.MessageId;
}
```
Tokens:
Raw