Skip to content
Get packs

Guide · Open source

How to use MailHog: install, send test mail and view it

Updated · written with AI from the project's own documentation and checked against our catalogue data

MailHog is a free, MIT-licensed testing tool that stands in for a real mail server while you develop. Your application sends its email to MailHog, which stores the messages so you can read them in a web interface or fetch them through an HTTP API. This guide shows you how to install it, configure your app to use it, and inspect the messages it catches.

MailHogmailhog/MailHog · ★ 16.2k · MIT

Quick start

  1. 1Install MailHog. Run brew update && brew install mailhog on macOS, or use go install with Go 1.17 or newer.
  2. 2Start MailHog. Run mailhog from the command line, or run the MailHog binary from your Go bin directory.
  3. 3Configure your app. Set your application's SMTP server to the host running MailHog and port 1025.
  4. 4Send a test email. Trigger a sign-up, password reset or notification email from your app.
  5. 5Open the web UI. Visit the HTTP server on port 8025 to view the captured message as text, HTML or source.
  6. 6Check messages with the API. Use the HTTP API to list, retrieve or delete messages in automated tests.

Install MailHog on macOS or with Go

On macOS, install MailHog with Homebrew. Run the update and install command below, then start MailHog by running mailhog in the command line.

If you have Go 1.17 or newer, you can use the go install route instead. After it finishes, start MailHog by running the binary from Go's bin directory. The README gives the example path ~/go/bin/MailHog on Ubuntu.

  • Homebrew (macOS): brew update && brew install mailhog
  • Go 1.17 or newer: go install github.com/mailhog/MailHog@latest
brew update && brew install mailhog

Know the default ports and start MailHog

By default, MailHog runs with no extra configuration. The SMTP server listens on port 1025 and the HTTP server, which hosts the web UI and API, listens on port 8025. Message storage is in memory by default.

The README also lists Docker, FreeBSD and manual download routes. Check the project's configuration and deployment docs for those setups.

  • SMTP server: port 1025
  • HTTP server (web UI and API): port 8025
  • Storage: in-memory by default
~/go/bin/MailHog

Point your application at MailHog

Configure your application to send mail through MailHog's SMTP server instead of a real provider. Use the host where MailHog runs and port 1025. Your app code does not change beyond its mail settings.

If your tool uses the sendmail command, the README shows two options: the mhsendmail binary, or MailHog's own sendmail subcommand. You can also use your native sendmail with the -S flag to point it at the SMTP server.

  • Set your app's SMTP host to the machine running MailHog and the port to 1025
  • Or set sendmail to the mhsendmail binary, or to MailHog sendmail
  • Native sendmail example from the README: /usr/sbin/sendmail -S mail:1025
/usr/sbin/sendmail -S mail:1025

View and check captured messages

Open the web UI in your browser to see messages your app has sent. The UI can show each message as plain text, HTML or source, and it supports RFC2047 encoded headers and multipart MIME. You can download individual MIME parts.

For automated checks, use the HTTP API to list, retrieve and delete messages. The README points to API v1 and API v2 documentation. A client library list is also linked from the project's docs.

  • View plain text, HTML or raw source in the web UI
  • Download individual MIME parts
  • Use the HTTP API to list, retrieve and delete messages
  • Web UI updates in real time using EventSource

Optionally release mail to a real SMTP server

MailHog can release messages to a real SMTP server when you choose to. This is an opt-in feature. Without it, messages stay in MailHog and are not delivered to real recipients.

Use this only when you deliberately want a captured message to reach a real inbox.

  • Release is optional and set by you
  • Messages are not delivered to real recipients by default

Secure, persist or extend MailHog

The README lists HTTP basic authentication for the web UI and API, a Chaos Monkey feature for failure testing, and MongoDB or file-based storage for persistence. Configuration options are described in the project's CONFIG documentation.

If you need stored messages to survive restarts or grow large, the README points to MongoDB or file storage as the alternative to the in-memory default.

  • HTTP basic authentication for UI and API (see the Auth docs)
  • Chaos Monkey for failure testing (see the Jim docs)
  • MongoDB or file storage for persistence

What people use it for

  • Test sign-up and password reset emails on a local development machine without sending them to real inboxes.
  • Let QA staff inspect outgoing notification emails in a shared web interface.
  • Write automated tests that fetch sent messages through the HTTP API and check their contents.
  • Verify MIME and HTML rendering of messages by viewing them in plain text, HTML or source.

Frequently asked questions

Is MailHog free to use?

MailHog is released under the MIT license, as stated in the README. The license text is in the project's LICENSE file.

How do I install MailHog?

On macOS, run brew update && brew install mailhog. With Go 1.17 or newer, run go install github.com/mailhog/MailHog@latest. The README also documents FreeBSD, Docker and manual download routes.

What ports does MailHog use?

By default the SMTP server uses port 1025 and the HTTP server, which serves the web UI and API, uses port 8025.

Does MailHog send emails to real people?

Not by default. MailHog stores messages so you can inspect them. It can release messages to a real SMTP server only when you choose to configure that.

Where does MailHog store messages?

Messages are stored in memory by default. The README also lists MongoDB and file-based storage for persistence.

What are the alternatives to MailHog?

The project names MailCatcher as its inspiration and lists Mailpit and smtp4dev as comparable projects. Compare them on the features you need, such as storage and API support.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

MailHog suits developers and QA teams who want a simple local mail catcher with a web UI and HTTP API. It is not meant for production delivery or large-scale persistent storage, and the README shows older Go versions and a last push from February 2024, so check its maintenance status before adopting it. If you need active maintenance or heavier storage, consider a comparable project such as Mailpit or smtp4dev.

Install options & downloads