DEV Community


Posted on

Cleaning up Gmail with Python


Over time, my Gmail account became stuffed with unnecessary e-mails, e-mail such as: pizza order confirmation, meal confirmation, utility bill reminder, utility bill payment confirmation, credit card offers, bank offers, e-commerce offers, OTP mails, really old e-mails and so on.

The frequency of some of these e-mail are monthly (usually), some are weekly(bank mailers, investment mailers, newsletters) and others quarterly.

So me and my spouse wanted to clean up our gmail account (she had WAY more spam). Roughly, we had around 20K e-mails to search and delete manually.

Time to clean-up

Those e-mails were consuming my Google Drive space as well (mailers with long body, attachments, etc).
I started to clean the mails manually and quickly realised this was definitely not the way - there has to be a better, easy way.

Hence started looking if there's any available e-mail API that I can use.

Found out there a handy api guide from Google

So where do I start?


  1. Python 2.6+
  2. apiclient library
  3. googapiclient library
  4. httplilb2 library
  5. oauth2client
  6. Register your free account at Google Cloud
  7. Setup a project (everything in Google Cloud works out of a project)
  8. Go to the APIs & Services option, from the Google Cloud Console
  9. Go to the Credentials tab and hit Create Credentials/OAuth client ID
  10. Once you're setup, download the credentials to your local, from the OAuth ID created in Step 9

Now, let's get the source code:

  1. Get the source code
  2. Get the e-mail filter input. This file contains a list of e-mail addresses, that I wanted to search and delete, you can modify it per your need

And just fire away the source code [python], authenticate via Google and see those nasty e-mails deleted effortlessly.

Here's a screen grab of mail search in action - screen grab of mail search

Another one, of e-mails being deleted - mail delete

Some more things

The code makes use of Google Batch Http Requests, reads the e-mail filter text file, and sends the search, as well the delete requests via http batching.

Google has put a limit of 1000 e-mails to be processed by batch (last I checked it was still 1000), and I think this is for regular accounts.
So the code takes care of that as well - it queries in batch of 1000's.

That's it folks!

I regularly use this program to clean my gmail inbox, my spouse or our friends's inbox as well, and update the e-mail filter, from time to time.

Go on, add your own e-mail filters, run the program and make your inbox free of unwanted e-mails.

If you want to be secure, just delete the token.json (and credentials.json optionally, but you need this file, when you run the source code)file from the directory which has the python source files, post the mail clean-up.

Discussion (2)

rmurari profile image

hey, can you share a python script which can delete all emails in trash folder only ?
thanks in advance

thezooperman profile image
zooperman Author

Hello there, the script now moves all the emails into trash to prevent the risk of permanent delete.
You can choose to clean the trash either manually or extend the script to do that.