Postbox: Email testing server for developers

Postbox is an email testing server for developers. It acts as a local SMTP server and saves all emails sent to it, and provides a HTTP API for automated testing.

Features

• Single binary with no dependencies
• Web UI to view emails
• Multiple inboxes to segregate emails by project
• Support for HTML emails and attachments
• Support for STARTTLS and HTTPS
• HTTP API to fetch emails and attachments for automated testing
• Drop in replacement for Mailtrap and supports the same API

Quick start

1. Download the latest binary for your platform (currently linux/amd64, linux/aarch64, darwin/arm64 and windows/amd64 are supported). On *nix, you can run the following command to download and start the server:

curl -sSLfo postbox "https://github.com/supriyo-biswas/postbox/releases/latest/download/postbox-$(uname -sm | tr 'A-Z ' 'a-z-')"
chmod +x postbox
./postbox server

Alternatively, use the Docker image:

docker run -d --name postbox -p 8025:8025 -p 8080:8080 -v $PWD/postbox:/var/lib supriyob/postbox

On Windows, open PowerShell in the directory where you want to install Postbox, then download and run the latest release:

Invoke-WebRequest -Uri 'https://github.com/supriyo-biswas/postbox/releases/latest/download/postbox-windows-amd64.exe' -OutFile '.\postbox.exe'
.\postbox.exe server

2. Send an email to the server by configuring your application to use the following SMTP settings:

• Host: localhost
• Port: 8025
• SMTP Username/Password: postbox-default/postbox-default
• SSL/TLS: None

3. Visit http://localhost:8080 to view the email in the web UI, using the username/password of postbox-default/postbox-default. You can also use the API server to fetch inboxes, emails and attachments like so:

curl localhost:8080/api/v1/inboxes/1/messages -H "Api-Token: postbox-default"

For details on the API, see the API documentation.

Creating inboxes

By default, Postbox creates a single inbox called postbox-default with the ID 1 and the SMTP username, password and HTTP API key all set to postbox-default. You can create additional inboxes by running the following command:

./postbox inbox add my-inbox

Or on docker, use:

docker exec postbox /usr/bin/postbox inbox add my-inbox

This will print the details of the new inbox like this:

Inbox ID: 2
SMTP username: my-inbox
SMTP password: <...>
API key: <...>

You can now use these credentials to send emails to the server and authenticate with the API server.

Advanced usage

If you want to configure STARTTLS support for the SMTP server, add HTTPS for the API server, or configure the server to listen on a different port, define a TOML file like this:

[server.smtp]
    listen = ":2525" # SMTP port, default is 8025
    key_file = "my-key.pem" # TLS key file, for STARTTLS
    cert_file = "my-cert.pem" # TLS cert file, for STARTTLS
    max_message_bytes = 1000000 # Max size of an email, in bytes (default is 10MB)

[server.http]
    listen = ":2580" # HTTP port, default is 8080
    key_file = "my-key.pem" # TLS key file, for HTTPS
    cert_file = "my-cert.pem" # TLS cert file, for HTTPS

[database]
    path = "/tmp" # Custom path to postbox's database

[logging]
    filename = "/tmp/postbox.log" # To configure logging to a file, instead of stdout
    max_size = 100 # Max size of the log file, in MB
    max_backups = 10 # Max number of log files to keep
    max_age = 7 # Max age of the log file, in days

Place this configuration file in ~/.config/postbox/config.toml on Linux, ~/Library/Application Support/postbox/config.toml on macOS, or in $PWD/postbox/config.toml if using the Docker image.

Alternatively, pass the configuration file in each invocation:

./postbox server --config /path/to/config.toml
./postbox inbox create my-inbox --config /path/to/config.toml