# Set up Mailpit in the AppHost

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

<ThemeImage
  light={mailpitLightIcon}
  dark={mailpitIcon}
  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/).

:::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](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.MailPit) NuGet package:

```bash title="Terminal"
aspire add 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="C# — AppHost.cs"
#:package CommunityToolkit.Aspire.Hosting.MailPit@*
```

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

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

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

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

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