Skip to main content

SMTP Server with API for email testing inspired by mailtrap and maildump

Project description


SMTP Server with API for email testing inspired by mailtrap and maildump

Can store messages in MongoDB or any SQLAlchemy supported DB (e.g., sqlite). Supports Python 2.7, 3.4, 3.5, pypy.

Contains simple UI interface (AngularJS) to navigate and manage received messages.


$ virtualenv venv  # or mkvirutalenv lathermail
$ . venv/bin/activate
$ pip install lathermail
$ lathermail --help

usage: lathermail [-h] [--db-uri DB_URI] [--api-host API_HOST]
                  [--api-port API_PORT] [--smtp-host SMTP_HOST]
                  [--smtp-port SMTP_PORT]

optional arguments:
  -h, --help            show this help message and exit
  --db-uri DB_URI       DB URI, e.g. mongodb://localhost/lathermail,
                        sqlite:////tmp/my.db (default:
  --api-host API_HOST   API Host (default:
  --api-port API_PORT   API port (default: 5000)
  --smtp-host SMTP_HOST
                        SMTP host (default:
  --smtp-port SMTP_PORT
                        SMTP port (default: 2525)

It will start SMTP server and API server in single process. Also UI interface is available at API port ( by default)

Inboxes are identified by SMTP user/password pairs. lathermail intended to be used in single project environment.

To send email, just use SMTP client with auth support.


To request API, you must provide headers:

  • X-Mail-Password - same as SMTP password
  • X-Mail-Inbox - same as SMTP user. Optional, work with all inboxes if not specified

GET /api/0/inboxes/

Returns list of inboxes for passed X-Mail-Password:

    "inbox_list": [
    "inbox_count": 3

GET /api/0/messages/<message_id>

Returns single message. Example:

    "message_info": {
        "message_raw": "Content-Type: multipart/mixed; boundary=\"===============3928630509694630745==...",
        "password": "password",
        "sender": {
            "name": "Me",
            "address": ""
        "recipients": [
                "name": "Rcpt1",
                "address": ""
                "name": "Rcpt2",
                "address": ""
                "name": "",
                "address": ""
        "recipients_raw": "=?utf-8?q?Rcpt1?= <>,\n =?utf-8?q?Rcpt2?= <>,",
        "created_at": "2014-06-24T15:28:35.045000+00:00",
        "sender_raw": "Me <>",
        "parts": [
                "index": 0,
                "body": "you you \u043f\u0440\u0438\u0432\u0435\u0442 2",
                "is_attachment": false,
                "charset": "utf-8",
                "filename": null,
                "type": "text/plain",
                "size": 16
                "index": 1,
                "body": null,
                "is_attachment": true,
                "charset": null,
                "filename": "t\u0430\u0441\u0434est.txt",
                "type": "application/octet-stream",
                "size": 12
        "inbox": "inbox",
        "_id": "53a960e3312f9156b7c92c5b",
        "subject": "Test subject \u0445\u044d\u043b\u043b\u043e\u0443 2",
        "read": false

Attachments in message have body = null. To download file, use following method.

GET /api/0/messages/<message_id>/attachments/<attachment_index>

Returns file from message. Works in browsers.

GET /api/0/messages/

Returns messages according to optional filters:

  • - Name of sender
  • sender.address - Email of sender
  • - Name of any of recipients
  • recipients.address - Email of any of recipients
  • subject - Message subject
  • Add _contains suffix to any field above to search substring match, e.g.: subject_contains, recipients.address_contains
  • created_at_lt - Filter messages created before this ISO formatted datetime
  • created_at_gt - Filter messages created after this ISO formatted datetime
  • read - Return only read emails when True or unread when False. All emails returned by default


    "message_count": 3,
    "message_list": [
        {"_id": ..., "parts": [...], ...},  // same as single message

DELETE /api/0/messages/<message_id>

Deletes single message

DELETE /api/0/messages/

Deletes all messages in inbox. Also, you can filter deletable messages like in GET /api/0/


Copy lathermail.conf.example, modify it, export environment variable before starting:

$ export LATHERMAIL_SETTINGS=/path/to/lathermail.conf
$ lathermail

To run tests:

$ python -m tests


0.4.1 (2017-02-06)

  • [UI] Add button to delete single or all messages

0.4.0 (2017-02-06)

  • Add _contains filters
  • Fix error with simple text format emails

0.3.1 (2016-09-02)

  • Proper fix for message_from_string on Python 2

0.3.0 (2016-09-01)

  • HTML multipart support (#2, #3)
  • Fix multipart binary messages

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
lathermail-0.4.1-py2.py3-none-any.whl (27.3 kB) Copy SHA256 hash SHA256 Wheel 2.7
lathermail-0.4.1.tar.gz (21.8 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page