magetron / imap_tools

Work with email and mailbox by IMAP

imap_tools 📧

Work with email and mailbox by IMAP:

• Parsed email message attributes
• Query builder for searching emails
• Actions with emails: copy, delete, flag, move, seen, append
• Actions with folders: list, set, get, create, exists, rename, delete, status
• No dependencies

Python version	3.3+
License	Apache-2.0
PyPI	https://pypi.python.org/pypi/imap_tools/
IMAP RFC	VERSION 4rev1 - https://tools.ietf.org/html/rfc3501
EMAIL RFC	Internet Message Format - https://tools.ietf.org/html/rfc2822

Contents

• Installation
• Guide
  • Basic
  • Email attributes
  • Search criteria
  • Actions with emails
  • Actions with folders
  • Exceptions
• Release notes
• Contribute
• Reasons
• Thanks
• Donate

Installation

$ pip install imap-tools

Guide

Basic

from imap_tools import MailBox, AND

# get list of email subjects from INBOX folder
with MailBox('imap.mail.com').login('[e-mail]', 'pwd') as mailbox:
    subjects = [msg.subject for msg in mailbox.fetch()]

# get list of email subjects from INBOX folder - equivalent verbose version
mailbox = MailBox('imap.mail.com')
mailbox.login('[e-mail]', 'pwd', initial_folder='INBOX')  # or mailbox.folder.set instead 3d arg
subjects = [msg.subject for msg in mailbox.fetch(AND(all=True))]
mailbox.logout()

MailBox(BaseMailBox), MailBoxUnencrypted(BaseMailBox) - for create mailbox instance.

BaseMailBox.login, MailBox.xoauth2 - authentication functions. TLS connection example.

BaseMailBox.fetch - email message generator, first searches email nums by criteria, then fetch and yields MailMessage:

• criteria = 'ALL', message search criteria, query builder
• charset = 'US-ASCII', indicates charset of the strings that appear in the search criteria. See rfc2978
• limit = None, limit on the number of read emails, useful for actions with a large number of messages, like "move"
• miss_defect = False, miss emails with defects (deprecated)
• miss_no_uid = True, miss emails without uid
• mark_seen = True, mark emails as seen on fetch
• reverse = False, in order from the larger date to the smaller
• headers_only = False, get only email headers (without text, html, attachments)
• bulk = False, False - fetch each message separately per N commands - low memory consumption, slow; True - fetch all messages per 1 command - high memory consumption, fast

BaseMailBox.<action> - copy, move, delete, flag, seen, append

BaseMailBox.folder - folder manager

BaseMailBox.search - search mailbox for matching message numbers (this is not uids)

BaseMailBox.box - imaplib.IMAP4/IMAP4_SSL client instance.

Email attributes

MailMessage and MailAttachment public attributes are cached by functools.lru_cache

for msg in mailbox.fetch():  # generator: imap_tools.MailMessage
    msg.uid          # str or None: '123'
    msg.subject      # str: 'some subject 你 привет'
    msg.from_        # str: 'Bartö[e-mail]'
    msg.to           # tuple: ('[e-mail]', '[e-mail]', )
    msg.cc           # tuple: ('[e-mail]', )
    msg.bcc          # tuple: ('[e-mail]', )
    msg.reply_to     # tuple: ('[e-mail]', )
    msg.date         # datetime.datetime: 1900-1-1 for unparsed, may be naive or with tzinfo
    msg.date_str     # str: original date - 'Tue, 03 Jan 2017 22:26:59 +0500'
    msg.text         # str: 'Hello 你 Привет'
    msg.html         # str: '<b>Hello 你 Привет</b>'
    msg.flags        # tuple: ('SEEN', 'FLAGGED', 'ENCRYPTED')
    msg.headers      # dict: {'received': ('from 1.m.ru', 'from 2.m.ru'), 'anti-virus': ('Clean',)}
    msg.size_rfc822  # int: 20664 bytes - size info from server (*useful with headers_only arg)
    msg.size         # int: 20377 bytes - size of received message

    for att in msg.attachments:  # list: imap_tools.MailAttachment
        att.filename             # str: 'cat.jpg'
        att.payload              # bytes: b'\xff\xd8\xff\xe0\'
        att.content_id           # str: '[e-mail]'
        att.content_type         # str: 'image/jpeg'
        att.content_disposition  # str: 'inline'
        att.part                 # email.message.Message: original object
        att.size                 # int: 17361 bytes

    msg.obj              # email.message.Message: original object
    msg.from_values      # dict or None: {'email': '[e-mail]', 'name': 'Ya', 'full': 'Ya <[e-mail]>'}
    msg.to_values        # tuple: ({'email': '', 'name': '', 'full': ''},)
    msg.cc_values        # tuple: ({'email': '', 'name': '', 'full': ''},)
    msg.bcc_values       # tuple: ({'email': '', 'name': '', 'full': ''},)
    msg.reply_to_values  # tuple: ({'email': '', 'name': '', 'full': ''},)

