Regira Office.Mail provides a unified abstraction for sending email through multiple providers. All implementations share the same IMailService interface, making mail backends interchangeable in consuming code.
| Project | Package | Backend |
|---|---|---|
Common.Office |
(transitive) | Shared abstractions, models, and DummyMailer |
Mail.SendGrid |
Regira.Office.Mail.SendGrid |
SendGrid API |
Mail.MailGun |
Regira.Office.Mail.MailGun |
Mailgun REST API |
Mail.MailKit |
Regira.Office.Mail.MailKit |
Any SMTP server, through MailKit |
Mail.Web |
Regira.Office.Mail.Web |
HTTP request DTOs for mail endpoints |
Mail.MSGReader |
Regira.Office.Mail.MSGReader |
Read existing .msg and .eml files |
Security.Authentication.Web |
Regira.Security.Authentication.Web |
IdentityMailer bridge to ASP.NET Identity’s IEmailSender |
<!-- SendGrid -->
<PackageReference Include="Regira.Office.Mail.SendGrid" Version="6.*" />
<!-- Mailgun -->
<PackageReference Include="Regira.Office.Mail.MailGun" Version="6.*" />
<!-- MailKit (SMTP) -->
<PackageReference Include="Regira.Office.Mail.MailKit" Version="6.*" />
<!-- Mail.Web -->
<PackageReference Include="Regira.Office.Mail.Web" Version="6.*" />
<!-- Mail.MSGReader -->
<PackageReference Include="Regira.Office.Mail.MSGReader" Version="6.*" />
<!-- IdentityMailer (ASP.NET Identity integration) -->
<PackageReference Include="Regira.Security.Authentication.Web" Version="6.*" />
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Regira.Office.Mail.SendGrid.DependencyInjection; // AddSendGrid
using Regira.Office.Mail.MailGun.DependencyInjection; // AddMailGun
using Regira.Office.Mail.MailKit.DependencyInjection; // AddMailKit
using Regira.Office.Mail.Abstractions; // IMailService
using Regira.Office.Mail.Models; // MailAddress, MailRecipient
IServiceCollection services = new ServiceCollection();
IConfiguration configuration = new ConfigurationBuilder().Build();
// Register (pick one)
services.AddSendGrid(cfg => cfg.Key = configuration["Mail:SendGrid:Key"]!);
// or
services.AddMailGun(cfg =>
{
cfg.Api = configuration["Mail:MailGun:Api"]!;
cfg.Key = configuration["Mail:MailGun:Key"]!;
cfg.Domain = configuration["Mail:MailGun:Domain"]!;
});
// or
services.AddMailKit(cfg =>
{
cfg.Host = configuration["Mail:Smtp:Host"]!;
cfg.UserName = configuration["Mail:Smtp:UserName"];
cfg.Password = configuration["Mail:Smtp:Password"];
});
// Use — the parameters are interface-typed, so construct the concrete models
// (the implicit string conversions don't apply to IMailAddress/IMailRecipient)
IMailService mailer = services.BuildServiceProvider().GetRequiredService<IMailService>();
await mailer.Send(
sender: new MailAddress { Email = "no-reply@example.com" },
recipients: [new MailRecipient { Email = "alice@example.com" }],
subject: "Hello",
message: "<p>Hi!</p>"
);
Every sending backend implements this interface.
// Parameter-based overload
Task<IMailResponse> Send(
IMailAddress sender,
IEnumerable<IMailRecipient> recipients,
string? subject,
string? message,
bool isHtml = true,
IEnumerable<INamedFile>? attachments = null,
CancellationToken cancellationToken = default);
// Full message overload
Task<IMailResponse> Send(IMessageObject message, CancellationToken cancellationToken = default);
| Property | Type | Description |
|---|---|---|
Success |
bool |
true whenever a sending backend’s Send returns: SendGrid, Mailgun and MailKit throw MailException on a refusal instead. DummyMailer returns false |
Status |
string? |
HTTP status code or provider status text; OK for SMTP |
Content |
string? |
Raw response body; for SMTP the server’s reply, with its queue id (2.0.0 Ok: queued as …) |
Exception |
Exception? |
Not set by the shipped backends, which throw instead |
Represents a complete outgoing email.
| Property | Type | Default | Description |
|---|---|---|---|
From |
MailAddress? |
null |
Sender address |
To |
ICollection<MailRecipient> |
[] |
Recipients (To / Cc / Bcc) |
ReplyTo |
IMailAddress? |
null |
Reply-To address |
Subject |
string? |
null |
Email subject |
Body |
string? |
null |
Message body |
IsHtml |
bool |
true |
HTML vs plain text |
Attachments |
ICollection<BinaryFileItem>? |
null |
File attachments |
MessageObject exposes the concrete model types shown above; the interface-typed members of
IMessageObject (IMailAddress? From, ICollection<IMailRecipient> To, ICollection<INamedFile>? Attachments)
are implemented explicitly and convert to/from the concrete types.
| Property | Type | Description |
|---|---|---|
Email |
string |
Email address — validated on assignment |
DisplayName |
string? |
Optional display name |
MailAddress supports implicit conversion from string:
using Regira.Office.Mail.Models; // MailAddress, MailRecipient
MailAddress addr = "alice@example.com";
MailAddress named = new() { Email = "alice@example.com", DisplayName = "Alice" };
ToString() returns "Alice <alice@example.com>" when DisplayName is set, or just the email.
Extends IMailAddress with a recipient type.
public enum RecipientTypes { To, Cc, Bcc }
using Regira.Office.Mail.Models; // MailAddress, MailRecipient, RecipientTypes
MailRecipient to = "alice@example.com"; // implicit — defaults to RecipientTypes.To
var cc = new MailRecipient { Email = "bob@example.com", RecipientType = RecipientTypes.Cc };
var bcc = new MailRecipient { Email = "carol@example.com", RecipientType = RecipientTypes.Bcc };
| Property | Type | Description |
|---|---|---|
Key |
string |
SendGrid API key |
| Property | Type | Description |
|---|---|---|
Api |
string |
Mailgun API endpoint (e.g. https://api.mailgun.net/v3) |
Key |
string |
Mailgun API key |
Domain |
string |
Sending domain |
TestMode |
bool |
Sends with Mailgun’s o:testmode flag. Default false. |
With TestMode enabled, Mailgun validates, accepts and logs each call exactly as it would a real one, but
never delivers it to the recipient. The response is a normal success, so code and tests that check
response.Success are unaffected. Note that it suppresses delivery, not billing — message counts and
charges may still apply.
| Property | Type | Default | Description |
|---|---|---|---|
Host |
string |
— | SMTP server host name |
Port |
int |
587 |
SMTP port |
Security |
SecureSocketOptions |
StartTls |
MailKit’s TLS mode (MailKit.Security); binds from configuration by name |
UserName |
string? |
null |
SMTP AUTH user — leave empty for a server that takes mail without AUTH |
Password |
string? |
null |
SMTP AUTH password |
Timeout |
int |
120000 |
Per SMTP command, in milliseconds |
| Server | Port |
Security |
|---|---|---|
| Submission with STARTTLS — Microsoft 365, Gmail (app password), Amazon SES, most providers | 587 |
StartTls |
| Implicit TLS | 465 |
SslOnConnect |
| Local test server without TLS — Mailpit, smtp4dev | 1025 / 25 |
None |
The StartTls default fails the send when a server offers no TLS. MailKit’s Auto would fall back to an
unencrypted connection and send the password in clear text, so keep StartTls or SslOnConnect for any remote
server. Each send opens its own connection — connect, authenticate, send, quit — which suits transactional
mail; a bulk send pays one TCP, TLS and AUTH handshake per message. OAuth2 sign-in is not supported.
using Regira.Office.Mail.SendGrid.DependencyInjection; // AddSendGrid
using Regira.Office.Mail.MailGun.DependencyInjection; // AddMailGun
using Regira.Office.Mail.MailKit.DependencyInjection; // AddMailKit
using MailKit.Security; // SecureSocketOptions
IServiceCollection services = new ServiceCollection();
// SendGrid
services.AddSendGrid(cfg => cfg.Key = "SG.xxx");
// Mailgun
services.AddMailGun(cfg =>
{
cfg.Api = "https://api.mailgun.net/v3";
cfg.Key = "key-xxx";
cfg.Domain = "mail.example.com";
});
// Mailgun, accepted and logged but never delivered — for staging hosts and test suites
// that send to real addresses
services.AddMailGun(cfg =>
{
cfg.Api = "https://api.mailgun.net/v3";
cfg.Key = "key-xxx";
cfg.Domain = "mail.example.com";
cfg.TestMode = true;
});
// MailKit — SMTP submission on port 587 with STARTTLS
services.AddMailKit(cfg =>
{
cfg.Host = "smtp.example.com";
cfg.UserName = "mailer@example.com";
cfg.Password = "app-password";
});
// MailKit — implicit TLS on port 465
services.AddMailKit(cfg =>
{
cfg.Host = "smtp.example.com";
cfg.Port = 465;
cfg.Security = SecureSocketOptions.SslOnConnect;
cfg.UserName = "mailer@example.com";
cfg.Password = "app-password";
});
// MailKit — a local Mailpit without TLS or AUTH, for development
services.AddMailKit(cfg =>
{
cfg.Host = "localhost";
cfg.Port = 1025;
cfg.Security = SecureSocketOptions.None;
});
Each extension method registers IMailService as a transient service that resolves from the root provider too, in a singleton say; its config is built from the configure action on every resolve. SendGrid and Mailgun send through a connection pool their package shares. Neither provider takes an idempotency key, so never retry a send that may have reached it.
A missing key fails only when a mailer is resolved or sends. To fail at start-up instead, validate the config:
services.AddOptions<Regira.Office.Mail.SendGrid.SendGridConfig>()
.Validate(c => !string.IsNullOrEmpty(c.Key), "Mail:SendGrid:Key is missing")
.ValidateOnStart();
Thrown by the shared MailerBase for invalid attachments (missing file name or empty content), and by the
SendGrid and Mailgun backends when the provider returns a non-success response, an unauthorized
one included. The provider’s own error body is on ResponseContent — the status code alone rarely says why
a send was refused.
The MailKit backend throws it when the SMTP server refuses the credentials, the sender, a recipient or the
message, with the server’s reply on ResponseContent, and before connecting when the message has no sender or no
recipients, or an address or attachment content type MimeKit cannot parse. One refused recipient aborts the whole message: nothing is delivered, not even to the accepted
recipients, and ResponseContent names the refused address. A connection fault is not a refusal and passes
through unwrapped — SocketException, SslHandshakeException, NotSupportedException (StartTls against a
server without STARTTLS, or a UserName for a server that offers no AUTH), TimeoutException or
OperationCanceledException. A server that drops the session mid-exchange throws MailException, with the
SmtpProtocolException inside.
| Property | Type | Description |
|---|---|---|
MessageObject |
IMessageObject? |
The message that failed to send |
ResponseContent |
string? |
Raw provider response body |
Thrown when an invalid email address is assigned to MailAddress.Email.
| Property | Type | Description |
|---|---|---|
EmailInput |
string? |
The invalid value that was provided |
DummyMailer implements IMailService (via MailerBase) and sends nothing — it returns an empty MailResponse, so Success is false. Register it in tests to suppress actual sending:
using Regira.Office.Mail.Abstractions; // IMailService
using Regira.Office.Mail.Services; // DummyMailer
IServiceCollection services = new ServiceCollection();
services.AddSingleton<IMailService, DummyMailer>();
Mail.Web ships MailInput for accepting email requests over HTTP. MailInputExtensions.ToMessageObject() converts it to a domain IMessageObject.
[Authorize]
[HttpPost]
public async Task<IActionResult> Send([FromBody] MailInput input, IMailService mailer)
{
var message = input.ToMessageObject();
message.From = new MailAddress { Email = "no-reply@example.com" }; // the app's sender, not the caller's
try
{
await mailer.Send(message);
return Ok();
}
catch (MailException) // Regira.Office.Mail.Exceptions: the provider or SMTP server refused the message
{
return StatusCode(502);
}
}
The caller chooses the recipients, the body and the attachments, so an anonymous endpoint relays spam or phishing through the app’s mail account. Never expose one without authorization, set From on the server rather than taking input.From, and limit the recipients to the ones the app allows.
| Property | Type | Validation | Description |
|---|---|---|---|
From |
Address? |
— | The sender the caller names; an endpoint sets its own |
To |
ICollection<Recipient>? |
[Required] |
Recipients |
ReplyTo |
Address? |
— | Reply-To address |
Subject |
string? |
[Required] |
Email subject |
Body |
string? |
— | HTML or plain text body |
IsHtml |
bool |
— | Defaults to true |
Attachments |
ICollection<Attachment>? |
— | File attachments |
Address and Recipient both support implicit conversion from a plain email string.
IdentityMailer (from the Regira.Security.Authentication.Web package, namespace
Regira.Security.Authentication.Web.Mail) bridges IMailService to the ASP.NET Identity IEmailSender interface.
using Microsoft.AspNetCore.Identity.UI.Services; // IEmailSender
using Regira.Office.Mail.Abstractions; // IMailService
using Regira.Security.Authentication.Web.Mail; // IdentityMailer, IdentityMailerOptions
IServiceCollection services = new ServiceCollection();
services.AddSingleton<IEmailSender>(provider =>
new IdentityMailer(
provider.GetRequiredService<IMailService>(),
new IdentityMailerOptions { Sender = "no-reply@example.com", FormatPlainText = true }
));
FormatPlainText reads each message as plain text, the form the Regira account controllers write their mails in: each
http:// or https:// link becomes an anchor, each line break a <br>, and all of the text, each link in its href
too, is HTML-encoded. Every
message is read that way, so HTML that another caller sends through the same IEmailSender (the ASP.NET Identity UI
pages’ mails) arrives as escaped markup: turn it on only for a sender that carries the plain-text account mails.
Without it the message is sent unchanged as HTML.