# Email Testing > Use when a QA agent (bug-replicator, flow-executor, integration) detects email-touching work in its slice — template files, SMTP / transactional-email client imports, or email-sending function calls. The cross-cutting email-testing discipline that uses Mailpit (a local SMTP trap, zero external dependencies) as the default capture engine. The body documents the four phases (E1 detect email surface, E2 provision Mailpit, E3 capture sent emails + classify every link by reading template source, E4 follow every link in Playwright and complete each user flow it initiates), the rule that the agent reads the template source BEFORE the send, that EVERY link in EVERY email is tested (not just the primary CTA), mandatory teardown, and the project-level design.md provider override. - Skill: `paulingram/email-testing` (Agent Skill) - Install (CLI): `npx skillmds@latest add paulingram/email-testing` - Raw SKILL.md: https://api.skillmd.com/api/skills/paulingram/email-testing/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: paulingram (https://skillmd.com/u/paulingram) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/paulingram/email-testing --- # email-testing — Cross-cutting email-testing discipline Email-dependent flows — invite-to-sign-up, password reset, notification click-throughs, verification links, unsubscribe — are a testing blind spot when dev environments lack a real inbox. The feature works in the UI, the email fires, but nobody follows the link to see if the destination page actually renders, the token is valid, or the form submits. This skill closes that gap by providing a discipline any QA agent can activate: capture the email locally, read every link, navigate to every link in Playwright, and complete the flow each link initiates. It is cross-cutting — not a standalone phase or agent, but a discipline that existing agents (bug-replicator, flow-executor, integration) consume at their natural insertion points when they detect email-touching work in their slice. ## Five non-negotiable rules 1. **Mailpit by default.** Local, zero-config, no API key. Project MAY override via a `## Email Testing` section in `design.md`. The override names the provider + connection details; the skill respects it but Mailpit is the structural default. 2. **Every link gets tested.** Not just the primary CTA — every `` tag, every form action, every attachment. A broken unsubscribe link is a compliance bug. 3. **Template source is read first.** The agent reads the template file to understand the email's purpose BEFORE triggering the send. Purpose informs assertions on destination pages. 4. **Teardown is mandatory.** Mailpit must be stopped after the test run. A dangling SMTP trap that intercepts emails in the next run is a structural failure. 5. **Credentials use env-var discipline.** Test passwords for email-linked sign-up flows come from env vars or documented test-data conventions — never hardcoded secrets in artifacts. ## Activation trigger — when does this discipline fire? The email-testing discipline activates **automatically** when the QA agent detects ANY of the following in its work slice's touched files or the coverage map's implementing paths: ### File-path indicators Template files in email-related paths: - `*.html`, `*.mjml`, `*.ejs`, `*.hbs`, `*.pug`, `*.liquid`, `*.jinja2` in paths containing `email`, `mail`, `template`, `notification`, `invite`, `welcome`, `reset`, `verify`, `confirm` ### Import indicators SMTP or transactional-email client imports in touched source files: - `nodemailer`, `@sendgrid/mail`, `@aws-sdk/client-ses`, `aws-sdk/clients/ses`, `postmark`, `mailgun`, `resend`, `@mailchimp/transactional`, `smtp`, `createTransport`, `SESClient`, `SendEmailCommand` > The indicators above cover the Node.js / JavaScript ecosystem. For other languages, also scan for: **Python** — `smtplib`, `django.core.mail`, `flask_mail`, `emails`; **Go** — `net/smtp`, `gomail`; **Java** — `javax.mail`, `jakarta.mail`, `JavaMailSender`; **Ruby** — `ActionMailer`, `Mail`; **PHP** — `PHPMailer`, `SwiftMailer`, `Symfony\Mailer`. The agent extends this list based on the target project's language. ### Function-call indicators Email-sending function calls in touched source files: - `sendMail`, `sendEmail`, `send_mail`, `send_email`, `deliver`, `notify`, `sendNotification`, `send_notification`, `sendInvite`, `send_invite`, `sendVerification`, `sendPasswordReset`, `sendWelcome` When ANY indicator is detected, the discipline activates. The agent does NOT ask whether to activate — this is automatic, like the selector witness. ## Phase E1 — Email Surface Detection The agent (bug-replicator, flow-executor, or integration) scans its work slice: 1. **Read the coverage map's implementing paths** for this slice. Grep each path for the file-path, import, and function-call indicators above. 2. **If any indicator matches:** record the email surface in a structured detection block: ```json { "email_surface_detected": true, "indicators": [ { "kind": "file_path", "path": "src/emails/invite.html", "pattern": "email template" }, { "kind": "import", "path": "src/services/email.ts", "symbol": "nodemailer" }, { "kind": "function_call", "path": "src/controllers/invite.ts", "symbol": "sendInvite" } ], "template_files": ["src/emails/invite.html", "src/emails/welcome.html"], "email_service_files": ["src/services/email.ts"] } ``` 3. **If no indicator matches:** `email_surface_detected: false` — skip E2-E4. The discipline is dormant for this slice. ## Phase E2 — Mailpit Provisioning When email surface is detected, the agent provisions Mailpit as the SMTP trap BEFORE triggering any email-sending action. ### Docker (preferred) ```bash docker rm -f mailpit-test 2>/dev/null || true docker run -d --name mailpit-test -p 1025:1025 -p 8025:8025 axllent/mailpit ``` ### Binary fallback (no Docker) ```bash # Download for the host OS # Linux: curl -sL https://github.com/axllent/mailpit/releases/latest/download/mailpit-linux-amd64.tar.gz | tar xz # macOS: curl -sL https://github.com/axllent/mailpit/releases/latest/download/mailpit-darwin-amd64.tar.gz | tar xz # Windows: curl -sL https://github.com/axllent/mailpit/releases/latest/download/mailpit-windows-amd64.zip -o mailpit.zip && unzip mailpit.zip ./mailpit --smtp 0.0.0.0:1025 --listen 0.0.0.0:8025 & # Windows (PowerShell): Start-Process -FilePath .\mailpit.exe -ArgumentList '--smtp', '0.0.0.0:1025', '--listen', '0.0.0.0:8025' -WindowStyle Hidden ``` ### Dev environment configuration The agent configures the target project's dev environment to route SMTP through Mailpit. The mechanism depends on the project: - **Environment variables** (most common): set `SMTP_HOST=localhost`, `SMTP_PORT=1025` (or the project's equivalent — `MAIL_HOST`, `EMAIL_HOST`, `MAILER_HOST`, etc.) - **Config file override**: if the project uses a config file for SMTP settings, create a test-specific override - **Design.md override**: if the project's `design.md` has a `## Email Testing` section naming a different provider (Mailtrap, MailSlurp, etc.), use that instead of Mailpit. The section must provide: provider name, SMTP host/port or API endpoint, and the env-var NAME for the API key. ### Reachability check After provisioning, verify Mailpit is alive: ```bash curl -fsS -o /dev/null -w "%{http_code}" http://localhost:8025/api/v1/messages ``` Expected: 200. If unreachable after 10s, the agent exits with `env-failure` for the email portion of the test — Mailpit provisioning failure does NOT block non-email tests in the same slice. ### Teardown (mandatory — wired as a finally block) After ALL email tests in the slice complete (pass or fail): ```bash docker stop mailpit-test && docker rm mailpit-test 2>/dev/null || true # Or for binary: kill the mailpit process ``` The agent MUST tear down Mailpit. A dangling SMTP trap is a structural failure — it will intercept emails in subsequent test runs and cause false negatives. Wire the teardown as a `try/finally` or equivalent; it runs regardless of test outcome. ## Phase E3 — Email Capture + Template Analysis ### Step 1 — Read the template source (BEFORE triggering the send) For each template file detected at E1: 1. **Read the template file** via the Read tool. Parse the HTML structure. 2. **Identify the email's purpose** from the template's content: - Subject line (or subject template variable name) - Primary CTA button/link text - Surrounding copy (headings, paragraphs) - Template name / path conventions 3. **Pre-extract link patterns** from the template — these are the links the agent EXPECTS to find in the captured email. Template variables (e.g., `{{inviteUrl}}`, `${resetLink}`, `<%= verifyUrl %>`) are recorded as patterns; the agent will match them against the rendered links in the captured email. Record the template analysis: ```json { "template_path": "src/emails/invite.html", "purpose": "Team invitation — invites a user to join an organization", "subject_pattern": "You've been invited to join {{orgName}}", "expected_links": [ { "template_var": "{{inviteUrl}}", "purpose": "invite-accept", "expected_flow": "sign-up form" }, { "template_var": "{{helpUrl}}", "purpose": "general", "expected_flow": "help page loads" } ], "expected_attachments": [] } ``` ### Step 2 — Trigger the email-sending action via UI The agent triggers the email send through the same Playwright user-flow discipline it was already running — `page.click('Send Invite')` / `page.fill('#email', ...)` / `page.click('#submit')`. The email-sending action is a UI interaction, NOT a direct API call. This is the existing `playwright-user-flows` discipline; the email-testing skill does not change it. ### Step 3 — Capture the email via Mailpit API Before polling, clear residual messages from prior tests to prevent stale matches: ```typescript // Pre-test cleanup — ensures polling only matches emails from this test await fetch(`${apiBase}/api/v1/messages`, { method: 'DELETE' }); ``` Poll Mailpit using its **search API** (server-side filtering — no client-side ceiling): ```typescript // Playwright helper pattern (inline in the .spec.ts) async function waitForEmail( apiBase: string = 'http://localhost:8025', timeoutMs: number = 30000, pollIntervalMs: number = 1000, filter: { to: string; subject?: RegExp } ): Promise { const query = `to:"${filter.to}"` + (filter.subject ? ` subject:"${filter.subject.source}"` : ''); const deadline = Date.now() + timeoutMs; while (Date.now() < deadline) { const res = await fetch( `${apiBase}/api/v1/search?query=${encodeURIComponent(query)}` ); const data = await res.json(); if (data.messages?.length > 0) { // Fetch full message with HTML body const fullRes = await fetch( `${apiBase}/api/v1/message/${data.messages[0].ID}` ); return await fullRes.json(); } await new Promise(r => setTimeout(r, pollIntervalMs)); } throw new Error(`Email not received within ${timeoutMs}ms`); } ``` ### Step 4 — Parse + classify every link From the captured email's HTML body: 1. Extract every `` link 2. Extract every `