mailpit-integration

Email Testing with Mailpit and .NET Aspire

When to Use This Skill

Use this skill when:

• Testing email delivery locally without sending real emails
• Setting up email infrastructure in .NET Aspire
• Writing integration tests that verify emails are sent
• Debugging email rendering and headers

Related skills:

• aspnetcore/mjml-email-templates - MJML template authoring
• testing/verify-email-snapshots - Snapshot test rendered HTML
• aspire/integration-testing - General Aspire testing patterns

---

What is Mailpit?

Mailpit is a lightweight email testing tool that:

• Captures all SMTP traffic without delivering emails
• Provides a web UI to view captured emails
• Exposes an API for programmatic access
• Supports HTML rendering, headers, and attachments

Perfect for development and integration testing.

---

Aspire AppHost Configuration

Add Mailpit as a container in your AppHost:

// AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

// Add Mailpit for email testing
var mailpit = builder.AddContainer("mailpit", "axllent/mailpit")
    .WithHttpEndpoint(port: 8025, targetPort: 8025, name: "ui")
    .WithEndpoint(port: 1025, targetPort: 1025, name: "smtp");

// Reference in your API project
var api = builder.AddProject<Projects.MyApp_Api>("api")
    .WithReference(mailpit.GetEndpoint("smtp"))
    .WithEnvironment("Smtp__Host", mailpit.GetEndpoint("smtp"));

builder.Build().Run();

---

SMTP Configuration

appsettings.json

{
  "Smtp": {
    "Host": "localhost",
    "Port": 1025,
    "EnableSsl": false,
    "FromAddress": "[email protected]",
    "FromName": "MyApp"
  }
}

Configuration Class

public class SmtpSettings
{
    public string Host { get; set; } = "localhost";
    public int Port { get; set; } = 1025;
    public bool EnableSsl { get; set; } = false;
    public string FromAddress { get; set; } = "[email protected]";
    public string FromName { get; set; } = "MyApp";

    // Optional: For production SMTP
    public string? Username { get; set; }
    public string? Password { get; set; }
}