Mailpit for local development

Test emails locally with Mailpit, a disposable SMTP server included in MakerKit's Docker Compose. All emails sent during development are captured at localhost:8025 instead of reaching real inboxes. Mailpit starts automatically with docker compose up and requires no configuration - your existing Nodemailer settings work out of the box.

This guide is part of the Email Configuration documentation.

Definition: Mailpit is a local SMTP server that captures all outgoing emails for inspection, providing a web UI at localhost:8025 to view, debug, and test email content without sending to real addresses.

Use Mailpit when: developing locally to test any email flow (auth, invitations, notifications). Switch to real SMTP when: testing deliverability, SPF/DKIM, or production email rendering. Avoid Mailpit in CI when: you need to verify emails programmatically - use Mailpit's API or a test SMTP service instead. If unsure: always use Mailpit locally - accidentally sending real emails during development is embarrassing.

When developing locally, use Mailpit to capture emails. It intercepts all SMTP traffic and displays emails in a web interface - no emails reach real inboxes.

What is Mailpit?

Mailpit is a disposable email service that captures all emails sent during local development. It's particularly useful for testing:

• Email verification flows
• Password reset emails
• Team invitations
• Notification emails
• Any other transactional emails

Accessing Mailpit

When running the development Docker Compose file, Mailpit is automatically available at:

# Start the development services (including Mailpit)
pnpm run compose:dev:up
# Mailpit web UI
http://localhost:8025

You can view any captured emails by:

1. Going to http://localhost:8025
2. Finding your test email in the list of received messages

Common Use Cases

1. Email Verification

When testing user signup:

1. Create a new account using any email address
2. Go to Mailpit at http://localhost:8025
3. Find the verification email
4. Click the verification link or copy the verification code

2. Password Reset

To test password reset flows:

1. Request a password reset using any email
2. Check InBucket/Mailpit for the reset email
3. Use the reset link or code to complete the process

3. Team Invitations

When testing team invites:

1. Send an invitation to any email address
2. Check Mailpit for the invitation email
3. Use the invitation link to accept

Mailpit vs Production Emails

Remember that Mailpit is for development only. In production:

1. Configure a proper email service provider (Resend, SendGrid, etc.)
2. Set up proper email authentication (SPF, DKIM)
3. Use production-grade SMTP settings
4. Monitor email deliverability

Using a different email provider during local development

If you want to use a different email provider, switch the environment variables at apps/web/.env.development:

EMAIL_SENDER=test@makerkit.dev
EMAIL_PORT=
EMAIL_HOST=
EMAIL_TLS=
EMAIL_USER=
EMAIL_PASSWORD=

We've found Mailpit invaluable during MakerKit development - it catches email bugs before they reach production, and the HTML preview helps verify template rendering across email clients.

Common Pitfalls

• Mailpit not running: Emails silently fail if Mailpit isn't running. Start it with docker compose up before testing email flows.
• Wrong port in .env.development: Mailpit uses port 1025 for SMTP, not 8025 (that's the web UI). Check EMAIL_PORT=1025 in development.
• Production credentials in .env.development: Never put real SMTP credentials in .env.development. Mailpit doesn't need credentials - leave them empty or use dummy values.
• Emails not appearing: Check that your EMAIL_HOST points to localhost or mailpit (if using Docker networking). External hosts bypass Mailpit.
• Testing with Resend locally: Resend uses HTTP, not SMTP. It bypasses Mailpit entirely. For local testing, use MAILER_PROVIDER=nodemailer with Mailpit.
• Clearing old emails: Mailpit stores emails in memory by default. Restart Docker to clear them, or use Mailpit's delete API.

Previous: Custom Mailer