Search criteria

This chapter about "criteria" and "charset" arguments of MailBox.fetch.

You can use 3 approaches to build search criteria:

from imap_tools import AND, OR, NOT

mailbox.fetch(AND(subject='weather'))  # query, the str-like object
mailbox.fetch('TEXT "hello"')          # str
mailbox.fetch(b'TEXT "\xd1\x8f"')      # bytes, *charset arg is ignored

The "charset" is argument used for encode criteria to this encoding. You can pass the criteria as bytes in the desired encoding - in this case, the encoding will be ignored.

mailbox.fetch(A(subject='жёлтый'), charset='utf8')

Query builder implements all search logic described in rfc3501. It uses this classes:

Class	Alias	Usage	Arguments
AND	A	combines keys by logical "AND" condition	Search keys (see table below) | str
OR	O	combines keys by logical "OR" condition	Search keys (see table below) | str
NOT	N	invert the result of a logical expression	AND/OR instances | str
Header	H	for search by headers	name: str, value: str
UidRange	U	for search by UID range	start: str, end: str

See query examples. A few examples:

from imap_tools import A, AND, OR, NOT
# AND
A(text='hello', new=True)  # '(TEXT "hello" NEW)'
# OR
OR(text='hello', date=datetime.date(2000, 3, 15))  # '(OR TEXT "hello" ON 15-Mar-2000)'
# NOT
NOT(text='hello', new=True)  # 'NOT (TEXT "hello" NEW)'
# complex
A(OR(from_='[e-mail]', text='"the text"'), NOT(OR(A(answered=False), A(new=True))), to='[e-mail]')
# python note: you can't do: A(text='two', NOT(subject='one'))
A(NOT(subject='one'), text='two')  # use kwargs after logic classes (args)

Search key table. Key types marked with * can accepts a sequence of values like list, tuple, set or generator.

Key	Types	Results	Description
answered	bool	ANSWERED/UNANSWERED	with/without the Answered flag
seen	bool	SEEN/UNSEEN	with/without the Seen flag
flagged	bool	FLAGGED/UNFLAGGED	with/without the Flagged flag
draft	bool	DRAFT/UNDRAFT	with/without the Draft flag
deleted	bool	DELETED/UNDELETED	with/without the Deleted flag
keyword	str*	KEYWORD KEY	with the specified keyword flag
no_keyword	str*	UNKEYWORD KEY	without the specified keyword flag
from_	str*	FROM "[e-mail]"	contain specified str in envelope struct's FROM field
to	str*	TO "[e-mail]"	contain specified str in envelope struct's TO field
subject	str*	SUBJECT "hello"	contain specified str in envelope struct's SUBJECT field
body	str*	BODY "some_key"	contain specified str in body of the message
text	str*	TEXT "some_key"	contain specified str in header or body of the message
bcc	str*	BCC "[e-mail]"	contain specified str in envelope struct's BCC field
cc	str*	CC "[e-mail]"	contain specified str in envelope struct's CC field
date	datetime.date*	ON 15-Mar-2000	internal date is within specified date
date_gte	datetime.date*	SINCE 15-Mar-2000	internal date is within or later than the specified date
date_lt	datetime.date*	BEFORE 15-Mar-2000	internal date is earlier than the specified date
sent_date	datetime.date*	SENTON 15-Mar-2000	rfc2822 Date: header is within the specified date
sent_date_gte	datetime.date*	SENTSINCE 15-Mar-2000	rfc2822 Date: header is within or later than the specified date
sent_date_lt	datetime.date*	SENTBEFORE 1-Mar-2000	rfc2822 Date: header is earlier than the specified date
size_gt	int >= 0	LARGER 1024	rfc2822 size larger than specified number of octets
size_lt	int >= 0	SMALLER 512	rfc2822 size smaller than specified number of octets
new	True	NEW	have the Recent flag set but not the Seen flag
old	True	OLD	do not have the Recent flag set
recent	True	RECENT	have the Recent flag set
all	True	ALL	all, criteria by default
uid	iter(str)/str/U	UID 1,2,17	corresponding to the specified unique identifier set
header	H(str, str)*	HEADER "A-Spam" "5.8"	have a header that contains the specified str in the text
gmail_label	str*	X-GM-LABELS "label1"	have this gmail label.

