Core.Email.Abstractions 1.1.0

.NET Transactional E-Mail Abstraction Layer

Send transactional e-mail through one ICoreEmail interface and switch providers by configuration. Several providers - or several configurations of the same provider - can be registered side by side as keyed services.

Targets .NET 10.

Packages

dotnet add package Core.Email
dotnet add package Core.Email.Provider.SES

Configuration

appsettings.json - only the providers you register need a section:

{
  "Email": {
    "Default": "Postmark",
    "SMTP": {
      "Host": "smtp.***.com",
      "Port": 587,
      "Username": "***",
      "Password": "***",
      "Tls": true
    },
    "SES": {
      "AccessKey": "***",
      "SecretAccessKey": "***",
      "Region": "eu-central-1"
    },
    "Postmark": {
      "ServerToken": "***",
      "MessageStream": "outbound"
    },
    "Mailjet": {
      "ApiKey": "***",
      "ApiSecret": "***"
    },
    "SendGrid": {
      "ApiKey": "***"
    }
  }
}

• Email:Default is the key of the provider used for messages without a ProviderKey.
• Each provider reads its settings from Email:{key}.

Registration

services.AddCoreEmail();
services.AddSmtpProvider("SMTP");
services.AddPostmarkProvider("Postmark");
services.AddSendGridProvider("SendGrid");
services.AddMailjetProvider("Mailjet");
services.AddSimpleEmailServiceProvider("SES");

The key is free to choose, so one provider can be registered several times:

services.AddPostmarkProvider("Postmark");          // reads Email:Postmark
services.AddPostmarkProvider("PostmarkBroadcast"); // reads Email:PostmarkBroadcast

Without a key (services.AddSmtpProvider()) the provider is registered unkeyed, reads Email:SMTP (or Email:SES, Email:Postmark, ...) and is used as default while Email:Default is not set.

Sending

var email = serviceProvider.GetRequiredService<ICoreEmail>();

var status = await email.SendAsync(new CoreEmailMessage
{
    From = "noreply@example.com",
    FromName = "Example Inc. · Reports", // optional display name
    To = ["jane@example.com"],
    Bcc = ["archive@example.com"],
    ReplyTo = "support@example.com",
    Subject = "Weekly report",
    TextBody = "Your weekly report is attached.",
    HtmlBody = "<p>Your weekly report is attached.</p>",
    Attachments =
    [
        new CoreEmailAttachment
        {
            Name = "report.csv",
            ContentType = "text/csv",
            Content = csvBytes
        }
    ]
});

if (!status.IsSuccess)
    logger.LogWarning("Mail {Id} failed: {Error}", status.Id, status.Error);

• Choose a provider per message with ProviderKey = "SES"; without it the default provider is used.
• Batches: SendAsync(List<CoreEmailMessage>) groups the messages by ProviderKey and hands each group to its provider as one batch. It returns one CoreEmailStatus per message - match them by Id.
• Errors: an unknown ProviderKey throws InvalidOperationException before anything is sent. Rejected messages come back with IsSuccess = false and Error. SMTP, SES and SendGrid also report connection and API exceptions that way; Mailjet and Postmark send the whole batch in one API call, which can throw.
• ProviderMessageId holds the provider's own message id where available (SES, Postmark).

Provider notes

¹ exposed as ICoreEmailProvider.MaxSize for information - not enforced by the library.

Development

dotnet build
dotnet test --filter "Category!=Integration"

EmailTest is an integration test that sends a real e-mail. It needs provider credentials plus TestSetup:From / TestSetup:To in Core.Email.Tests/appsettings.private.json (git-ignored).

License

Apache-2.0