SMTP catcher

What it is

The SMTP catcher is a mail server for your test, QA and staging systems that never delivers anything. Change only the SMTP settings of the app (host, port, user name, password) to ours: every message it sends, to any address, lands in one MailPier environment, where you read it in the web inbox or through the API. Real customers in a copied database can never get a test mail.

• Every recipient is rewritten into the environment you log in to: jane@contoso.com becomes jane@contoso.com.qa.acme.mailpier.io and the inbox shows "intended for jane@contoso.com" with a "via SMTP catcher" badge. Addresses already in that environment are kept as they are.
• The message itself is stored as your app sent it: the To and Cc headers are not changed. Two headers are added on top: X-MailPier-Catcher (the SMTP user name) and X-MailPier-Original-Recipients (the addresses your app used).
• The plan's limits apply as for any other mail: each recipient counts as a message, and the plan's message size is enforced.
• Part of every plan, Free included: the plan's message, rate and size limits apply. See /pricing.

Set it up

1. Open the environment that should catch the mail (for example qa), tab SMTP. Managers and account admins see it.
2. Create a password and copy it (it is shown once). An environment can have up to 10 active passwords, for example one per app; revoke one any time.
3. Put the settings below into the app's configuration and send a test mail.

Settings

.NET

appsettings (keep the password in user secrets, a key vault or a pipeline secret, not in the file):

"Smtp": {
  "Host": "smtp.mailpier.io",
  "Port": 587,
  "UserName": "qa.acme",
  "Password": "mps_..."
}

MailKit (recommended):

// dotnet add package MailKit
using MailKit.Net.Smtp;
using MailKit.Security;
using MimeKit;

var message = new MimeMessage();
message.From.Add(MailboxAddress.Parse("noreply@yourapp.example"));
message.To.Add(MailboxAddress.Parse("jane@contoso.com"));   // caught as jane@contoso.com.qa.acme.mailpier.io
message.Subject = "Welcome";
message.Body = new TextPart("plain") { Text = "Hello Jane" };

using var client = new SmtpClient();
await client.ConnectAsync(config["Smtp:Host"], 587, SecureSocketOptions.StartTls);   // 465: SecureSocketOptions.SslOnConnect
await client.AuthenticateAsync(config["Smtp:UserName"], config["Smtp:Password"]);
await client.SendAsync(message);
await client.DisconnectAsync(true);

System.Net.Mail.SmtpClient (works on 587/2525 only: it cannot do TLS from the start, so not 465):

using System.Net;
using System.Net.Mail;

using var smtp = new SmtpClient("smtp.mailpier.io", 587)
{
    EnableSsl = true,   // STARTTLS
    Credentials = new NetworkCredential("qa.acme", Environment.GetEnvironmentVariable("MAILPIER_SMTP_PASSWORD")),
};
smtp.Send("noreply@yourapp.example", "jane@contoso.com", "Welcome", "Hello Jane");

Node.js (nodemailer)

// npm install nodemailer
const nodemailer = require("nodemailer");

const transport = nodemailer.createTransport({
  host: "smtp.mailpier.io",
  port: 587,
  secure: false,        // STARTTLS on 587/2525; use port 465 with secure: true for TLS from the start
  requireTLS: true,
  auth: { user: "qa.acme", pass: process.env.MAILPIER_SMTP_PASSWORD },
});

await transport.sendMail({
  from: "noreply@yourapp.example",
  to: "jane@contoso.com",
  subject: "Welcome",
  text: "Hello Jane",
});

Python (smtplib)

import os, smtplib, ssl
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "noreply@yourapp.example"
msg["To"] = "jane@contoso.com"
msg["Subject"] = "Welcome"
msg.set_content("Hello Jane")

with smtplib.SMTP("smtp.mailpier.io", 587) as s:          # 465: smtplib.SMTP_SSL("smtp.mailpier.io", 465, context=ssl.create_default_context())
    s.starttls(context=ssl.create_default_context())
    s.login("qa.acme", os.environ["MAILPIER_SMTP_PASSWORD"])
    s.send_message(msg)

Java / Spring Boot

application.properties (Spring's JavaMailSender):

spring.mail.host=smtp.mailpier.io
spring.mail.port=587
spring.mail.username=qa.acme
spring.mail.password=${MAILPIER_SMTP_PASSWORD}
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true

PHP / Laravel

.env:

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailpier.io
MAIL_PORT=587
MAIL_USERNAME=qa.acme
MAIL_PASSWORD=mps_...
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourapp.example

WordPress (WP Mail SMTP)

1. Install and activate the WP Mail SMTP plugin on the test or staging site.
2. WP Mail SMTP → Settings → Mailer: Other SMTP.
3. SMTP Host smtp.mailpier.io, Encryption TLS, SMTP Port 587, Auto TLS on.
4. Authentication on, SMTP Username qa.acme, SMTP Password your mps_... password (or define WPMS_SMTP_PASS in wp-config.php so it is not stored in the database).
5. Save, then use the plugin's Email Test tab. The test mail appears in the environment's inbox.

Troubleshooting

Questions