Skip to content
Volare Documentation

Mailpit Setup

Mailpit captures all outgoing emails in local development, providing a web UI to view and test email notifications without actual delivery.

What is Mailpit

Section titled “What is Mailpit”

Mailpit is a lightweight SMTP server and web UI for testing emails locally:

  • Captures all outgoing SMTP emails
  • Web interface to view email content
  • No emails actually delivered to real addresses
  • Perfect for notification development and testing

Website: https://mailpit.axllent.org

Configuration

Section titled “Configuration”

Docker Compose

Section titled “Docker Compose”

Mailpit service already configured in docker-compose.yml:

mailpit:
    image: 'axllent/mailpit:latest'
    ports:
        - '${FORWARD_MAILPIT_PORT:-1025}:1025'      # SMTP port
        - '${FORWARD_MAILPIT_DASHBOARD_PORT:-8025}:8025'  # Web UI port
    networks:
        - sail

Source: backend/docker-compose.yml:101-107

Environment Variables

Section titled “Environment Variables”

Add to .env:

MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_FROM_ADDRESS="noreply@volare.test"
MAIL_FROM_NAME="Volare"


# Optional: Custom ports
FORWARD_MAILPIT_PORT=1025
FORWARD_MAILPIT_DASHBOARD_PORT=8025

Default .env.example uses MAIL_MAILER=log - update for email testing.

Usage

Section titled “Usage”

Start Mailpit

Section titled “Start Mailpit”

Mailpit starts automatically with Sail:

Terminal window
./vendor/bin/sail up -d

Access Web UI

Section titled “Access Web UI”

Open browser: http://localhost:8025

Features:

  • View all captured emails
  • Search by recipient, subject, date
  • View HTML and plain text versions
  • Inspect email headers
  • Test responsive email templates

Send Test Notification

Section titled “Send Test Notification”
Terminal window
# Send to first user
./vendor/bin/sail artisan notification:test


# Send to specific email
./vendor/bin/sail artisan notification:test admin@example.com

Check Mailpit UI to see delivered email.

Trigger from Application

Section titled “Trigger from Application”

Any Laravel notification with ‘mail’ channel sends to Mailpit:

$user->notify(new OfferCreatedNotification($offer));

Queue worker must be running:

Terminal window
./vendor/bin/sail artisan queue:work

Ports

Section titled “Ports”
ServicePortURL
Web UI8025http://localhost:8025
SMTP1025mailpit:1025 (internal)

Port conflicts: Update FORWARD_MAILPIT_* env vars if needed.

Testing Email Notifications

Section titled “Testing Email Notifications”

1. Start Services

Section titled “1. Start Services”
Terminal window
./vendor/bin/sail up -d
./vendor/bin/sail artisan queue:work

2. Trigger Notification

Section titled “2. Trigger Notification”

Create offer, booking, or use test command.

3. View in Mailpit

Section titled “3. View in Mailpit”
  1. Open http://localhost:8025
  2. Find email in list
  3. Click to view full content
  4. Verify subject, body, formatting
  5. Test action buttons

4. Verify Content

Section titled “4. Verify Content”

Check:

  • Subject line clear and specific
  • Greeting personalized with user name
  • Content formatted correctly (markdown rendered)
  • Action buttons link correctly
  • Footer includes sender info

Troubleshooting

Section titled “Troubleshooting”

Mailpit UI not accessible:

  • Check Docker container: sail ps
  • Verify port 8025 not in use
  • Check FORWARD_MAILPIT_DASHBOARD_PORT in .env

Emails not appearing:

  • Queue worker running? sail artisan queue:work
  • Check MAIL_HOST=mailpit in .env
  • View logs: sail logs mailpit
  • Verify notification uses ‘mail’ channel

SMTP connection refused:

  • Container running? sail ps
  • Check MAIL_PORT=1025
  • Mailpit service in docker-compose depends_on

Production Configuration

Section titled “Production Configuration”

Never use Mailpit in production.

Production .env should use real SMTP:

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_FROM_ADDRESS="noreply@volare.com"
MAIL_FROM_NAME="Volare"

Or use service-specific mailer:

  • MAIL_MAILER=ses for AWS SES
  • MAIL_MAILER=sendmail for server sendmail
  • MAIL_MAILER=mailgun for Mailgun

Alternative: Log Mailer

Section titled “Alternative: Log Mailer”

For quick local dev without email UI:

MAIL_MAILER=log

Emails written to storage/logs/laravel.log instead of Mailpit.

Less convenient than Mailpit UI but no additional service needed.

Section titled “Related”