DOCSEARCHbyAlgolia
Submit Docs

MailCatcher Documentation

repository·main·Indexed 27 days ago

https://github.com/sj26/mailcatcher

An SMTP server designed for development environments that catches all outgoing mail and displays it in a web interface. It allows developers to inspect HTML, plain text, and attachments without sending emails to real recipients. Features include a REST API for programmatic access, WebSocket support for real-time updates, a sendmail-analogue CLI called catchmail, and configuration guides for Rails, PHP, and Django.

Tokens
2.8K
Snippets
5
Records
22
Agent score
91%

What's inside MailCatcher

  1. Configure PHP to use MailCatcher

    main

    For PHP projects, you can use the catchmail command (a sendmail-analogue provided by MailCatcher) by updating your php.ini or Apache configuration.

    If you are using RVM, use the absolute path returned by which catchmail instead of /usr/bin/env catchmail.

  3. Configure Django to use MailCatcher

    main

    In your Django settings.py, add the following configuration when DEBUG is enabled to route emails to MailCatcher.

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

  4. Configure Rails to use MailCatcher

    main

    In a Rails application, add the following configuration to environments/development.rb to route emails through MailCatcher.

    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

  5. Install MailCatcher in a dedicated RVM gemset

    main

    To prevent gem conflicts when using RVM, install MailCatcher into its own gemset and create a wrapper script.

    rvm default@mailcatcher --create do gem install mailcatcher
ln -s "$(rvm default@mailcatcher do rvm wrapper show mailcatcher)" "$rvm_bin_path/"

  6. Install and run MailCatcher

    main
    To use MailCatcher, install it via RubyGems, start the server, and then configure your application to send mail to the local SMTP server. By default, the SMTP server runs on 127.0.0.1:1025 and the web interface is available at http://127.0.0.1:1080/.

  8. MailCatcher command line options

    main

    Use the following flags to configure the SMTP and HTTP servers or manage the MailCatcher process.

    Usage: mailcatcher [options]

        --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

  9. Run MailCatcher programmatically

    main

    You can start MailCatcher within a Ruby application by calling MailCatcher.run!. You can pass an optional hash of options to override the defaults.

    Default Options:

    • :smtp_ip: "127.0.0.1"
    • :smtp_port: 1025
    • :http_ip: "127.0.0.1"
    • :http_port: 1080
    • :http_path: /
    • :messages_limit: nil
    • :verbose: false
    • :daemon: true (unless on Windows)
    • :browse: false
    • :quit: true

  10. Subscribe to real-time message updates via WebSockets

    main

    MailCatcher supports WebSockets for real-time message delivery. By opening a WebSocket connection to the /messages endpoint, you will receive a JSON-encoded message every time a new email is intercepted by the server.

    This is useful for building live dashboards or automated testing tools that need to react immediately to incoming mail.

  11. Access message content and parts

    main

    To inspect the contents of a specific message, use these methods:

    • MailCatcher::Mail.message_source(id): Returns the raw email source string.
    • MailCatcher::Mail.message_parts(id): Returns an array of hashes for all parts (including attachments) containing cid, type, filename, and size.
    • MailCatcher::Mail.message_attachments(id): Returns an array of hashes for only the attachment parts.
    • MailCatcher::Mail.message_part(message_id, part_id): Retrieves a specific part by its internal ID.
    • MailCatcher::Mail.message_part_cid(message_id, cid): Finds a specific part by its Content-ID (cid).

  12. Retrieve specific message formats via API

    main

    Once you have a message ID, you can request different representations of that message using specific file extensions in the URL path:

    EndpointContent TypeDescription
    /messages/:id.jsonapplication/jsonFull message data including formats (source, html, plain) and attachments
    /messages/:id.htmltext/htmlThe HTML body of the message. Embedded cid: attachments are automatically rewritten to link to the /parts/ endpoint.
    /messages/:id.plainVariable (from part)The plain text body of the message.
    /messages/:id.sourcetext/plainThe raw message source.
    /messages/:id.emlmessage/rfc822The raw message source in EML format.
    /messages/:id/parts/:cidVariable (from part)Retrieves a specific MIME part or attachment using its Content-ID (cid).