Server side search notes:

• For string search keys a message matches if the string is a substring of the field. The matching is case-insensitive.
• When searching by dates - email's time and timezone are disregarding.

Actions with emails

First of all read about uid at rfc3501.

You can use 2 approaches to perform these operations:

• "in bulk" - Perform IMAP operation for message set per 1 command
• "by one" - Perform IMAP operation for each message separately per N commands

MailBox.fetch generator instance passed as the first argument to any action will be implicitly converted to uid list.

For actions with a large number of messages imap command may be too large and will cause exception at server side, use 'limit' argument for fetch in this case.

with MailBox('imap.mail.com').login('[e-mail]', 'pwd', initial_folder='INBOX') as mailbox:

    # COPY all messages from current folder to folder1, *by one
    for msg in mailbox.fetch():
        res = mailbox.copy(msg.uid, 'INBOX/folder1')

    # MOVE all messages from current folder to folder2, *in bulk (implicit creation of uid list)
    mailbox.move(mailbox.fetch(), 'INBOX/folder2')

    # DELETE all messages from current folder, *in bulk (explicit creation of uid list)
    mailbox.delete([msg.uid for msg in mailbox.fetch()])

    # FLAG unseen messages in current folder as Answered and Flagged, *in bulk.
    flags = (imap_tools.MailMessageFlags.ANSWERED, imap_tools.MailMessageFlags.FLAGGED)
    mailbox.flag(mailbox.fetch(AND(seen=False)), flags, True)

    # SEEN: flag as unseen all messages sent at 05.03.2007 in current folder, *in bulk
    mailbox.seen(mailbox.fetch("SENTON 05-Mar-2007"), False)

    # APPEND: add message to mailbox directly, to INBOX folder with SEEN flag and now date
    with open('/tmp/message.eml', 'rb') as f:
        msg = imap_tools.MailMessage.from_bytes(f.read())  # *or use bytes instead MailMessage
    mailbox.append(msg, 'INBOX', dt=None, flag_set=[imap_tools.MailMessageFlags.SEEN])

Actions with folders

with MailBox('imap.mail.com').login('[e-mail]', 'pwd') as mailbox:

    # LIST: get all subfolders of the specified folder (root by default)
    for f in mailbox.folder.list('INBOX'):
        print(f)  # {'name': 'INBOX|cats', 'delim': '|', 'flags': ('\\Unmarked', '\\HasChildren')}

    # SET: select folder for work
    mailbox.folder.set('INBOX')

    # GET: get selected folder
    current_folder = mailbox.folder.get()

    # CREATE: create new folder
    mailbox.folder.create('INBOX|folder1')

    # EXISTS: check is folder exists (shortcut for list)
    is_exists = mailbox.folder.exists('INBOX|folder1')

    # RENAME: set new name to folder
    mailbox.folder.rename('folder3', 'folder4')

    # DELETE: delete folder
    mailbox.folder.delete('folder4')

    # STATUS: get folder status info
    stat = mailbox.folder.status('some_folder')
    print(stat)  # {'MESSAGES': 41, 'RECENT': 0, 'UIDNEXT': 11996, 'UIDVALIDITY': 1, 'UNSEEN': 5}

Exceptions

Custom lib exceptions here: errors.py.

Release notes

History of important changes: release_notes.rst

Contribute

If you found a bug or have a question, please let me know - create merge request or issue.

Reasons

• Excessive low level of imaplib library.
• Other libraries contain various shortcomings or not convenient.
• Open source projects make world better.

Thanks

Big thanks to people who helped develop this library:

shilkazx, somepad, 0xThiebaut, TpyoKnig, parchd-1, dojasoncom, RandomStrangerOnTheInternet, jonnyarnold, Mitrich3000, audemed44, mkalioby, atlas0fd00m, unqx, daitangio, upils, Foosec, frispete, PH89, amarkham09, nixCodeX, backelj, ohayak, mwherman95926, andyfensham, mike-code, aknrdureegaesr, ktulinger, SamGenTLEManKaka, devkral, tnusraddinov, thepeshka, shofstet, the7erm, c0da, dev4max, ascheucher, Borutia, nathan30, daniel55411, rcarmo, bhernacki, ilep, ThKue, repodiac

Donate

💰 You may donate, if this library helped you.