search criteria of IMAP protocol search command


I read from here:, 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.

Asked By: Jilin



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.

Answered By: Gigi

You may use imap_tools package:

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 "xd1x8f"')  # bytes
mailbox.fetch(Q(subject='weather'))  # query, the str-like object
Q(text='hello', new=True)  # 'TEXT "hello" NEW'
# OR
OR(text='hello',, 3, 15))  # '(OR TEXT "hello" ON 15-Mar-2000)'
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.

Answered By: Vladimir

You can find the list of available criteria here:

I’m the author of Red Box (IMAP library) and I wrote the options down here as well:

If you wish to use Red Box for the problem, here’s how it works. First configure the email box:

from redbox import EmailBox

# Create email box instance
box = EmailBox(
    username="[email protected]",

# Select an email folder
inbox = box["INBOX"]

Then search for messages:

from redbox.query import SEEN, FROM

# Search and process messages
for msg in & (FROM("[email protected]") | SUBJECT("[email protected]"))):
    # Process the message

You can also pass the raw search query as string if you prefer that. More about querying here and more about manipulating the messages.


Answered By: miksus
Categories: questions Tags: , ,
Answers are sorted by their score. The answer accepted by the question owner as the best is marked with
at the top-right corner.