Skip to main content

Python asyncio IMAP4rev1 client library

Project description


Build status

This library is inspired by imaplib and imaplib2 from Piers Lauder, Nicolas Sebrecht, Sebastian Spaeth. Some utilities functions are taken from imaplib/imaplib2 thanks to them.

The aim is to port the imaplib with asyncio, to benefit from the sleep or treat model.

It runs with python 3.4 and 3.5.


import asyncio
from aioimaplib import aioimaplib

def check_mailbox(host, user, password):
    imap_client = aioimaplib.IMAP4_SSL(host=host)
    yield from imap_client.wait_hello_from_server()

    yield from imap_client.login(user, password)

    res, data = yield from
    print('there is %s messages INBOX' % data[0])

    yield from imap_client.logout()

if __name__ == '__main__':
    loop = asyncio.get_event_loop()
    loop.run_until_complete(check_mailbox('my.imap.server', 'user', 'pass'))

Beware that the IMAP4.close() function is an IMAP function that is closing the selected mailbox, thus passing from SELECTED state to AUTH state. It does not close the TCP connection. The way to close TCP connection properly is to logout.

IDLE command

The RFC2177 is implemented, to be able to wait for new mail messages without using CPU. The responses are pushed in an async queue, and it is possible to read them in real time. To leave the IDLE mode, it is necessary to send a “DONE” command to the server.

def wait_for_new_message(host, user, password):
    imap_client = aioimaplib.IMAP4_SSL(host=host)
    yield from imap_client.wait_hello_from_server()

    yield from imap_client.login(user, password)
    yield from

    while True:
        msg = yield from imap_client.wait_server_push()
        print('--> received from server: %s' % msg)
        if 'EXISTS' in msg:

    yield from imap_client.logout()

if __name__ == '__main__':
        loop = asyncio.get_event_loop()
        loop.run_until_complete(wait_for_new_message('my.imap.server', 'user', 'pass'))


The IMAP4ClientProtocol class is not thread safe, it uses asyncio.Event and asyncio.Condition that are not thread safe, and state change for pending commands is not locked.

It is possible to use threads but each IMAP4ClientProtocol instance should run in the same thread :


Each color rectangle is an IMAP4ClientProtocol instance piece of code executed by the thread asyncio loop until it reaches a yield, waiting on I/O.

For example, it is possible to launch 4 mono-threaded mail-fetcher processes on a 4 cores server with supervisor, and use a distribution function like len(email) % (process_num) or whatever to share equally a mail account list between the 4 processes.

IMAP command concurrency

IMAP protocol allows to run some commands in parallel. Four rules are implemented to ensure responses consistency:

  1. if a sync command is running, the following requests (sync or async) must wait
  2. if an async command is running, same async commands (or with the same untagged response type) must wait
  3. async commands can be executed in parallel
  4. sync command must wait pending async commands to finish


As said in the logging howto the logger is defined with

logger = logging.getLogger(__name__)

Where name is ‘aioimaplib.aioimaplib’. You can set the logger parameters, either by python API

aioimaplib_logger = logging.getLogger('aioimaplib.aioimaplib')
sh = logging.StreamHandler()
sh.setFormatter(logging.Formatter("%(asctime)s %(levelname)s [%(module)s:%(lineno)d] %(message)s"))

Or loading config file (for example with logging.config.dictConfig(yaml.load(file))) with this piece of yaml file:

    level: DEBUG
    handlers: [syslog]
    propagate: no

Tested with

  • dovecot 2.2.13 on debian Jessie
  • gmail with imap and SSL


Developers are welcome ! If you want to improve it, fix bugs, test it with other IMAP servers, give feedback, thank you for it.

To develop, just run:

virtualenv --python=python3.4 venv
source venv/bin/activate
python develop
pip install -r dev-requirements.txt

To add a imaplib or imaplib2 command you can :

  • add the function to the testing imapserver with a new imaplib or imaplib2 server test, i.e. or respectively;
  • then add the function to the aioimaplib doing almost the same test than above but the async way in

Not unit tested

  • SSL


  • 23/25 IMAP4rev1 commands are implemented from the main rfc3501. ‘STARTTLS’ and ‘AUTHENTICATE’ are still missing.
  • ‘COMPRESS’ from rfc4978
  • ‘GETQUOTA’: ‘GETQUOTAROOT’: ‘SETQUOTA’ from quota rfc2087
  • ‘SORT’ and ‘THREAD’ from the rfc5256
  • ‘ID’ from the rfc2971
  • ‘NAMESPACE’ from rfc2342
  • ‘CATENATE’ from rfc4469
  • tests with other servers

If it goes wrong

Sometimes you break things and you don’t understand what’s going on (I always do). For this library I have two related tools:

  • ngrep on the imap test port : sudo ngrep -d lo port 12345
  • activate debug logs changing INFO to DEBUG at the top of the mock server and the aioimaplib




  • tests : added better encoding handling and message building in Mail.create


  • tests : added message_id as Mail.create parameter for testing


  • tests : extract Mail.create_binary for convenience


  • fix : trailing whitespace bug causing “BAD Could not parse command” using gmail/IDLE
  • fix : stop adding a space for the prefix ‘UID ‘ -> ‘UID’


  • fix : issue #12 Not properly buffering newlines for incomplete lines
  • fix : imapserver with status of an inexistant mailbox
  • fix : remove offset problem with strip() modifying length of read data
  • fix : remove ‘unknown data received’ logs if line is empty


  • remove hard coded logging config
  • doc : added logging settings


  • added rfc5032 ‘within’ function to server and tests for aiolib (it is only YOUNGER/OLDER arguments)


  • pushing continuation in the queue when idled


  • added a stop waiting server push function to interupt yield from queue.get


  • server send still here every IDLE_STILL_HERE_PERIOD_SECONDS to client when idle
  • fix when server was lauched with main, loop is already running


  • fix doc
  • fix imapserver main (needs a asyncio.loop.run_forever())


  • fix issues with coroutines in uid command
  • documentation


  • refactor: treating response as we read the imap server responses for a better reading
  • doc
  • removing tests from package
  • publish on pypi
  • added coverall


  • fix aioimaplib bug when receiving chunked fetch data
  • do not abort when receiving unsollicited data from server


  • build CI environment
  • license GPL v3.0


  • added APPEND command
  • fix usernames can have ‘@’ for mockimapserver
  • server can handle SEARCH with CHARSET opt parameter (but ignores it)


  • added 11 new imap commands
  • added imap command synchronizing
  • refactor
  • documentation


  • init project with mockimapserver
  • project files
  • 11 imap commands

Project details

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
aioimaplib-0.5.17-py3-none-any.whl (345.0 kB) Copy SHA256 hash SHA256 Wheel 3.5
aioimaplib-0.5.17.tar.gz (50.0 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