MailPeek.Hosting.Aspire

MailPeek

A NuGet package that provides an in-memory fake SMTP server with a real-time web dashboard for ASP.NET Core applications. Think Hangfire, but for emails.

Perfect for local development and testing — capture emails your app sends without configuring a real mail server.

Features

• Fake SMTP server — Receives emails on a configurable port, no external mail server needed
• Real-time dashboard — Messages appear instantly via SignalR
• Full MIME support — HTML/text bodies, attachments, CC/BCC, headers (powered by MimeKit)
• Responsive UI — Works on desktop, tablet, and mobile
• Dark/light theme — Respects your OS prefers-color-scheme setting
• Hangfire-style DX — Two lines of code to set up
• Extensible auth — Plug in your own authorization filter (OAuth, Azure AD, cookie auth, etc.)
• Testable — Inject IMessageStore in your tests to assert emails were sent
• Zero frontend toolchain — All assets embedded in the DLL

Quick Start

1. Install the package

dotnet add package MailPeek

2. Register services

using MailPeek.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMailPeek(options =>
{
    options.Port = 2525;           // SMTP port to listen on
    options.MaxMessages = 1000;    // Max stored messages (FIFO eviction)
});

var app = builder.Build();

app.UseMailPeek(options =>
{
    options.PathPrefix = "/mailpeek";  // Dashboard URL (configurable)
    options.Title = "MailPeek";        // Custom page title
});

app.Run();

3. Point your app's SMTP settings to localhost:2525

{
  "Smtp": {
    "Host": "localhost",
    "Port": 2525
  }
}

4. Open the dashboard

Navigate to http://localhost:5000/mailpeek to see received emails in real-time.

Configuration

MailPeekSmtpOptions

MailPeekDashboardOptions

Authorization

The dashboard supports extensible authorization via IMailPeekAuthorizationFilter:

using MailPeek.Authorization;

public class MyAuthFilter : IMailPeekAuthorizationFilter
{
    public bool Authorize(MailPeekAuthContext context)
    {
        // Check claims, roles, policies — whatever your auth stack provides
        return context.HttpContext.User.Identity?.IsAuthenticated == true;
    }
}

// Register it
app.UseMailPeek(options =>
{
    options.Authorization = [new MyAuthFilter()];
});

Works naturally with OAuth, Azure AD, cookie auth, or any ASP.NET Core authentication middleware.

Testing

Inject IMessageStore in your tests to assert that emails were sent:

using MailPeek.Storage;

var store = serviceProvider.GetRequiredService<IMessageStore>();

// Send an email through your app's email service...

var messages = store.GetAll();
Assert.Single(messages);
Assert.Equal("[email protected]", messages[0].To.First());
Assert.Equal("Welcome!", messages[0].Subject);

Aspire Integration

MailPeek integrates with .NET Aspire for service discovery.

AppHost

Install the hosting package in your AppHost project:

dotnet add package MailPeek.Hosting.Aspire

var mailpeek = builder.AddMailPeek("mailpeek", smtpPort: 2525);

builder.AddProject<Projects.WebApp>("webapp")
    .WithReference(mailpeek);

Consuming Service

In the web project that hosts the MailPeek dashboard:

builder.Services.AddMailPeek("mailpeek"); // reads SMTP config from Aspire
app.UseMailPeek();

Other services can read the SMTP connection string directly:

var smtp = builder.Configuration.GetConnectionString("mailpeek");
// -> "smtp://localhost:2525"

Dashboard Pages

REST API

The dashboard exposes a REST API under {prefix}/api/:

Tech Stack

• SmtpServer — SMTP protocol handling
• MimeKit — MIME message parsing
• ASP.NET Core SignalR — Real-time dashboard updates
• Embedded HTML/JS/CSS — No frontend build toolchain required

Requirements

• .NET 8.0 or .NET 9.0

License

MIT