QREATiv | Tutorial: Using MODX with MailHog Local IMAP Email Server


The Goal

Learn how to install the MailHog SMTP server and configure the MODX mail settings for local email testing.

Specialties: Front-end dev; photorealistic hand-drawing
Years’ Experience: 22
Employer: Freelance
Tutorial Details
Difficulty Level: ★★
  • Basic / Inexperienced
  • ★★ Easy / Beginner
  • ★★★ Moderate / Experienced
  • ★★★★ Difficult / Expert
  • ★★★★★ Complex / Über Geek
Tools: MailHog, Homebrew, MODX, Terminal
Completion Time: 15-30 minutes
Related Article: Source
Tags: mailhog, email, modx, homebrew

This is a member-contributed tutorial. If possible, contact the author with questions or comments.

MODX + MailHog

MailHog, like MailCatcher which inspired it (see my tutorial) is a very simple but useful mail testing tool created by Ian Kent. It functions as a local SMTP server with a basic GUI for email testing and debugging which, no surprise here, is useful for Web application development.

Are there more feature-rich alternatives? Sure. Mailtrap is a commercial (online) option but for my needs I find MailHog (or MailCatcher) ideal, though your mileage may vary. For the purpose of this tutorial I’ll show you how to configure MailHog for use with MODX but it could be used with other Web applications/CMS1.

MODX Mail Configuration

  1. Sign-in to the MODX Manager.
  2. Go to Menu > [ Cog ] > System Settings.
  3. Leave the picker at the default core setting and in the Filter by area... picker select Mail. You should see 13 Mail settings. We’re only concerned with 4 of them.
  4. Leave SMTP Authentication set to the default No.
  5. Set SMTP Hosts to or localhost.
  6. Set SMTP Port to 1025.
  7. Set Use SMTP to Yes.

Installing MailHog

On its Github page it states “MailHog runs without installation” but you still need to download it and that can be done a few different ways: GitHub, Docker, Compose, Homebrew or Golang. For the purpose of this tutorial I used Homebrew (Mac and Linux). The MailHog GitHub site has additional configuration options depending on your choice of installation.

For those new to using the Terminal or command-line, after typing or copying/pasting a command hit Return then wait for the next prompt before entering the next command.

  1. Using the Terminal/command-line install Homebrew (Mac and Linux) if you haven’t already:
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. Install MailHog:
    brew install mailhog
  3. Start MailHog:
    brew services start mailhog
  4. Launch MailHog:

To (re)start MailHog repeat Step 4.

Going Whole (Mail)Hog

MailHog should now be accessible at http://localhost:8025 in your browser. If you configured the mail settings correctly when you send emails through your local MODX-built site they should instantly appear in the MailHog GUI.

A Security Note About mhsendmail

mhsendmail is a sendmail replacement for MailHog that ensures mail is redirected to MailHog using SMTP. The GitHub page has additional information. As it applies to MODX since the SMTP Hosts and SMTP Port have been explicitly set in System Settings > Core > Mail then my guess is we are probably ok security-wise.

Depending on the application the configuration process will vary.

Tutorials Archive show by year/month