mailpit-testing
/mailpit-testing
The email-testing home: configures and runs Mailpit - modern dev-mailbox server for SMTP testing with built-in REST API for assertions; default SMTP `1025` + Web UI `8025`; Chaos mode (configurable SMTP errors for resilience testing), message tagging, search filters. Carries the end-to-end email-flow workflow (multipart body, link-rewrite resolution, unsubscribe per RFC 8058, bounce + complaint webhooks) in references/email-flows.md and the legacy MailHog capture patterns + migration path in references/mailhog-legacy.md. Use when developing or testing email-sending code locally / in CI - SMTP
- Author
- testland ↗
- Repository
- qa ↗
- Licence
- MIT
- Last repository change
- 20.10.2026
Assessment and security
- Files in this package
- 15
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 7
No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
The email-testing home: configures and runs Mailpit - modern dev-mailbox server for SMTP testing with built-in REST API for assertions; default SMTP `1025` + Web UI `8025`; Chaos mode (configurable SMTP errors for resilience testing), message tagging, search filters. Carries the end-to-end email-flow workflow (multipart body, link-rewrite resolution, unsubscribe per RFC 8058, bounce + complaint webhooks) in references/email-flows.md and the legacy MailHog capture patterns + migration path in references/mailhog-legacy.md. Use when developing or testing email-sending code locally / in CI - SMTP
Original author description
The email-testing home: configures and runs Mailpit - modern dev-mailbox server for SMTP testing with built-in REST API for assertions; default SMTP `1025` + Web UI `8025`; Chaos mode (configurable SMTP errors for resilience testing), message tagging, search filters. Carries the end-to-end email-flow workflow (multipart body, link-rewrite resolution, unsubscribe per RFC 8058, bounce + complaint webhooks) in references/email-flows.md and the legacy MailHog capture patterns + migration path in references/mailhog-legacy.md. Use when developing or testing email-sending code locally / in CI - SMTP
How it works
- Overview
- When to use
- Step 1 - Install
- Step 2 - Start
- Step 3 - Configure your app's SMTP
- Step 4 - Assert via REST API
- Step 5 - Chaos mode
- Step 6 - Tagging + plus-addressing
- Step 7 - CI integration
- Anti-patterns
SKILL.md preview
---
name: mailpit-testing
description: "The email-testing home: configures and runs Mailpit - modern dev-mailbox server for SMTP testing with built-in REST API for assertions; default SMTP `1025` + Web UI `8025`; Chaos mode (configurable SMTP errors for resilience testing), message tagging, search filters. Carries the end-to-end email-flow workflow (multipart body, link-rewrite resolution, unsubscribe per RFC 8058, bounce + complaint webhooks) in references/email-flows.md and the legacy MailHog capture patterns + migration path in references/mailhog-legacy.md. Use when developing or testing email-sending code locally / in CI - SMTP capture, full-flow assertions, or migrating an existing MailHog deployment."
---
# mailpit-testing
## Overview
Per [mailpit.axllent.org/docs/][mp-docs]:
[mp-docs]: https://mailpit.axllent.org/docs/
> "Mailpit is packed full of features for developers wanting to test
> SMTP and emails. It acts as an SMTP server, provides a modern web
> interface to view & test intercepted emails."
Per [mp-docs][mp-docs] the differentiated features:
- "Chaos feature to enable configurable SMTP errors for testing
application resilience."
- "Message tagging, including manual tagging or automated tagging
using filtering and 'plus addressing'."
- "A REST API for integration testing"
Mailpit succeeded MailHog as the de facto OSS dev mailbox in the
mid-2020s; new projects start with Mailpit by default.
## When to use
- The repo has email-sending code (transactional emails, password
reset, notifications) that needs local + CI testing.
- Tests assert on captured email content (subject, body, headers,
attachments).
- The team needs Chaos mode to test app resilience to SMTP errors
(bounce, timeout, rate-limit).
- The full email flow needs coverage beyond capture - headers,
multipart body, links, unsubscribe, bounces - per
[references/email-flows.md](references/email-flows.md).
- Migrating from MailHog (Mailpit is API-compatible at the SMTP
layer + has a richer REST API) - per
[references/mailhog-legacy.md](references/mailhog-legacy.md).
## Step 1 - Install
Per [github.com/axllent/mailpit][mp-gh]:
[mp-gh]: https://github.com/axllent/mailpit
```bash
# macOS
brew install mailpit
# Docker (Linux, macOS, Windows, CI) - per the [mp-docker][mp-docker] image page
docker run -d --name=mailpit --restart unless-stopped -p 8025:8025 -p 1025:1025 axllent/mailpit
```
Docker is the recommended path for CI. [mp-gh][mp-gh] also documents a
shell install script that writes to `/usr/local/bin` with `sudo`; prefer the
image or a release binary so a test setup never pipes remote code into a
root shell.
[mp-docker]: https://hub.docker.com/r/axllent/mailpit
## Step 2 - Start
Per [mp-gh][mp-gh]:
> "The Mailpit web UI listens by default on `http://0.0.0.0:8025`
> and the SMTP port on `0.0.0.0:1025`."
Foreground:
```bash
mailpit
# Web UI: http://localhost:8025
# SMTP: localhost:1025
```
As a background service on macOS:
```bash
brew services start mailpit
```
Discover all options:
```bash
mailpit -h
```
## Step 3 - Configure your app's SMTP
Point the application's SMTP config at Mailpit:
```yaml
# example: Rails action_mailer config
smtp_settings:
address: localhost
port: 1025
domain: localhost
authentication: nil # Mailpit accepts unauthenticated SMTP by default
```
Equivalent envs work for Django (`EMAIL_HOST=localhost`,
`EMAIL_PORT=1025`), Spring (`spring.mail.host=localhost`,
`spring.mail.port=1025`), Node nodemailer, etc.
## Step 4 - Assert via REST API
Per [mp-docs][mp-docs] Mailpit ships a "REST API for integration
testing." The canonical endpoints (consult [mp-docs][mp-docs] for
current paths per release) follow this shape:
```python
import requests
BASE = "http://localhost:8025"
def test_password_reset_sends_email():
# 1. Clear inbox before the test
requests.delete(f"{BASE}/api/v1/messages")
# 2. Trigger the email send
trigger_password_reset("alice@example.com")
# 3. Poll until the email lands (typical: <1s)
msg = poll_for_message(BASE, to="alice@example.com", timeout=5)
# 4. Assert
assert msg["Subject"] == "Reset your password"
assert "/reset?token=" in msg["Text"]
assert msg["To"][0]["Address"] == "alice@example.com"
```
```python
def poll_for_message(base, to, timeout):
import time
deadline = time.time() + timeout
while time.time() < deadline:
response = requests.get(f"{base}/api/v1/search", params={"query": f"to:{to}"})
messages = response.json().get("messages", [])
if messages:
return requests.get(f"{base}/api/v1/message/{messages[0]['ID']}").json()
time.sleep(0.1)
raise AssertionError(f"No email to {to} within {timeout}s")
```
The exact endpoint paths may evolve - always check the live API
schema at `http://localhost:8025/api/v1/` (Mailpit ships an
OpenAPI schema for self-introspection).
## Step 5 - Chaos mode
Per [mp-docs][mp-docs]: "Chaos feature to enable configurable SMTP
errors for testing application resilience."
Use cases for app-level resilience testing:
- Verify retry-with-backoff works when SMTP returns 421 / 451
- Verify dead-letter handling for permanent failures (5xx)
- Verify rate-limit handling (server returns 421 4.7.0)
Per [mp-docs][mp-docs], Chaos is configurable per-recipient or
globally; consult the live docs for current Chaos API shape.
## Step 6 - Tagging + plus-addressing
Per [mp-docs][mp-docs]: "automated tagging using filtering and
'plus addressing'."
Pattern for test-isolation: each test sends to
`alice+test-${test_id}@example.com`; Mailpit auto-tags by the
`+test-...` suffix; tests filter by tag to isolate their email
batch from concurrent test runs:
```python
import uuid
test_id = uuid.uuid4().hex[:8]
to_addr = f"alice+test-{test_id}@example.com"
trigger_email(to_addr)
msg = requests.get(
f"{BASE}/api/v1/search",
params={"query": f'tag:"test-{test_id}"'},
).json()["messages"][0]
```
## Step 7 - CI integration
```yaml
services:
mailpit:
image: axllent/mailpit:latest
ports: [1025:1025, 8025:8025]
steps:
- run: pytest tests/integration/email/ -v
env:
SMTP_HOST: localhost
SMTP_PORT: 1025
```
## Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Skip per-test inbox clear | Stale messages cause false-positives | DELETE /api/v1/messages in setup (Step 4) |
| Assume Mailpit handles authenticated SMTP | Default config is unauthenticated; auth tests need explicit config | Configure `--smtp-auth-allow-insecure` or proper auth config |
| Hardcode message IDs in tests | IDs are random per send; tests fail | Search by recipient/subject (Step 4) |
| Skip polling; assert immediately | Sub-second SMTP delivery isn't guaranteed | Poll with timeout (Step 4) |
| Test only happy path | Misses retry/dead-letter scenarios | Use Chaos mode (Step 5) |
## Limitations
- Mailpit does NOT actually deliver email - it only captures. For
end-to-end deliverability tests, use a real-mail-with-test-domain
service (Mailtrap, Mailosaur).
- Some advanced SMTP features (DKIM signing assertion, SPF lookup)
are not Mailpit's focus; verify via separate tooling.
- The REST API surface evolves between Mailpit releases; pin a
specific version in CI (`axllent/mailpit:v1.20.0` not `:latest`).
## References
- [mp-docs][mp-docs] - official documentation
- [mp-gh][mp-gh] - repository, install commands, ports
- [mp-docker][mp-docker] - Docker image and `docker run` example (ports 8025 / 1025)
- mailpit.axllent.org/docs/api-v1/ - REST API reference
- End-to-end email-flow workflow (headers, multipart, links,
unsubscribe, bounces): [references/email-flows.md](references/email-flows.md)
- MailHog (legacy) capture + migration:
[references/mailhog-legacy.md](references/mailhog-legacy.md)
(+ [references/migrating-to-mailpit.md](references/migrating-to-mailpit.md))
Files in this package (15)
- SKILL.md 8 KB
- .tessl-plugin/plugin.json 1 KB
- evals/auditor-checklist-half-of-which-we-cannot-verify-here/criteria.json 7 KB
- evals/auditor-checklist-half-of-which-we-cannot-verify-here/task.md 10 KB
- evals/four-workers-wiping-each-others-inbox/criteria.json 7 KB
- evals/four-workers-wiping-each-others-inbox/task.md 14 KB
- evals/green-suite-while-reset-links-shipped-broken/criteria.json 6 KB
- evals/green-suite-while-reset-links-shipped-broken/task.md 7 KB
- evals/retry-queue-written-after-the-relay-outage/criteria.json 5 KB
- evals/retry-queue-written-after-the-relay-outage/task.md 8 KB
- evals/smtp-auth-typo-that-only-staging-caught/criteria.json 5 KB
- evals/smtp-auth-typo-that-only-staging-caught/task.md 7 KB
- references/email-flows.md 8 KB
- references/mailhog-legacy.md 6 KB
- references/migrating-to-mailpit.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · testland/qa | 100 | MIT |
| testland/qa-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version 52fe43f85928 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95nette-mail
Invoke before writing or reviewing code that sends email with nette/mail. Covers Nette\Mail\Message (setFrom, addTo/addCc/addBcc, setSubject, setBody, setHtmlBody with automatic image embedding, addEmbeddedFile, addAttachment, setUnsubscribe), sending Latte templates as email,… - 100sending-emails
Use when integrating, configuring, or troubleshooting Mailtrap live email sending (Email API or SMTP). Use when wiring outbound mail from an application or choosing how to send. - 100email-smtp-send
Send emails through SMTP with optional local attachments and optional IMAP APPEND sync to Sent mailbox. Use when tasks need reliable outbound email delivery, attachment sending, SMTP connectivity checks, or cross-client sent-mail visibility (for example appending to "Sent Items" after SMTP send). - 85email-testing
End-to-end testing of email-dependent flows — signup confirmation, password reset, magic-link login, OTP/MFA codes, and notification emails. Covers the capture-inbox decision tree (Mailpit, Mailosaur, MailSlurp, ShazaMail, Ethereal), Playwright polling without fixed sleeps,… - 100drupal-mail
Drupal mail system configuration for local testing (Mailpit) and production (Mailchimp Transactional). Covers HTML email rendering, Content-Type headers, sender/formatter plugins, and troubleshooting. Use when testing emails locally, debugging email issues, or configuring mail delivery. - 100orchardcore-email-smtp
Skill for configuring SMTP email delivery in Orchard Core. Covers SmtpSettings, SmtpOptions, DefaultSmtpOptions, SmtpEmailProvider, DefaultSmtpEmailProvider, SmtpEmailProviderBase, the OrchardCore Email Smtp configuration section, pickup directories and…