Skip to content
Skills Library
Programming · Testing

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

Repository
qa ↗
Licence
MIT
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
15
Scripts
0
HTML comments
0
URLs in SKILL.md
7
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

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

  1. Overview
  2. When to use
  3. Step 1 - Install
  4. Step 2 - Start
  5. Step 3 - Configure your app's SMTP
  6. Step 4 - Assert via REST API
  7. Step 5 - Chaos mode
  8. Step 6 - Tagging + plus-addressing
  9. Step 7 - CI integration
  10. Anti-patterns
Original SKILL.md headings · 230 lines, 893 words
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

RepositoryScoreLicence
This page · testland/qa100MIT
testland/qa-skills100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.