Testing email functionality is often painful because SMTP servers are external, tests become slow or flaky, and the local setups differ from CI.

For years, developers used fake SMTP servers, in-memory solutions, or complex mocks. They work, but they never feel clean. With Testcontainers and Mailpit, this changes.

In this post, I show how I created a reusable Mailpit Testcontainer and how to use it in a real Spring Boot application.

The Problem with Email Testing

Most applications send emails for things like:

  • User registration
  • Password reset
  • Notifications

But testing emails usually means one of these:

  • Mocking the mail sender and not testing anything real
  • Using a shared SMTP server
  • Relying on local tools that are not available in CI

All of these approaches reduce confidence.

What we really want is:

  • A real SMTP server
  • Running locally and in CI
  • Isolated per test run
  • Easy to inspect sent emails

This is exactly what Mailpit gives us.

What is Mailpit?

Mailpit is a small, fast SMTP testing server with a modern web UI.

It captures emails instead of delivering them and exposes:

  • SMTP endpoint for sending emails
  • HTTP API for inspecting messages
  • Web UI to view emails in the browser

Perfect for automated tests.

Why Testcontainers?

Testcontainers allows you to run Docker containers directly from your tests.

That means:

  • No manual setup
  • Same environment locally and in CI
  • Containers start only when needed
  • Everything is reproducible

Mailpit already has a Docker image. So the combination is obvious.

The Mailpit Testcontainer

I created a dedicated Testcontainers module for Mailpit:
https://github.com/martinellich/testcontainers-mailpit

The goal was simple:

  • One container
  • Sensible defaults
  • Spring Boot friendly
  • Zero configuration for common use cases

The container exposes:

  • SMTP port
  • HTTP API port
  • Web UI port

And it integrates cleanly with Spring Boot tests.

Example Usage

In a Spring Boot test, it looks like this:

@Container
@ServiceConnection
static MailpitContainer mailpit = new MailpitContainer();

That is all.

Spring Boot automatically wires the mail configuration using the Service Connection support.
No spring.mail.host, no spring.mail.port, no profiles.
It just works.

Using It in a Real Application

I use this container in a real project: https://github.com/martinellich/registration

This application sends a registration email when a user signs up.

The integration test does the following:

  1. Starts the application
  2. Starts Mailpit via Testcontainers
  3. Triggers the registration use case
  4. Fetches emails from Mailpit via HTTP
  5. Verifies subject, recipient, and content

This tests the full email flow end-to-end.
No mocks. No assumptions. Real SMTP.

Why This Matters

This approach has several advantages:

  • Emails are tested like any other external integration
  • Tests are reliable and deterministic
  • CI behaves exactly like local development
  • No shared infrastructure needed
  • Easy debugging via Mailpit UI

Most importantly, you actually test what you ship.

Keep It Simple

Email testing does not need to be complicated.

With a small Testcontainer and a lightweight SMTP server, you get:

  • Better tests
  • Higher confidence
  • Less configuration

If you already use Testcontainers, adding Mailpit is a no-brainer.

Give it a try. And as always: Keep IT simple.