MailHog: The Essential Email Testing Tool for .NET Developers

by Joche Ojeda | Aug 4, 2025 | Linux, Ubuntu, WSL

Email functionality is a critical component of most modern applications, from user authentication and password resets to notifications and marketing campaigns. However, testing email features during development can be challenging—you don’t want to accidentally send test emails to real users, and setting up a complete email server for testing is often overkill. This is where MailHog comes to the rescue.

What is MailHog?

MailHog is an open-source email testing tool designed specifically for development and testing environments. Think of it as a “fake” SMTP server that captures emails sent by your application instead of delivering them to real recipients. It provides a clean web interface where you can view, inspect, and manage all captured emails in real-time.

Built with Go and completely free, MailHog has become an indispensable tool for developers who need to test email functionality without the complexity and risks associated with real email delivery.

Why MailHog is Perfect for .NET Development

As a .NET developer, you’ve likely encountered scenarios where you need to test:

• User registration and email verification
• Password reset workflows
• Account activation processes
• Notification systems
• Email templates and formatting

MailHog seamlessly integrates with .NET applications using the standard SMTP libraries you’re already familiar with. Whether you’re using System.Net.Mail.SmtpClient or other SMTP libraries, MailHog works transparently as a drop-in replacement for your production SMTP server.

Key Features That Make MailHog Stand Out

SMTP Server Compliance

• Full RFC5321 ESMTP server implementation
• Support for SMTP AUTH (RFC4954) and PIPELINING (RFC2920)
• Works with any SMTP client library

Developer-Friendly Interface

• Clean web UI to view messages in plain text, HTML, or raw source
• Real-time updates using EventSource technology
• Support for RFC2047 encoded headers
• Multipart MIME support with downloadable individual parts

Testing and Development Features

• Chaos Monkey: Built-in failure testing to simulate email delivery issues
• Message Release: Forward captured emails to real SMTP servers when needed
• HTTP API: Programmatically list, retrieve, and delete messages (APIv1 and APIv2)
• Authentication: HTTP basic authentication for UI and API security

Storage Options

• In-memory storage: Lightweight and fast for development
• MongoDB persistence: For scenarios requiring message persistence
• File-based storage: Simple file system storage option

Deployment Benefits

• Lightweight and portable: Single binary with no dependencies
• No installation required: Download and run
• Cross-platform: Works on Windows, macOS, and Linux

Installing MailHog on WSL2

Setting up MailHog on Windows Subsystem for Linux (WSL2) is straightforward and provides excellent performance for .NET development workflows.

Option 1: Automated Installation with Script

If you don’t want to manually install MailHog, you can use my automated installation script for WSL:

# Download and run the installation script
curl -sSL https://raw.githubusercontent.com/egarim/MyWslScripts/master/install_mailhog.sh | bash

This script will automatically download MailHog, set it up, and configure it as a service. You can find the script at: https://github.com/egarim/MyWslScripts/blob/master/install_mailhog.sh

Option 2: Manual Installation

Step 1: Download MailHog

# Create a directory for MailHog
mkdir ~/mailhog
cd ~/mailhog

# Download the latest Linux binary
wget https://github.com/mailhog/MailHog/releases/download/v1.0.1/MailHog_linux_amd64

# Make it executable
chmod +x MailHog_linux_amd64

# Optional: Create a symlink for easier access
sudo ln -s ~/mailhog/MailHog_linux_amd64 /usr/local/bin/mailhog

Step 2: Start MailHog

# Start MailHog (runs on ports 1025 for SMTP and 8025 for web UI)
./MailHog_linux_amd64

# Or if you created the symlink:
mailhog

Step 3: Verify Installation

Open your browser and navigate to http://localhost:8025. You should see the MailHog web interface ready to capture emails.

Step 4: Configure as a Service (Optional)

For persistent use, create a systemd service:

# Create service file
sudo nano /etc/systemd/system/mailhog.service

Add the following content:

[Unit]
Description=MailHog Email Web Service
After=network.target

[Service]
Type=simple
User=your-username
ExecStart=/home/your-username/mailhog/MailHog_linux_amd64
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable mailhog
sudo systemctl start mailhog

Integrating MailHog with .NET Applications

Configuration in appsettings.json

