gmail cleaner
v1.0.4
Quickly peek, and permanently delete emails in Gmail that match specific label and search query.
This was created to delete over 120k messages that GMail web interface and IMAP weren't able to handle (they just timed out). In addition, I also needed a project to test a bunch of CI tools.
Download the zipped-binary for your OS from the release page and extract it.
Alternatively, if you have node installed, then just clone this repository using git, then do npm install. After that you can follow the examples below, replacing all reference to gmail_cleaner-linux with node gmail_cleaner.js.
Delete up to 15k emails in Categories/Updateslabel:
$ ./gmail_cleaner-linux delete -l "CATEGORY_UPDATES" -n 15000
Found 10381 matching emails in CATEGORY_UPDATES. Deleting them ...
1000 messages deleted.
1000 messages deleted.
1000 messages deleted.
1000 messages deleted.
1000 messages deleted.
1000 messages deleted.
1000 messages deleted.
1000 messages deleted.
1000 messages deleted.
1000 messages deleted.
381 messages deleted.Verify the result using emails command:
$ ./gmail_cleaner-linux emails -l "CATEGORY_UPDATES"
No emails found.Using Gmail query to target specific emails, and reviewing samples before deleting them:
$ ./gmail_cleaner-linux delete -s -l "Corp" -q "subject:Birthday" --dry-run
Found 47 matching emails in Corp. Deleting them ...
dry-run is active, skip deleting emails.
$ ./gmail_cleaner-linux emails -s -l "Corp" -q "subject:Birthday" -n 3 --no-snippet
retrieving headers for 3 emails ..
Matching email messages:
Date From Subject
Thu, 7 Nov 2019 22:00:14 +0000 Corp App <[email protected]> [Employee] Happy Birthday To Foo
Wed, 6 Nov 2019 22:06:52 +0000 Corp App <[email protected]> [Employee] Happy Birthday To Bar
Tue, 5 Nov 2019 22:00:13 +0000 Corp App <[email protected]> [Employee] Happy Birthday To 42
$ ./gmail_cleaner-linux delete -l "Corp" -q "subject:Birthday"
Found 47 matching emails in Corp. Deleting them ...
47 messages deleted.
$ ./gmail_cleaner-linux emails -s -l "Corp" -q "subject:Birthday"
no emails found.Use --help or -h to see usage information.
$ ./gmail_cleaner-linux -h
Usage: gmail_cleaner-linux <command> [options]
Commands:
gmail_cleaner-linux labels List all available Gmail labels
gmail_cleaner-linux emails List emails matching specific label and query
gmail_cleaner-linux delete Delete emails matching specific label and query
Options:
--version Show version number [boolean]
--sec-warning-off, -s Don't display security warning [boolean]
--verbose, -v Show more verbose information [boolean]
--help, -h Show help [boolean]
Examples:
gmail_cleaner-linux delete -l "SPAM" Delete all emails labeled "SPAM"
gmail_cleaner-linux delete -l "INBOX" -q Delete emails in "INBOX" that has
"subject:spam" --unsafe 'spam' in subjectYou can also see more info on a specific command like so:
$ ./gmail_cleaner-linux delete -h
$ ./gmail_cleaner-linux emails -hAs part of the authentication process, this program by default will temporarily open port 31338/tcp on localhost. You can use other port by specifying environment variable GMAIL_CLEANER_PORT, for example:
$ GMAIL_CLEANER_PORT=1337 ./gmail_cleaner.js labelsThis program uses Gmail API so you must authorise it first before it can access your Gmail account.
On the first time access to Gmail, this program will fail to locate gmail_token.json file, and will fall back to display an authorisation URL. Open it in a browser, and follow the steps to authorise the program to access your account.
After that first run, you should handle gmail_token.json file with care: anyone who has access to it will also have access to your Gmail account. Unless it is turned off with the -s switch, Gmail Cleaner will display the following security warning on every run.
** SECURITY WARNING **
Do the following when you no longer need to use this program in the near future.
- Remove the app access to your account from https://myaccount.google.com/u/2/permissions
- Remove gmail_token.json file. Anyone who has access to it will have full control over your Gmail account.
Note that removing the app access from https://myaccount.google.com/u/2/permissions merely invalidates gmail_token.json so it can no longer be used to access your Gmail account. Gmail Cleaner "app" doesn't really have or need a server/cloud-side component that stores content of gmail_token.json or any information at all about your account. If that's not good enough, then you can always create your own "app" using the following instruction.
https://mail.google.com/ to the list of scopes to authorise (that scope is needed by batchDelete API used by gmail_cleaner)../lib/client_id.json file.gmail_token.json file.After that, the next time you run the program, it will prompt to authorise your own app instead of the default one.
