MailCatcher Updated

Catches mail and serves it through a dream.

Stack

• Ruby 3.3.x;
• Sinatra 3.1.x;
• Thin server 1.8.x;
• Docker;
• For more, check the Gemfile.

About the project

This is a fork of MailCatcher that runs a super simple SMTP server which catches any message sent to it to display in a web interface. Run mailcatcher, set your favourite app to deliver to smtp://localhost:1025 instead of your default SMTP server, then check out http://localhost:1080 to see the mail that's arrived so far.

The main differences about our projects are:

• I want to follow another way than make it a gem. At my viewpoint I prefer to spend some time to make it better as an dockerized API. I removed everything that made it look like this project is a simple gem, without changing the essence as a service;
• Basic HTTP auth available.

How to run this project

cp .env.sample .env
docker-compose up --build

Go to http://localhost:1080 and send mail through smtp://localhost:1025.

Use the public docker image (production)

FROM dcotecnologia:latest

Setup the env vars to use the basic auth

MAILCATCHER_AUTH_USER=thomas
MAILCATCHER_AUTH_PASSWORD=turbando

Features

• Catches all mail and stores it for display.
• Shows HTML, Plain Text and Source version of messages, as applicable.
• Rewrites HTML enabling display of embedded, inline images/etc and opens links in a new window.
• Lists attachments and allows separate downloading of parts.
• Download original email to view in your native mail client(s).
• Command line options to override the default SMTP/HTTP IP and port settings.
• Mail appears instantly if your browser supports websockets, otherwise updates every thirty seconds.
• Runs as a daemon in the background, optionally in foreground.
• Sendmail-analogue command, catchmail, makes using mailcatcher from PHP a lot easier.
• Keyboard navigation between messages

Command Line Options

Use mailcatcher --help to see the command line options.

Usage: bin/mailcatcher [options]

MailCatcher v1.0.0

        --ip IP                      Set the ip address of both servers
        --smtp-ip IP                 Set the ip address of the smtp server
        --smtp-port PORT             Set the port of the smtp server
        --http-ip IP                 Set the ip address of the http server
        --http-port PORT             Set the port address of the http server
        --messages-limit COUNT       Only keep up to COUNT most recent messages
        --http-path PATH             Add a prefix to all HTTP paths
        --no-quit                    Don't allow quitting the process
    -f, --foreground                 Run in the foreground
    -b, --browse                     Open web browser
    -v, --verbose                    Be more verbose
    -h, --help                       Display this help information
        --version                    Display the current version

Rails

To set up your rails app, I recommend adding this to your environments/development.rb:

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = { :address => '127.0.0.1', :port => 1025 }
config.action_mailer.raise_delivery_errors = false

PHP

For projects using PHP, or PHP frameworks and application platforms like Drupal, you can set PHP's mail configuration in your php.ini to send via MailCatcher with:

sendmail_path = /usr/bin/env catchmail -f [email protected]

You can do this in your Apache configuration like so:

php_admin_value sendmail_path "/usr/bin/env catchmail -f [email protected]"

If you've installed via RVM this probably won't work unless you've manually added your RVM bin paths to your system environment's PATH. In that case, run which catchmail and put that path into the sendmail_path directive above instead of /usr/bin/env catchmail.

If starting mailcatcher on alternative SMTP IP and/or port with parameters like --smtp-ip 192.168.0.1 --smtp-port 10025, add the same parameters to your catchmail command:

sendmail_path = /usr/bin/env catchmail --smtp-ip 192.160.0.1 --smtp-port 10025 -f [email protected]

Django

For use in Django, add the following configuration to your projects' settings.py

if DEBUG:
    EMAIL_HOST = '127.0.0.1'
    EMAIL_HOST_USER = ''
    EMAIL_HOST_PASSWORD = ''
    EMAIL_PORT = 1025
    EMAIL_USE_TLS = False

Docker

There is a Docker image available on Docker Hub:

docker run -p 1080 -p 1025 sj26/mailcatcher
Unable to find image 'sj26/mailcatcher:latest' locally
latest: Pulling from sj26/mailcatcher
8c6d1654570f: Already exists
f5649d186f41: Already exists
b850834ea1df: Already exists
d6ac1a07fd46: Pull complete
b609298bc3c9: Pull complete
ab05825ece51: Pull complete
Digest: sha256:b17c45de08a0a82b012d90d4bd048620952c475f5655c61eef373318de6c0855
Status: Downloaded newer image for sj26/mailcatcher:latest
Starting MailCatcher v0.9.0
==> smtp://0.0.0.0:1025
==> http://0.0.0.0:1080

How those ports appear and can be accessed may vary based on your Docker configuration. For example, your may need to use http://127.0.0.1:1080 etc instead of the listed address. But MailCatcher will run and listen to those ports on all IPs it can from within the Docker container.

API

A fairly RESTful URL schema means you can download a list of messages in JSON from /messages, each message's metadata with /messages/:id.json, and then the pertinent parts with /messages/:id.html and /messages/:id.plain for the default HTML and plain text version, /messages/:id/parts/:cid for individual attachments by CID, or the whole message with /messages/:id.source.

Thanks

MailCatcher is just a mishmash of other people's hard work. Thank you so much to the people who have built the wonderful guts on which this project relies. Thanks to all the contributors from the original repo.

License

Released under the MIT License, see LICENSE for details.