Last Updated: September 29, 2020
· jdubeau123

Python's imaplib

Some useful examples of using python's imaplib to check your inbox. This has only been tested with a gmail inbox so far.

Some Especially Useful Reading About IMAP


Setting a reasonable time interval

You probably don't want to start crawling your inbox all the way back to the very first emails you ever received, so the datetime module will come in handy. Specifically, I like to use:

date = ( - datetime.timedelta(1)).strftime("%d-%b-%Y")

to get a correctly formatted date representing yesterday. Just change the argument to the timedelta function if you want to check further back.

The relevant syntax for using this will be something along the lines of:

'(SENTSINCE {0})'.format(date)

this will go inside of an IMAP search command as part of your filters

Specifying A Specific Sender to Look For

If you're looking for mail from someone in particular you can use:

'(FROM {0})'.format(eml.strip())

It would be dangerous to omit the strip call in general.

Searching For Only Unseen Emails

To search for only unseen emails, the relevant python/IMAP syntax is:


A Full Example

CONN = imaplib.IMAP4_SSL("")
login("your email", "your password", CONN)
date = ( - datetime.timedelta(1)).strftime("%d-%b-%Y")
(_, data) =, ('UNSEEN'), '(SENTSINCE {0})'.format(date)), '(FROM {0})'.format("".strip()))
ids = data[0].split()

This will retrieve all UNSEEN emails sent within the last day from "", in the form of message id's, which you can then use to further process the individual emails.

The login function should look something like:

conn.login(user, password)
readonly = True"INBOX", readonly)

The readonly part is actually very important if you don't want the script to move the emails that it finds into your "read" section. With the readonly bit set to true, your inbox will not be modified in any way.

1 Response
Add your response

How does the unseen feature work? I would assume it is a single bit shared across email clients.

In my case I have an api that needs to parse all the emails in an inbox. If we restart the api it should parse all the emails in the inbox. But if we are within a task (that runs every few minutes) we should only read in the emails since x date. Any tips on how to structure thsi?

10 months ago ·