gmailctl

You can create sophisticated Gmail filters by nesting logical operators like and, or, and not within your Jsonnet configuration. This allows you to combine multiple criteria (such as from, to, subject, or has) into a single rule. Note that while Jsonnet provides structure, the underlying logic ultimately maps to Gmail search expressions.

local me = 'pippo@gmail.com';
local spam = {
  or: [
    { from: 'foo@gmail.com' },
    { from: 'bar@hotmail.com' },
    { subject: 'buy this' },
    { subject: 'buy that' },
  ],
};
{
  version: 'v1alpha3',
  rules: [
    {
      filter: {
        and: [
          { to: me },
          { from: 'friend@mail.com' },
          { not: spam },
        ],
      },
      actions: { delete: true },
    },
  ],
}

In the v1alpha2 YAML format, you can define reusable filters in a top-level filters section and reference them in rules using the name key. This prevents repetition.

Note: Filters can only reference filters defined previously in the file to avoid cyclic dependencies. In Jsonnet, this functionality is unnecessary as you can use native variables.

Example (YAML):

version: v1alpha2
filters:
  - name: toMe
    query:
      or:
        - to: myself@gmail.com
        - to: myself@yahoo.com

rules:
  - filter:
      name: toMe
    actions:
      labels:
        - directed

Since a filter can only contain one expression, use logic operators to combine multiple conditions within a rule:

• and: True only if all sub-expressions are true.
• or: True if one or more sub-expressions are true.
• not: True if the sub-expression is false.

Example (YAML):

rules:
  - filter:
      or:
        - from: foo
        - and:
            - list: bar
            - not:
                to: baz
    actions:
      markImportant: true

Configuration files and credentials are stored in one of the following locations:

1. <XDG_BASE_DIR>/gmailctl (typically ~/.config/gmailctl on Linux).
2. ~/.gmailctl (legacy location, maintained for backward compatibility).
3. A custom location specified via the --config argument.

You can manage multiple Gmail accounts by specifying different configuration files using the --config flag. A common pattern is to set up bash aliases for each account:

alias gmailctlu1='gmailctl --config=$HOME/.gmailctlu1'
alias gmailctlu2='gmailctl --config=$HOME/.gmailctlu2'

To keep your configuration modular and reusable, you can define common filter components in separate .libjsonnet files and import them into your main config.jsonnet.

// spam.libjsonnet
{
  or: [
    { from: 'foo@gmail.com' },
    { from: 'bar@hotmail.com' },
    { subject: 'buy this' },
    { subject: 'buy that' },
  ],
}

// config.jsonnet
local spam_filter = import 'spam.libjsonnet';
{
  version: 'v1alpha3',
  rules: [
    {
      filter: spam_filter,
      actions: { delete: true },
    },
  ],
}

Since gmailctl uses your system editor to modify configuration files, you should set the EDITOR environment variable.

Linux (using xdg-mime for snap users)

If using the snap version, configure your preferred editor (e.g., vim):

xdg-mime default vim.desktop text/x-csrc

Windows

Set the EDITOR variable using cmd or powershell:

Command Prompt:

set "EDITOR=code --wait"

PowerShell:

setx EDITOR "code --wait"

After installation, run the init command to guide you through setting up the Gmail APIs and updating your settings via the command line.

gmailctl init

You can install gmailctl using several methods depending on your platform:

From Source (Go)

If you have Go installed, use go install:

go install github.com/mbrt/gmailctl/cmd/gmailctl@latest

macOS

Using Homebrew:

brew install gmailctl

Using Macports:

sudo port install gmailctl

Linux

On Fedora:

sudo dnf install gmailctl

Using Snap:

sudo snap install gmailctl

Windows

Download pre-built binaries from the GitHub releases page.