Mailpit: A Comprehensive Guide for Email Testing

Mailpit is an email testing tool that acts as an SMTP server and provides a web interface to view captured emails. It's an excellent alternative to tools like MailHog, offering a simple and efficient way to test email functionality in your applications without sending real emails.

Installation

Using Go

If you have Go installed, you can install Mailpit using the following command:

go install github.com/axllent/mailpit@latest

Make sure your $PATH includes the Go binaries directory (usually $HOME/go/bin).

Using Docker

You can also run Mailpit using Docker:

docker run -d -p 1025:1025 -p 8025:8025 axllent/mailpit

This command will start Mailpit in detached mode, mapping port 1025 for SMTP and port 8025 for the web UI.

Basic Usage

1. Start Mailpit:

   • If you installed it using Go, simply run mailpit in your terminal.
   • If you're using Docker, the container should already be running.

2. Configure your application:

   Configure your application to use Mailpit as its SMTP server. The default settings are:

   • Host: localhost or 127.0.0.1
   • Port: 1025
   • No authentication

   Example configuration in a .env file:

   MAIL_HOST=localhost
   MAIL_PORT=1025
   MAIL_USERNAME=
   MAIL_PASSWORD=
   MAIL_ENCRYPTION=null

3. Send emails:

   Send emails from your application as you normally would.

4. View emails:

   Open your web browser and go to http://localhost:8025 to view the captured emails.

Configuration for Different Testing Stages

Development

For local development, the default configuration is usually sufficient. You can simply run Mailpit and configure your application to use localhost:1025 as the SMTP server.

Example docker-compose.yml:

version: "3.8"
services:
  mailpit:
    image: axllent/mailpit
    ports:
      - "1025:1025"
      - "8025:8025"

Staging

In staging environments, you might want to configure Mailpit to be accessible from other machines or to use a different port. You can achieve this by setting environment variables or command-line arguments.

Example:

mailpit --http-port 9025 --smtp-bind-address 0.0.0.0:1025

This will make the web UI accessible on port 9025 and allow SMTP connections from any IP address. Make sure to adjust your firewall settings accordingly. Using docker, you can set the ports like so:

version: "3.8"
services:
  mailpit:
    image: axllent/mailpit
    ports:
      - "1025:1025"
      - "9025:8025"

Continuous Integration (CI)

In CI environments, you can use Mailpit to verify that emails are sent correctly during your automated tests. You can start Mailpit as part of your CI pipeline and use its API to retrieve and assert the contents of the emails.

Example using docker-compose in a CI script:

# Start Mailpit
docker-compose up -d mailpit

# Run tests
npm run test

# Stop Mailpit
docker-compose down

Example test (using Jest and node-fetch):

const fetch = require("node-fetch");

describe("Email tests", () => {
  it("should send a welcome email", async () => {
    // ... your code to trigger the email ...

    // Wait for the email to be delivered (adjust timeout as needed)
    await new Promise((resolve) => setTimeout(resolve, 1000));

    // Fetch emails from Mailpit API
    const response = await fetch("http://localhost:8025/api/v1/messages");
    const emails = await response.json();

    // Assert that the email was sent
    expect(emails.length).toBeGreaterThan(0);

    // Assert the email content
    const email = emails[0];
    expect(email.To[0].Email).toBe("test@example.com");
    expect(email.Subject).toBe("Welcome!");
  });
});

Securing Connections (TLS/SSL) and Allowing Insecure Connections

By default, Mailpit operates without TLS/SSL encryption. While this is suitable for development environments, you might need to configure secure connections or explicitly allow insecure connections for specific testing scenarios.

Allowing Insecure Connections

If your application requires sending emails over an insecure connection (not recommended for production), you might need to configure your email client or application to allow it. This is usually a setting within your email library or framework.

Example (Node.js with Nodemailer):

const nodemailer = require("nodemailer");

const transporter = nodemailer.createTransport({
  host: "localhost",
  port: 1025,
  secure: false, // Use `true` for TLS, `false` for plain SMTP
  tls: {
    rejectUnauthorized: false, // Allow self-signed certificates (for testing only)
  },
});

Warning: Disabling TLS verification (rejectUnauthorized: false) should only be done in controlled testing environments.

Configuring TLS/SSL Encryption

To enable TLS/SSL encryption, you need to provide Mailpit with a TLS certificate and key. You can generate a self-signed certificate for testing purposes.

1. Generate a self-signed certificate:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes

2. Start Mailpit with TLS:

mailpit --tls-cert-file cert.pem --tls-key-file key.pem

Or, using Docker:

version: "3.8"
services:
  mailpit:
    image: axllent/mailpit
    ports:
      - "1025:1025"
      - "8025:8025"
    volumes:
      - ./cert.pem:/cert.pem
      - ./key.pem:/key.pem
    command: ["--tls-cert-file", "/cert.pem", "--tls-key-file", "/key.pem"]

3. Configure your application:

Configure your application to use TLS and trust the certificate (if self-signed).

Example (Node.js with Nodemailer):

const nodemailer = require("nodemailer");

const transporter = nodemailer.createTransport({
  host: "localhost",
  port: 1025,
  secure: true, // Use `true` for TLS
  tls: {
    rejectUnauthorized: false, // Allow self-signed certificates (for testing only)
  },
});

Important: In production environments, use a valid TLS certificate from a trusted Certificate Authority (CA). Remove the rejectUnauthorized: false option when using a valid certificate.

Advanced Features

• API: Mailpit provides an API to retrieve, delete, and manipulate emails. See the Mailpit API documentation for details.
• Webhooks: Configure webhooks to be notified when new emails arrive.
• Authentication: While Mailpit is typically used without authentication in development environments, you can configure it to require authentication if needed.
• Message Retention: Configure how long Mailpit should retain messages.

Conclusion

Mailpit is a valuable tool for testing email functionality in your applications. Its ease of use, comprehensive features, and flexible configuration options make it a great choice for development, staging, and CI environments. By following this guide, you can effectively integrate Mailpit into your workflow and ensure that your email functionality works as expected.