Send email from C# and .NET

dotnet add package MailKit

using MailKit.Net.Smtp;
using MailKit.Security;
using MimeKit;

var message = new MimeMessage();
message.From.Add(new MailboxAddress("Acme", "billing@yourdomain.com"));
message.To.Add(MailboxAddress.Parse("user@example.com"));
message.Subject = "Your receipt";

// Optional: Groundmail features over SMTP.
message.Headers.Add("X-Groundmail-Idempotency-Key", "receipt-order-1042");
message.Headers.Add("X-Groundmail-Tag", "type=receipt");

var body = new BodyBuilder
{
    TextBody = "Thanks for your order.",
    HtmlBody = "<p>Thanks for your order.</p>",
};
body.Attachments.Add("invoice-1042.pdf");
message.Body = body.ToMessageBody();

using var smtp = new SmtpClient();
await smtp.ConnectAsync("smtp.groundmail.dev", 587, SecureSocketOptions.StartTls);
await smtp.AuthenticateAsync("groundmail", Environment.GetEnvironmentVariable("GROUNDMAIL_SMTP_PASSWORD")!);
await smtp.SendAsync(message);
await smtp.DisconnectAsync(true);

using System.Net;
using System.Net.Mail;

using var client = new SmtpClient("smtp.groundmail.dev", 587)
{
    EnableSsl = true,
    Credentials = new NetworkCredential("groundmail", Environment.GetEnvironmentVariable("GROUNDMAIL_SMTP_PASSWORD")),
};

using var message = new MailMessage("billing@yourdomain.com", "user@example.com", "Your receipt", "<p>Thanks for your order.</p>")
{
    IsBodyHtml = true,
};
await client.SendMailAsync(message);

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.groundmail.dev/") };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("GROUNDMAIL_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post, "emails")
{
    Content = JsonContent.Create(new
    {
        from = "Acme <billing@yourdomain.com>",
        to = new[] { "user@example.com" },
        subject = "Your receipt",
        html = "<p>Thanks for your order.</p>",
        text = "Thanks for your order.",
    }),
};
request.Headers.Add("Idempotency-Key", "receipt-order-1042");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
// 200 {"id":"msg_…","status":"sent"}

attachments = new[]
{
    new
    {
        name = "invoice-1042.pdf",
        content_type = "application/pdf",
        data = Convert.ToBase64String(await File.ReadAllBytesAsync("invoice-1042.pdf")),
    },
},

// Email/GroundmailClient.cs
using System.Net;
using System.Net.Http.Json;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace MyApp.Email;

public sealed class GroundmailOptions
{
    public const string Section = "Groundmail";

    public string ApiKey { get; set; } = "";
    public Uri BaseAddress { get; set; } = new("https://api.groundmail.dev/");
}

public sealed record SendEmailRequest
{
    public required string From { get; init; }
    public required IReadOnlyList<string> To { get; init; }
    public required string Subject { get; init; }
    public string? Html { get; init; }
    public string? Text { get; init; }
    public string? ReplyTo { get; init; }
    public IReadOnlyDictionary<string, string>? Tags { get; init; }
}

public sealed record SendEmailResponse(string Id, string Status, bool? Test);

public sealed class GroundmailException(
    HttpStatusCode status, string? code, string message, string? hint, TimeSpan? retryAfter)
    : Exception(message)
{
    public HttpStatusCode Status { get; } = status;
    public string? Code { get; } = code;
    public string? Hint { get; } = hint;
    public TimeSpan? RetryAfter { get; } = retryAfter;

    /// 429 (except the daily ramp-up limit), 500, 502 and 503 are safe to retry
    /// with the same Idempotency-Key. 504 means the email may already be on its way.
    public bool IsRetryable => Status switch
    {
        HttpStatusCode.TooManyRequests => Code != "daily_ramp_limit",
        HttpStatusCode.InternalServerError or HttpStatusCode.BadGateway or HttpStatusCode.ServiceUnavailable => true,
        _ => false,
    };

    public static async Task<GroundmailException> FromResponseAsync(HttpResponseMessage response, CancellationToken ct)
    {
        string? code = null, hint = null;
        var message = $"Groundmail returned {(int)response.StatusCode}";
        try
        {
            using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync(ct));
            var root = doc.RootElement;
            // Errors look like {"error": {"code", "message", "hint", "docs_url"}}.
            var error = root.TryGetProperty("error", out var e) && e.ValueKind == JsonValueKind.Object ? e : root;
            code = error.TryGetProperty("code", out var c) ? c.GetString() : null;
            hint = error.TryGetProperty("hint", out var h) ? h.GetString() : null;
            if (error.TryGetProperty("message", out var m)) message = m.GetString() ?? message;
        }
        catch (JsonException)
        {
            // Not JSON (for example a proxy error page): keep the status line.
        }
        return new GroundmailException(response.StatusCode, code, message, hint, response.Headers.RetryAfter?.Delta);
    }
}

public sealed class GroundmailClient(HttpClient http)
{
    private static readonly JsonSerializerOptions Json = new(JsonSerializerDefaults.Web)
    {
        PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower, // ReplyTo -> reply_to
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    };

