aspire-mailpit-integration_skill

Overview

This skill shows how to integrate Mailpit with .NET Aspire to capture and inspect outgoing email traffic during development and tests. It provides example AppHost configuration, SMTP settings, an IEmailSender implementation using MailKit, and patterns for viewing and asserting captured messages in integration tests. The goal is reliable local email testing without sending real messages.

How this skill works

Add Mailpit as a container in the Aspire AppHost and expose HTTP (UI) and SMTP endpoints. Configure your app to point its SMTP settings at Mailpit (localhost:1025) and use a MailKit-based IEmailSender to send messages. Use the Mailpit web UI or its API from tests to list, clear, and wait for messages and to inspect HTML, headers, and attachments.

When to use it

• During local development to preview rendered HTML and headers without sending real emails
• When writing integration tests that must assert emails were sent and contain specific content
• To debug email rendering, templates, or header and attachment issues
• When you need a lightweight, containerized SMTP capture service integrated into Aspire
• To run automated tests that rely on deterministic email delivery behavior

Best practices

• Register SMTP settings via configuration and inject an IEmailSender for testability
• Use Aspire container endpoints so tests reference the runtime Mailpit URL rather than hardcoded hosts
• Clear Mailpit messages at the start of each test to avoid cross-test interference
• Use a WaitForMessage helper with a timeout for asynchronous email sending
• Keep production SMTP configuration separate and enable SSL/auth only outside Development

Example use cases

• Signup flow test: trigger signup API, fetch Mailpit messages, assert recipient, subject, and HTML content
• Password reset: extract reset link from captured HTML and verify the link returns HTTP 200
• Bulk invitations: post bulk invites and assert Mailpit captured the expected number of messages and recipients
• Async workflows: trigger background work, then wait for the expected email within a timeout window
• Debugging templates: preview rendered HTML and source view in Mailpit UI to iterate on email templates