Email inboxes work like a stack. The newest email goes to the top of the inbox and is the first email you see when opening an email client. I find that I get a ton of emails that I either don’t want to see, or don’t need to be at the top of my inbox. Using filters and labels makes email more tolerable. Automating these filters and labels makes them usable. Gmail tries to do this by automating tabs, but I need more control over how emails are grouped and prioritized. An example is Github notifications. I still want them to come to my inbox but I want to triage them on my own schedule and I want to prioritize certain types of notifications over others. I solved this with automation.


  • gmailctl
    • Declarative configuration for Gmail filters. Allows automation of Gmail filters and labels.
  • GCP access
    • Gmailctl uses the gmail api, which requires access to GCP. This may be an issue in some environments where GCP access is restricted, but should generally not be a problem.

Getting Started

Setting up gmailctl isn’t as straightforward as I wish, but once it’s setup then things just work.


You will need to install gmailctl on your system. On my mac I used Homebrew to do this, but the gmailctl README has alternatives.

brew install gmailctl

Initial Setup

This is where things become a little less straightforward, it requires creating a project in GCP and giving that project access to the gmail api. The tool walks you through how to do this by using its init function.

gmailctl init

Once this is done you are ready to start automating your inbox.

Setting Up Rules

To edit your gmailctl configuration you can use its edit command.

gmailctl edit

This will open your default editor and allow you to edit your configuration. The tool comes with a template that you can use as a base for your configuration.

Once you edit the rules file gmailctl will check for any errors in your configuration. If there are any then it will prompt you to fix them. If your configuration is error free then the tool will look for changes in rules, if there are any the tool will show you a diff and then ask if you want to apply these changes to your Gmail account. You can chose to apply these changes now or you can run gmailctl apply at a later point to apply changes. This will look something like this:

Organizing Your Rules

The base template uses a single array to define all of the rules for a template. I recommend defining your rules as separate arrays to group similar rules. You can then concatenate all of your variables into a single array that is used in the template. Another technique I use is task specific email address to segment emails from services. This allows me to create filters for all newsletters. I can use as the email address and then create a label and filter for anything to that email address.

Here is an example of what my template looks like to manage notifications from services I use.

Label Creation

By default gmailctl will not create labels for you. You can either explicitly or implicitly create labels. I prefer implicit label creation as it is highly unlikely for me to have a label that is not tied to a rule. I also do not care about the color of my labels. If you do want to customize colors then you will need to use explicit label creation.

Version Control

Since the rules file is plain text you can use version control to store your rules. This is nice because you can always go back to an old version of your rules if desired. I do this with a private repository in Github. I keep the repo private to prevent accidentally leaking private email addresses.

The tool provides a download command, but I recommend copying the file from the .gmailctl directory instead as the download command will get rid of any structure you added to your file. I have a shell alias setup to automate this for me.

function editEmailRules() {
    gmailctl edit;
    cp $HOME/.gmailctl/config.jsonnet $DOTFILES/gmailctl;

Final Thoughts

I love automating things and I love using plain text files where I can. This gives me the ability to automate how I use email to make it less cumbersome. Even if you chose not to automate your inbox, you can manually manage filters in the Gmail interface. Other tools can also do similar automation such as gmailfilters or gmail-britta. You can also find email services like Hey that tries to do a lot of this automation for you.

It’s common that when you start using a new service you get a ton of new emails. Using filters to control that can be helpful, automating those filters can also help. Whatever you chose I highly suggest taming your Gmail inbox with filters.