Gmail filters as a code

Published in

The Startup

5 min readJun 16, 2020

Using gmailctl to create filters and label your emails

Recently, I was reading the great article, The Art of Automation from Jessie Frazelle, and amazed me how she automates her day to day tasks.

As developers, automation is not a new concept, we tend to deal with the patterns of automation day to day through continuous integration (CI) and continuous delivery (CD). For the rest of the world, it is interesting to see the patterns of automation are starting to play a role in consumer products. — Jessie Frazelle

After reading that, I decided to automate my Gmail filters using some tools, like the one she described in her article.

Tools

I wouldn’t like to write something from scratch for this job, so I tried to find something to help me, and I came across with the following tools:

Gmailfilters (Jessie described in her blog)
gmail-britta
gmailctl

My Choice — gmailctl

After taking a look at some tools, I decided to go ahead with gmailctl, mainly because of the declarative style of config (using Jsonnet), and the author works for google 😃.

Installation

You can check the gmailctl GitHub to see the installation methods, but as I use macOS, I will install using brew:

brew install gmailctl

After that, you can start to config your the tool with:

gmailctl init

if it is your first time you will get the following message:

opening credentials: open /Users/yourhome/.gmailctl/credentials.json: no such file or directoryThe credentials are not initialized.To do so, head to https://console.developers.google.com1. Create a new project if you don't have one
1. Go to 'Enable API and services' and select Gmail
2. Go to credentials and create a new one, by selecting 'Help me choose'
   2a. Select the Gmail API
   2b. Select 'Other UI'
   2c. Access 'User data'.
3. Go to 'OAuth consent screen'
   3a. If your account is managed by an organization, you have to
       select 'Internal' as 'User Type' and Create (otherwise ignore)
   3b. Set an application name (e.g. 'gmailctl')
   3c. Update 'Scopes for Google API', by adding:
       * https://www.googleapis.com/auth/gmail.labels
       * https://www.googleapis.com/auth/gmail.metadata
       * https://www.googleapis.com/auth/gmail.settings.basic
5. IMPORTANT: you don't need to submit your changes for verification, as
   you're not creating a public App.
6. Save and go back to Credentials
   6a. Click 'Create credentials'
   6b. Select 'OAuth client ID'
   6c. Select 'Other' as 'Application type' and give it a name.
   6d. Create.
7. Download the credentials file into '/Users/yourhome/.gmailctl/credentials.json' and execute the 'init'
   command again.Documentation about Gmail API authorization can be found
at: https://developers.google.com/gmail/api/auth/about-auth

Just follow the steps as described by the author, and you will be fine.

First Steps

After the configuration, you can start editing your filters with the following command:

gmailctl edit

note that it will open the editor configured in the environment variable $EDITOR

Here are the default config.jsonnet:

config.jsonnet

In my case, I downloaded my configs from Gmail first:

# download the filters to the default configuration file
gmailctl download > ~/.gmailctl/config.jsonnet
# check that the diff is empty and no errors are present
gmailctl diff
# happy editing!
gmailctl edit

Commands

You can check all the commands available, just typing gmailctl and pressing enter in your terminal.

I have already talked about the commands: edit, download, and init, but I also would like to mention the commands apply and diff.

“gmailctl apply”: Simple applies your changes and apply to your Gmail account, but before that, it runs tests that we will be talking later.

“gmailctl diff”: This guy diffs your local changes against your Gmail, let’s say I want to add a new label to my Gmail, I can add that to my configuration like below:

and after that, I can diff:

That’s great to see what changes will be applied to your Gmail.

Tests

Yeah, you read it right, you can do your own set of tests with gmailctl, and it runs the tests before you apply the changes live to your account.

You could even upload your config to GitHub and have circle-ci running the tests to see if something breaks. 😎

How does it work?

Below we have the two files that compose a bigger config.jsonnet file. The first one is my filters and the actions to be applied. The last part is my test cases.

messages: […] is an array of mock emails that my rules will be applied and actions: {} is an object that should match the actions that are described on my filters section.

Let’s remove ‘GitHub/Mentions’ from my expected results and see what happens:

$ gmailctl test
Error: config tests failed: test "Should apply github mentions filter": message #0 is going to get unexpected actions: {"labels":["GitHub","GitHub/Mentions"]}Note:
  - Message: {
      "from": "notifications@github.com",
      "to": [
        "author@noreply.github.com"
      ],
      "subject": "GitHub",
      "body": "@hjemmel"
    }
  - Actions:
    --- want
    +++ got
    @@ -1,6 +1,5 @@
     {
       "labels": [
    -    "GitHub",
    -    "GitHub/Mentions"
    +    "GitHub"
       ]
     }

Reading the message, we can see that the message was tagged with two filters, “GitHub” and “GitHub/Mentions” but we only were expecting one “GitHub”

Gmailctl helped me to reduce the volume of email that I was receiving and also to analyze which emails were essential or not.