Skip to main content

Test SMTP/IMAP server for local integration testing

Project description


For local people.

Localmail is an SMTP and IMAP server that stores all messages into a single in-memory mailbox. It is designed to be used to speed up running test suites on systems that send email, such as new account sign up emails with confirmation codes. It can also be used to test SMTP/IMAP client code.


  • Fast and robust IMAP/SMTP implementations, including multipart messages and unicode support.

  • Includes simple HTTP interface for reading messages, which is useful for checking html emails.

  • Compatible with python’s stdlib client, plus clients like mutt and thunderbird.

  • Authentication is supported but completely ignored, all message go in single mailbox.

  • Messages not persisted by default, and will be lost on shutdown. Optionally, you can log messages to disk in mbox format.

Missing features/TODO:

  • SSL support

WARNING: not a real SMTP/IMAP server - not for production usage.

Running localmail

twistd localmail

This will run localmail in the background, SMTP on port 2025 and IMAP on 2143, It will log to a file ./twistd.log. Use the -n option if you want to run in the foreground, like so.

twistd -n localmail

You can pass in arguments to control parameters.

twistd localmail --imap <port> --smtp <port> --http <port> --file localmail.mbox

You can have localmail use random ports if you like. The port numbers will be logged. TODO: enable writing random port numbers to a file.

twisted -n localmail --random


If you want to embed localmail in another non-twisted program, such as test runner, do the following.

import threading
import localmail

thread = threading.Thread(,
   args=(2025, 2143, 8880, 'localmail.mbox')



This will run the twisted reactor in a separate thread, and shut it down on exit.

If you want to use random ports, you can pass a callback that will have the ports the service is listening on.

import threading
import localmail

def report(smtp, imap, http):
    """do stuff with ports"""

thread = threading.Thread(,
   args=(0, 0, 0, None, report)


0.4 (2015-08-14)

  • support for using random port numbers

  • available as a universal wheel, general packaging improvements

  • Simple HTTP interface for browsing mail (requires jinja2)

  • Support writing to mbox file

  • Fixed date to work with mutt, example muttrc included in package.

0.3 (2013-05-24)

  • Multipart message support [via Ed Jannoo]

  • IMAP UID support

  • Support python 2.6, 2.7 and pypy, tested via tox

0.2 (2012-11-13)

  • Initial public release

  • Basic SMTP/IMAP server


“localmail” is written and maintained by Simon Davy


The following people contributed directly or indirectly to this project:

  • Ed Jannoo <>

Download files

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

Source Distribution

localmail-0.5.0.tar.gz (25.9 kB view hashes)

Uploaded source

Built Distribution

localmail-0.5.0-py2.py3-none-any.whl (13.7 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page