{
  "EmailSettings": {
    "SmtpServer": "localhost",
    "SmtpPort": 1025,
    "FromEmail": "noreply@yourapp.com",
    "FromName": "Your Application"
  }
}

Using with System.Net.Mail

public class EmailService
{
    private readonly IConfiguration _configuration;

    public EmailService(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public async Task SendEmailAsync(string to, string subject, string body)
    {
        var smtpClient = new SmtpClient(_configuration["EmailSettings:SmtpServer"])
        {
            Port = int.Parse(_configuration["EmailSettings:SmtpPort"]),
            EnableSsl = false, // MailHog doesn't require SSL
            UseDefaultCredentials = true
        };

        var mailMessage = new MailMessage
        {
            From = new MailAddress(_configuration["EmailSettings:FromEmail"], 
                                 _configuration["EmailSettings:FromName"]),
            Subject = subject,
            Body = body,
            IsBodyHtml = true
        };
        
        mailMessage.To.Add(to);

        await smtpClient.SendMailAsync(mailMessage);
    }
}

Real-World Testing Scenarios

Password Reset Testing

[Fact]
public async Task PasswordReset_ShouldSendEmail()
{
    // Arrange
    var userEmail = "test@example.com";
    var resetToken = Guid.NewGuid().ToString();

    // Act
    await _authService.SendPasswordResetEmailAsync(userEmail, resetToken);

    // Assert - Check MailHog API for sent email
    var httpClient = new HttpClient();
    var response = await httpClient.GetAsync("http://localhost:8025/api/v2/messages");
    var messages = JsonSerializer.Deserialize<MailHogResponse>(await response.Content.ReadAsStringAsync());
    
    Assert.Single(messages.Items);
    Assert.Contains(resetToken, messages.Items[0].Content.Body);
}

Email Template Verification

With MailHog’s web interface, you can:

• Preview HTML email templates exactly as recipients would see them
• Test responsive design across different screen sizes
• Verify that images and styling render correctly
• Check for broken links or formatting issues

Advanced MailHog Usage

Environment-Specific Configuration

Use different MailHog instances for different environments:

# Development environment
mailhog -smtp-bind-addr 127.0.0.1:1025 -ui-bind-addr 127.0.0.1:8025

# Testing environment  
mailhog -smtp-bind-addr 127.0.0.1:1026 -ui-bind-addr 127.0.0.1:8026

API Integration for Automated Tests

public class MailHogClient
{
    private readonly HttpClient _httpClient;

    public MailHogClient()
    {
        _httpClient = new HttpClient { BaseAddress = new Uri("http://localhost:8025/") };
    }

    public async Task<IEnumerable<Email>> GetEmailsAsync()
    {
        var response = await _httpClient.GetAsync("api/v2/messages");
        var content = await response.Content.ReadAsStringAsync();
        var mailHogResponse = JsonSerializer.Deserialize<MailHogResponse>(content);
        return mailHogResponse.Items;
    }

    public async Task DeleteAllEmailsAsync()
    {
        await _httpClient.DeleteAsync("api/v1/messages");
    }
}

Why I Use MailHog Daily

As someone who works extensively with .NET applications requiring email functionality, MailHog has become an essential part of my development toolkit. Here’s why:

Reliability: No more worrying about test emails reaching real users or bouncing back from invalid addresses.

Speed: Instant email capture and viewing without network delays or external dependencies.

Debugging: The ability to inspect raw email headers and content makes troubleshooting email issues much easier.

Team Collaboration: Developers can share MailHog URLs to demonstrate email functionality during code reviews or testing sessions.

CI/CD Integration: MailHog works perfectly in Docker containers and automated testing pipelines.

Conclusion

MailHog represents the perfect balance of simplicity and functionality for email testing in .NET development. Its open-source nature, zero-configuration setup, and comprehensive feature set make it an invaluable tool for any developer working with email functionality.

Whether you’re building a simple contact form or a complex multi-tenant application with sophisticated email workflows, MailHog provides the testing infrastructure you need without the complexity of traditional email servers.

Give MailHog a try in your next .NET project—you’ll wonder how you ever developed email features without it.

Resources:

• MailHog GitHub Repository
• API Documentation
• MailHog Client Libraries
• WSL Installation Script