Go to file
Travis Burtrum 1c049fc071 Send deletes across websocket and handle in poll as well so deletes update in realtime 2016-08-11 12:52:04 -04:00
assets Send deletes across websocket and handle in poll as well so deletes update in realtime 2016-08-11 12:52:04 -04:00
bin Bring `catchmail` closer to `sendmail` 2015-01-17 15:21:13 +11:00
examples An example that used to break 2014-03-26 12:33:38 +11:00
lib Send deletes across websocket and handle in poll as well so deletes update in realtime 2016-08-11 12:52:04 -04:00
public Switch to sprockets for assets 2014-03-17 19:06:32 +11:00
spec Placate ambiguous argument warning 2015-01-17 15:08:42 +11:00
vendor/assets/javascripts Remove fractal analysis, it doesn't work at the moment anyway 2014-03-26 20:33:37 +11:00
views Add --show-from-server option to parse the server from the Recieved header and display in a column, off by default 2016-08-11 08:23:33 -04:00
.gitignore Remove Gemfile lock 2016-01-15 17:10:25 +11:00
.travis.yml Use new travis infrastructure 2016-01-15 17:22:04 +11:00
Dockerfile Simplify and fix docker builder 2016-04-07 11:10:33 +10:00
Gemfile Fix mime-types in Gemfile 2016-07-26 21:20:34 +10:00
LICENSE Update LICENSE year 2011-05-31 06:48:57 -07:00
README.md Recommend turning off raise delivery errors 2016-08-10 10:03:45 +10:00
Rakefile Testing needs compiled assets 2014-06-05 21:08:52 +10:00
mailcatcher.gemspec We don't need no support 2016-04-23 15:53:56 +08:00



Catches mail and serves it through a dream.

MailCatcher 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:// instead of your default SMTP server, then check out to see the mail that's arrived so far.

MailCatcher screenshot


  • 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 open 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 run in the background.
  • Sendmail-analogue command, catchmail, makes using mailcatcher from PHP a lot easier.
  • Written super-simply in EventMachine, easy to dig in and change.
  • Keyboard navigation between messages


  1. gem install mailcatcher
  2. mailcatcher
  3. Go to http://localhost:1080/
  4. Send mail through smtp://localhost:1025

Use mailcatcher --help to see the command line options. The brave can get the source from the GitHub repository.


Please don't put mailcatcher into your Gemfile. It will conflict with your applications gems at some point.

Instead, pop a note in your README stating you use mailcatcher. Simply run gem install mailcatcher then mailcatcher to get started.


Under RVM your mailcatcher command may only be available under the ruby you install mailcatcher into. To prevent this, and to prevent gem conflicts, install mailcatcher into a dedicated gemset and create wrapper scripts:

rvm default@mailcatcher --create do gem install mailcatcher
rvm wrapper default@mailcatcher --no-prefix mailcatcher catchmail


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 => "localhost", :port => 1025 }
config.action_mailer.raise_delivery_errors = false


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 some@from.address

You can do this in your Apache configuration like so:

php_admin_value sendmail_path "/usr/bin/env catchmail -f some@from.address"

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 --smtp-port 10025, add the same parameters to your catchmail command:

sendmail_path = /usr/bin/env catchmail --smtp-ip --smtp-port 10025 -f some@from.address


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

    EMAIL_HOST = ''
    EMAIL_PORT = 1025
    EMAIL_USE_TLS = False


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/:cid for individual attachments by CID, or the whole message with /messages/:id.source.


  • Mail processing is fairly basic but easily modified. If something doesn't work for you, fork and fix it or file an issue and let me know. Include the whole message you're having problems with.
  • The interface is very basic and has not been tested on many browsers yet.


  • Add mail delivery on request, optionally multiple times.
  • Compatibility testing against CampaignMonitor's design guidelines and CSS support matrix.
  • Forward mail to rendering service, maybe CampaignMonitor?


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 also to The Frontier Group for giving me the idea, being great guinea pigs and letting me steal pieces of time to keep the project alive.


I work on MailCatcher mostly in my own spare time. If you've found Mailcatcher useful and would like to help feed me and fund continued development and new features, please donate via PayPal. If you'd like a specific feature added to MailCatcher and are willing to pay for it, please email me.


Copyright © 2010-2011 Samuel Cochran (sj26@sj26.com). Released under the MIT License, see LICENSE for details.


For dream catching, try this. OR THIS, OMG.