search criteria of IMAP protocol search command

Question

I read from here:

http://docs.python.org/2/library/imaplib.html
IMAP4.search(charset, criterion[, ...])

that imaplib has the search method for me to search mails from my mail boxes.

But I don't understand what criterion are available, or is it that I can enter anything for it?

I searched that page,, but didn't get a clue.

Solution 1

I'm not sure how Python expects the criteria but I'm assuming it's the same as plain IMAP. Refer to the SEARCH command documentation (as larsks already suggested) and use a combination of keywords depending on what you want to retrieve. Examples of criteria:

SUBJECT Christmas

...retrieves messages containing "Christmas" in the subject line.

SUBJECT "New York"

...retrieves messages containing "New York" (without quotes) in the subject line.

OR TO boss SUBJECT resignation

...is to be read as (TO boss) OR (SUBJECT resignation) and will retrieve messages that either have "boss" in the "To" field or contain "resignation" in the subject line.

As you can see above, IMAP Search uses a prefix notation in its criteria that may at first be confusing. You can reason about them using brackets or else by graphically drawing a tree of criteria - especially useful when you get nested ANDs or ORs.

There is a fair amount of different criteria you can use. Refer to the RFC for the whole list.

It may be helpful to interact with IMAP manually (e.g. using telnet) to get used to the structure of SEARCH requests before you spend time coding it.

Solution 2

You may use imap_tools package: https://pypi.org/project/imap-tools/

Implemented the search logic described in rfc3501.

from imap_tools import Q, AND, OR, NOT
# base
mailbox.fetch('TEXT "hello"')  # str
mailbox.fetch(b'TEXT "\xd1\x8f"')  # bytes
mailbox.fetch(Q(subject='weather'))  # query, the str-like object
# AND
Q(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:
# 'TO "[email protected]" (OR FROM "[email protected]" TEXT "\\"the text\\"") (NOT (OR UNANSWERED NEW))')
Q(OR(from_='[email protected]', text='"the text"'), NOT(OR(Q(answered=False), Q(new=True))), to='[email protected]')
# encoding
mailbox.fetch(Q(subject='привет'), charset='utf8')  # 'привет' will be encoded by MailBox._criteria_encoder

see docs for more info.