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.

Installation

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

Terminal

aspire add communitytoolkit-mailpit

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

AppHost.cs

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

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();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const mailpit = await builder.addMailPit('mailpit');

const api = await builder.addProject(
  'apiservice',
  '../ExampleProject/ExampleProject.csproj'
);
await api.withReference(mailpit);

await 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 the SMTP connection string, host, port, and URI available to the consuming project. For the exact formats and per-language examples, see Connect to Mailpit.

SMTP endpoint

Mailpit listens for SMTP on port 1025 by default. Aspire exposes this as the smtp endpoint and uses it for the resource’s Host, Port, Uri, and connection string values.

HTTP UI endpoint

Mailpit serves its web-based email inspector on port 8025 by default. Aspire exposes this separately as the http endpoint on the resource.

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("mailpit-data");

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

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

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const mailpit = await builder.addMailPit('mailpit');
await mailpit.withDataVolume('mailpit-data');

const api = await builder.addProject(
  'apiservice',
  '../ExampleProject/ExampleProject.csproj'
);
await api.withReference(mailpit);

await builder.build().run();

The data volume is mounted at /data and the integration configures Mailpit to store its database at /data/mailpit.db. For more information on data volumes and details on why they’re preferred over bind mounts, see Docker docs: Volumes.

Add Mailpit resource with data bind mount

Use a bind mount when you need direct access to Mailpit’s database files from the host:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var mailpit = builder.AddMailPit("mailpit")
    .WithDataBindMount("./mailpit-data");

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const mailpit = await builder.addMailPit('mailpit');
await mailpit.withDataBindMount('./mailpit-data');

await builder.build().run();

The bind mount uses the same /data container path and /data/mailpit.db database location as a data volume.

Customize ports

Pass httpPort and smtpPort to bind Mailpit’s endpoints to fixed host ports:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var mailpit = builder.AddMailPit(
    name: "mailpit",
    httpPort: 8025,
    smtpPort: 1025);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const mailpit = await builder.addMailPit('mailpit', {
  httpPort: 8025,
  smtpPort: 1025,
});

await builder.build().run();

When these values are omitted, Aspire assigns random host ports while Mailpit continues to listen on ports 8025 and 1025 inside the container.

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.

Hosting integration health checks

The Mailpit hosting integration automatically checks the /livez and /readyz paths on the HTTP endpoint. The resource becomes healthy after both checks pass.