Organize Your Emails in Bulk With Gmail Search Operators + Python Libraries

After 12 years with Gmail as my primary email inbox, I wanted to clear out old “Promotions” emails. This can be done with some clever use of Gmail’s search syntax shown below.

I wanted to preserve my “Starred” emails, but delete old emails to free up space. I was able to delete 58,000 “Promotions” emails! I wrote this post because I feel it might save you a little time figuring it out yourself. I also included brief details on possible Python tools for Gmail and IMAP below if you are considering scripting your contact management.

I didn’t need Python in the end after reading some Gmail search operator examples. For example, adding a hypen before a search in Gmail acts similar to a “bitwise” or unary operator (~) in Python. It excludes or inverses the criteria in a search rather than including it. I was able to use this to exclude my starred emails. You can also add a filter for “has attachment”. I used that to star any emails with attachments, then delete the rest and excluded “starred” emails.

Gmail search syntax to get “Promotions” minus “Starred” emails and filter on a date range:

category:promotions -is:starred after:2019/12/31 before:2021/1/1

Selecting “all” emails in your search

Once, you’ve selected “All” from the checkbox dropdown, click “Select all conversations that match this search”. Now you can apply actions such as “add a star” or “delete” them by clicking the (⋮) vertical ellipses menu:

To Python or not?

I also considered Python tools for interfacing with gmail to accomplish this. There doesn’t seem to be an easy way to group emails by “Category” in the Gmail API or IMAP. IMAP is shorthand for Internet Message Access Protocol.

imaplib is an “IMAP4 protocol client” in the Python standard library. Usually python’s smtplib is the first library that comes up for email. Don’t forget about imaplib! It might be more suitable for searching based on text in your emails or creating labeled segments yourself, then applying actions to them.

Additional Gmail + Python Resources

Gmail search operators

imaplib – python standard library interface to email accounts [Stack Overflow example]

enabling IMAP in your gmail

Gmail API Python Quickstart

Gmail python library – There are also pythonic wrappers to the Gmail API like this one.

imaplib – Python Module of the Week