# Set up Mailpit in the AppHost

<Badge text="⭐ Community Toolkit" variant="tip" size="large" />

<ThemeImage
  light={mailpitIcon}
  dark={mailpitLightIcon}
  alt="Mailpit logo"
  width={100}
  height={100}
  zoomable={false}
  classOverride="float-inline-left icon"
/>

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`](/get-started/app-host/) project.

If you're new to the Mailpit integration, start with the [Get started with Mailpit integrations](/integrations/devtools/mailpit/mailpit-get-started/) guide. For how consuming apps read the connection information this page exposes, see [Connect to Mailpit](../mailpit-connect/).

## Installation

To start building an Aspire app that uses Mailpit, install the [📦 CommunityToolkit.Aspire.Hosting.MailPit](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.MailPit) NuGet package:

```bash title="Terminal"
aspire add communitytoolkit-mailpit
```

<LearnMore>
  Learn more about [`aspire add`](/reference/cli/commands/aspire-add/) in the
  command reference.
</LearnMore>

Or, choose a manual installation approach:

```csharp title="AppHost.cs"
#:package CommunityToolkit.Aspire.Hosting.MailPit@*
```

```xml title="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:

```csharp title="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 title="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.

1. 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](../mailpit-connect/).

## 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:

```csharp title="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 title="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](https://docs.docker.com/engine/storage/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:

```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();
```

```typescript title="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:

```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();
```

```typescript title="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](../mailpit-connect/).

## 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.