Set up Mailpit in the AppHost

⭐ Community Toolkit

This article is the reference for the Aspire Mailpit Hosting integration. It enumerates the AppHost APIs that you use to model a Mailpit resource in your AppHost project.

If you’re new to the Mailpit integration, start with the Get started with Mailpit integrations guide. For how consuming apps read the connection information this page exposes, see Connect to Mailpit.

Note

TypeScript AppHost support for the Mailpit integration is not yet available. The examples on this page use the C# AppHost only.

Installation

To start building an Aspire app that uses Mailpit, install the 📦 CommunityToolkit.Aspire.Hosting.MailPit NuGet package:

Terminal

aspire add mailpit

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

C# — AppHost.cs

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

XML — AppHost.csproj

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

Add Mailpit resource

Once you’ve installed the hosting integration in your AppHost project, you can add a Mailpit resource as shown in the following example:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(mailpit);

// After adding all resources, run the app...
builder.Build().Run();

1. When Aspire adds a container image to the AppHost, as shown in the preceding example with the docker.io/axllent/mailpit image, it creates a new Mailpit instance on your local machine.

2. The AppHost reference call configures a connection in the consuming project named after the referenced Mailpit resource, such as mailpit in the preceding example.

Note

When you reference a Mailpit resource from the AppHost, Aspire makes several properties available to the consuming project, such as the SMTP host, SMTP port, and the HTTP UI endpoint URL. For a complete list of these properties and per-language connection examples, see Connect to Mailpit.

SMTP endpoint

Mailpit listens for SMTP on port 1025 by default. Aspire exposes this as the smtp endpoint on the resource. When you call WithReference(mailpit) from a consuming project, Aspire injects the SmtpHost and SmtpPort connection properties automatically.

HTTP UI endpoint

Mailpit serves its web-based email inspector on port 8025 by default. Aspire exposes this as the http endpoint on the resource. The HttpEndpoint connection property contains the full URL.

You can open the Mailpit web UI from the Aspire dashboard by clicking the HTTP endpoint link next to the Mailpit resource.

Add Mailpit resource with data volume

Add a data volume to the Mailpit resource to persist captured emails across container restarts:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(mailpit);

// After adding all resources, run the app...
builder.Build().Run();

The data volume is mounted inside the Mailpit container and persists data outside the lifecycle of the container. When a name parameter isn’t provided, the name is generated at random. For more information on data volumes and details on why they’re preferred over bind mounts, see Docker docs: Volumes.

Connection properties

For the full reference of Mailpit connection properties — and how consuming apps in C#, TypeScript, Python, and Go read them — see Connect to Mailpit.