    public async Task<SendEmailResponse> SendAsync(
        SendEmailRequest email, string idempotencyKey, CancellationToken ct = default)
    {
        using var request = new HttpRequestMessage(HttpMethod.Post, "emails")
        {
            Content = JsonContent.Create(email, options: Json),
        };
        request.Headers.Add("Idempotency-Key", idempotencyKey);

        using var response = await http.SendAsync(request, ct);
        if (!response.IsSuccessStatusCode)
            throw await GroundmailException.FromResponseAsync(response, ct);

        return (await response.Content.ReadFromJsonAsync<SendEmailResponse>(Json, ct))!;
    }

    /// Retries rate limits, 5xx and network errors with the same idempotency key,
    /// so a retry can never send the email twice.
    public async Task<SendEmailResponse> SendWithRetryAsync(
        SendEmailRequest email, string idempotencyKey, CancellationToken ct = default)
    {
        const int maxAttempts = 5;
        for (var attempt = 1; ; attempt++)
        {
            try
            {
                return await SendAsync(email, idempotencyKey, ct);
            }
            catch (GroundmailException e) when (e.IsRetryable && attempt < maxAttempts)
            {
                await Task.Delay(e.RetryAfter ?? Backoff(attempt), ct);
            }
            catch (HttpRequestException) when (attempt < maxAttempts)
            {
                await Task.Delay(Backoff(attempt), ct);
            }
            catch (TaskCanceledException) when (!ct.IsCancellationRequested && attempt < maxAttempts)
            {
                // HttpClient.Timeout elapsed. The email may or may not have been accepted;
                // retrying with the same key is safe either way.
                await Task.Delay(Backoff(attempt), ct);
            }
        }
    }

    private static TimeSpan Backoff(int attempt) => TimeSpan.FromSeconds(Math.Pow(2, attempt - 1)); // 1s, 2s, 4s, 8s
}

using System.Net.Http.Headers;
using Microsoft.Extensions.Options;
using MyApp.Email;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<GroundmailOptions>(builder.Configuration.GetSection(GroundmailOptions.Section));
builder.Services.AddHttpClient<GroundmailClient>((sp, http) =>
{
    var options = sp.GetRequiredService<IOptions<GroundmailOptions>>().Value;
    http.BaseAddress = options.BaseAddress;
    http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", options.ApiKey);
    http.Timeout = TimeSpan.FromSeconds(30);
});

using System.Net;
using MyApp.Email;

app.MapPost("/orders/{orderId}/receipt", async (string orderId, string email, GroundmailClient groundmail, CancellationToken ct) =>
{
    try
    {
        var result = await groundmail.SendWithRetryAsync(new SendEmailRequest
        {
            From = "Acme <billing@yourdomain.com>",
            To = [email],
            Subject = $"Receipt for order {orderId}",
            Html = $"<p>Thanks for order {orderId}.</p>",
            Text = $"Thanks for order {orderId}.",
            Tags = new Dictionary<string, string> { ["type"] = "receipt" },
        }, idempotencyKey: $"receipt-{orderId}", ct);

        return Results.Ok(new { result.Id, result.Status });
    }
    catch (GroundmailException e) when (e.Status == HttpStatusCode.UnprocessableEntity)
    {
        // Every recipient is suppressed or opted out. Don't retry; flag the address instead.
        return Results.Problem(e.Message, statusCode: StatusCodes.Status422UnprocessableEntity);
    }
    catch (GroundmailException e) when (e.Status is HttpStatusCode.Unauthorized or HttpStatusCode.Forbidden)
    {
        // Wrong or revoked key, unverified From domain, missing scope: fix the config, don't retry.
        app.Logger.LogError("Groundmail refused the send: {Code} {Message} {Hint}", e.Code, e.Message, e.Hint);
        return Results.Problem("Email is misconfigured", statusCode: StatusCodes.Status500InternalServerError);
    }
});

var ex = await Assert.ThrowsAsync<GroundmailException>(() => groundmail.SendAsync(new SendEmailRequest
{
    From = "billing@yourdomain.com",
    To = ["suppressed@simulator.groundmail.dev"],
    Subject = "Suppression test",
    Text = "Simulated.",
}, $"test-{Guid.NewGuid()}"));

Assert.Equal(HttpStatusCode.UnprocessableEntity, ex.Status);

dotnet add package Azure.Identity

using System.Net.Http.Headers;
using Azure.Core;

namespace MyApp.Email;

public sealed class EntraTokenHandler(TokenCredential credential) : DelegatingHandler
{
    private static readonly TokenRequestContext Scope = new(["https://api.groundmail.dev/.default"]);

    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        // DefaultAzureCredential caches the token and refreshes it before it expires.
        AccessToken token = await credential.GetTokenAsync(Scope, cancellationToken);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
        return await base.SendAsync(request, cancellationToken);
    }
}

using Azure.Core;
using Azure.Identity;
using MyApp.Email;

builder.Services.AddSingleton<TokenCredential>(new DefaultAzureCredential());
builder.Services.AddTransient<EntraTokenHandler>();
builder.Services.AddHttpClient<GroundmailClient>(http =>
    {
        http.BaseAddress = new Uri("https://api.groundmail.dev/");
        http.Timeout = TimeSpan.FromSeconds(30);
    })
    .AddHttpMessageHandler<EntraTokenHandler>();