route-mail-to-mailpit

Route application email to Mailpit

Mailpit only captures what is sent to its SMTP port. Before any email verification can work, the application under test must be configured to send there — and you must prove it, not assume it.

Two different addresses — don't confuse them

• SMTP host:port — where the application sends mail (e.g. mailpit-host:1025; deployments often remap the port). No TLS, credentials optional (accepted but ignored).
• MCP endpoint URL — where you (the agent) read the mailbox (e.g. http://mailpit-host:3000/mcp). Never give this to the application.

First call get_mailbox_info: SMTPEndpoint is the authoritative answer — the operator configured exactly where applications must send for THIS mailbox to capture their mail. Compare the project's mail config against it; any other destination (a different Mailpit instance, a real provider) means verification will wait for emails that never arrive here. Do not derive the SMTP port from the MCP URL — they are unrelated.

Prove the mailbox side before debugging the app side: send_smtp_message performs a real SMTP transaction to the endpoint (like an application would) — if it lands (confirm with wait_for_message), the SMTP channel works and any remaining problem is in the app's configuration. If the endpoint names an address unreachable from the MCP server's own network (e.g. localhost:...), pass the tool's endpoint parameter with a network-local address (such as the Mailpit container hostname mailpit:1025) — that still proves Mailpit accepts SMTP, though not the app-visible path.

Configure the application

Find where the app defines its outgoing mail transport and point it at Mailpit — typical spots: SMTP_HOST/SMTP_PORT/MAIL_HOST env vars, Laravel MAIL_*, Django EMAIL_HOST, Rails smtp_settings, Spring spring.mail.*, nodemailer transport options. Set: Mailpit's host and SMTP port, TLS off (or STARTTLS optional), any or no credentials.

Safety check — do this even if routing "already works": scan the app's mail config (all environments that tests touch) for real provider hosts — sendgrid, mailgun, ses/amazonaws, postmark, resend, smtp.gmail.com, office365, or any production SMTP relay. If the test environment can reach a real provider, flag it to the user immediately: test runs could email real people. Verification must never run against a configuration that might deliver externally.