Mock Your Email Server, Not Your Users: Testing with Papercut SMTP

One of the most underrated tools in my development workflow—both at work and at home—is Papercut SMTP.

Whether I’m working on a Point of Sale (POS) eReceipt or report that needs to email PDFs to customers or testing alert notifications from a self-hosted service in my homelab, I don’t want those test emails going out to real people. I also don’t want to deal with the overhead of setting up a real SMTP server for every project.

That’s where Papercut SMTP comes in—letting me test emails safely without the risk or hassle of a real mail server.

What Is Papercut SMTP?

Papercut is a local SMTP server designed for developers. It accepts email messages but doesn’t actually deliver them—it just captures and displays them. You can view the content, subject, headers, attachments, and everything else you need to verify your app is working as expected.

There are two flavors:

• Desktop app: Great for quick local use, with a GUI viewer.
• Docker container: Ideal for headless or server environments.

How I Use It in Point of Sale Development

At work, most of our Point of Sale systems send emails for things like:

• Scheduled reports
• End-of-day summaries
• Loyalty program communications
• Electronic receipts

I configure my development environments to point to Papercut SMTP instead of a real mail server. That way:

• Reports still get “sent” but stay local
• I can review formatting, PDF attachments, and delivery metadata
• There’s no risk of someone accidentally emailing a real customer

When I make changes to email templates, I fire off a test run and instantly see the results in Papercut. No mail relay setup. No fake accounts. No “oops” emails.

Using It in My Home Lab

My home lab is full of self-hosted services—Home Assistant, Docker containers, backup systems, and monitoring tools. Many of these support email notifications for alerts or summaries. Sometimes before I set up real SMTP notifications in these services, I use Papercut to test it out and make any changes to the emails before pointing it at a live SMTP server.

Docker Setup

Since I work from home, I mostly use the Docker container version of Papercut for the convenience of having an always running local-only version for work and home.

version: "3.9"
services:
  papercut:
    image: changemakerstudios/papercut:latest
    ports:
      - "25:25"     # SMTP port
      - "8081:80"   # Web UI
    restart: unless-stopped

Now anything for work or my homelab that needs to “send” email can just point to port 25 on the Docker host. I open the web UI at http://[host]:8081 and view any messages that come through.

Simple, safe, and no passwords or relay configs needed.

Papercut Web UI in Docker

Desktop App for Local Testing

On my development machine, I’ll occasionally fire up the Papercut desktop version for ad hoc testing. It gives you a GUI to browse received messages, preview them in HTML or plain text, and inspect headers.

This is especially useful when testing Point of Sale integrations or apps that only run locally on Windows. It’s as easy as:

1. Install and launch the app
2. Point your SMTP settings to localhost:25
3. Watch the email appear instantly

Why Not Use a Real SMTP Server?

Short answer: too risky and too much hassle.

Longer answer:

• Accidental emails to customers or staff
• Need to whitelist test recipients
• Gmail and others can rate-limit or block your test traffic
• Requires auth and proper domain configuration

Papercut avoids all of that. It keeps emails in the dev/test bubble where they belong.

Tip

Some email programs such as Outlook may not support all the HTML that is supported in the Papercut UI. As a result the email may look fine in Papercut, but not when opened in a program such as Outlook. Papercut saves the emails it receives in .eml files that can be opened with Outlook and other email programs. I will usually double check by opening the files.

With the Docker version of Papercut there is a Save raw message link to download the .eml file. In the desktop version you can right click on the message and select the Open Containing Folder option.

Final Thoughts

If you work on anything that sends email—Point of Sale systems, web apps, Home Assistant automations—you need something like Papercut SMTP in your toolbox.

It’s dead simple to use, runs locally or in Docker, and prevents the kind of embarrassing mistakes that happen when a test script emails the entire customer list.

It’s one of those tools that just works—and has saved me more than once.