MailPit integration

⭐ Community Toolkit

MailPit is an email testing tool for developers. It acts as an SMTP server, captures emails, and provides a web interface to view them. The Aspire MailPit hosting integration enables you to run MailPit alongside your Aspire projects for local email testing.

Hosting integration

To get started with the Aspire MailPit hosting integration, install the CommunityToolkit.Aspire.Hosting.MailPit NuGet package in the app host project.

aspire add communitytoolkit-mailpit

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Select an integration to add:

> communitytoolkit-mailpit (CommunityToolkit.Aspire.Hosting.MailPit)
> Other results listed as selectable options...

#:package CommunityToolkit.Aspire.Hosting.MailPit@*

<PackageReference Include="CommunityToolkit.Aspire.Hosting.MailPit" Version="*" />

Add MailPit resource

To add MailPit to your app host, use the AddMailPit extension method:

var builder = DistributedApplication.CreateBuilder(args);

var mailpit = builder.AddMailPit("mailpit");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mailpit);

// After adding all resources, run the app...

When Aspire adds MailPit to the app host, it creates a new MailPit instance with the docker.io/axllent/mailpit container image.

Ports

MailPit exposes two ports:

SMTP port: 1025 (for sending emails)
Web UI port: 8025 (for viewing emails in the browser)

Both ports are automatically configured and accessible through the Aspire dashboard.

Data persistence

To persist emails across container restarts, use the WithDataVolume method:

var builder = DistributedApplication.CreateBuilder(args);

var mailpit = builder.AddMailPit("mailpit")
                     .WithDataVolume();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mailpit);

The data volume is used to persist the MailPit data outside the lifecycle of the container.

For development scenarios, you may want to use bind mounts instead of data volumes. To add a data bind mount, call the WithDataBindMount method:

var builder = DistributedApplication.CreateBuilder(args);

var mailpit = builder.AddMailPit("mailpit")
                     .WithDataBindMount(source: @"C:\MailPit\Data");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mailpit);

Web UI

The MailPit web interface is automatically available when you add a MailPit resource. You can access it through the Aspire dashboard by clicking on the endpoint for the MailPit resource.

Client integration

MailPit doesn’t require a dedicated client integration package. You can use any SMTP library to send emails to MailPit. The connection information is automatically injected into your application when you reference the MailPit resource.

Using MailKit

Here’s an example using the popular MailKit library:

dotnet add package MailKit

using MailKit.Net.Smtp;
using MimeKit;

public class EmailService
{
    private readonly string _smtpHost;
    private readonly int _smtpPort;

    public EmailService(IConfiguration configuration)
    {
        _smtpHost = configuration.GetConnectionString("mailpit")?.Split(':')[0] ?? "localhost";
        _smtpPort = 1025;
    }

    public async Task SendEmailAsync(string to, string subject, string body)
    {
        using var message = new MimeMessage();
        message.From.Add(new MailboxAddress("Sender", "[email protected]"));
        message.To.Add(new MailboxAddress("Recipient", to));
        message.Subject = subject;
        message.Body = new TextPart("plain") { Text = body };

        using var client = new SmtpClient();
        await client.ConnectAsync(_smtpHost, _smtpPort, false);
        await client.SendAsync(message);
        await client.DisconnectAsync(true);
    }
}

Using System.Net.Mail

You can also use the built-in System.Net.Mail APIs:

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

public class EmailService
{
    private readonly string _smtpHost;
    private readonly int _smtpPort;

    public EmailService(IConfiguration configuration)
    {
        _smtpHost = configuration.GetConnectionString("mailpit")?.Split(':')[0] ?? "localhost";
        _smtpPort = 1025;
    }

    public async Task SendEmailAsync(string to, string subject, string body)
    {
        using var client = new SmtpClient(_smtpHost, _smtpPort);
        using var message = new MailMessage("[email protected]", to, subject, body);
        await client.SendMailAsync(message);
    }
}