Automation is a hot topic right now. In my day job as part of my job is to automate as many repetitive tasks as possible. but how many of us do that in our daily, non-work lives? this year, I’m focused on automating work so we can focus on the things that are important.
Server-side mail rules are one of the most efficient ways to pre-sort and filter mail. Unfortunately, Gmail, the world’s most popular email service, does not use any of the standard protocols to allow users to manage its rules. adding, editing, or deleting a single rule can be a time-consuming task in the web interface, depending on how many rules the user has. the options to edit them “out of band” provided by the company are limited to an xml export and import.
I have 109 mail filters, so I know how hard it can be to manage them using the provided methods. At least until I discovered gmailctl, the command line tool for managing gmail filters with a (relatively) simple, standards-based configuration file.
To define rules flexibly, gmailctl uses the jsonnet template language. using gmailctl also allows the user to export existing rules for modification.
To get started, install gmailctl via your system’s package manager or install it from source with go install github.com/mbrt/gmailctl/cmd/gmailctl@latest. follow that with gmailctl init which will guide you through the process of setting up your credentials and the correct permissions in google. If you already have rules in gmail, I recommend running the gmailctl download below to backup your existing rules. these will be saved in the default config file ~/.gmailctl/config.jsonnet. copy that file somewhere safe for future reference, or to restore your previous rules just in case.
If you want to start from scratch, or if you don’t have any rules yet, you need to create a new empty ~/.gmailctl/config.jsonnet file. the most basic structure for this file is:
As you can see, this file format is similar, but not as strict, as json. this file sets up a simple rule to mark any mail from opensource.com as important, leave it unread, and not mark it as spam. It does this by defining the criteria in the filters section and then the rules to apply in the actions section. actions include the following boolean commands: markread, markspam, markimportant, and archive. You can also use actions to specify a category for mail and assign folders, which we’ll get to later in this article.
once the file is saved, the configuration file format can be verified with the gmailctl test. if everything is ok you can use gmailctl diff to see what changes to make and gmailctl apply to upload your new rule to gmail.
As mentioned above, new email messages can be automatically archived by setting labels in the configuration. I want to assign all mails from opensource.com to a specific folder for them and remove them from the inbox (or archive in gmail terms). To do that, I would change the actions section to be:
As you can see in the image above, gmailctl diff now shows only what is going to change. to apply it, I used gmailctl apply -y to skip the confirmation message. if the tag doesn’t exist, an error is raised, since you can’t do a filter for a tag that doesn’t exist yet.
You can also create more complex rules that target specific conditions or multiple emails. for example, the following rule uses a condition and to search for messages from cloudflare other than purchase confirmations.
In the case of a rule that performs the same action on multiple messages, you can use an or structure. I use it to archive all board game related emails in one folder.
For people with multiple gmail accounts who need their own sets of rules, you can specify a single config file for them with the -config command line parameter. for example, my work uses gmail, and I have another set of rules for that. I can create a new gmailctl directory and use it for the working configuration, like so:
To make this easier for me, I have two shell aliases so it’s clear which configuration I’m using.
The only downside to gmailctl is that it won’t apply a new filter to existing messages, so you still have to manually do things for received mail before applying gmailctl. I hope they can fix it in the future. Other than that, gmailctl has allowed me to quickly and almost completely automatically add and update gmail filters, and I can use my favorite email client without constantly going back to the web UI to change or update a filter.