Skip to main content

A quick tool for generating Gmail filters from YAML rules.

Project description


Build Status

A quick tool for generating Gmail filters from YAML rules.

Interested in helping? See for a few guidelines.

Getting Started

By default, the command line script will generate XML to stdout, which you can then upload to Gmail yourself:

$ pip install gmail-yaml-filters
$ gmail-yaml-filters my-filters.yaml > my-filters.xml

Synchronization via Gmail API

If you are the trusting type, you can authorize the script to upload new filters and remove obsolete filters via Gmail's API. Before using any of these commands, you will need to create client_secret.json and store it in the same directory as your YAML file.

# Upload all filters (and create new labels) from the configuration file
$ gmail-yaml-filters --upload my-filters.yaml

# Delete any filters that aren't defined in the configuration file
$ gmail-yaml-filters --prune my-filters.yaml

# Do both of these steps at once.
$ gmail-yaml-filters --sync my-filters.yaml

# See what would happen but don't apply any changes.
$ gmail-yaml-filters --dry-run --sync my-filters.yaml

Sample Configuration

# Simple example
  label: news
  not_important: true

# Boolean conditions
      - alice
      - bob
      - carol
    all: [me, -MyBoss]
  label: conspiracy

# Nested conditions
  label: hiring
      has: 'completed feedback'
      archive: true
      has: 'what is your feedback'
      star: true
      important: true

# Foreach loops
    - list1
    - list2
    - list3
    to: "{item}"
    label: "{item}"

# Foreach loops with complex structures
    - [mailing-list-1a, list1]
    - [mailing-list-1b, list1]
    - [mailing-list-1c, list1]
    - [mailing-list-2a, list2]
    - [mailing-list-2b, list2]
    to: "{item[0]}"
    label: "{item[1]}"
    - {list: list1, domain:}
    - {list: list2, domain:}
    to: "{list}@{domain}"
    label: "{list}"


Supported conditions:

  • has (also match)
  • does_not_have (also missing, no_match)
  • subject
  • list
  • labeled
  • from, to, cc, and bcc
  • category
  • deliveredto
  • filename
  • larger
  • smaller
  • size
  • rfc822msgid
  • is and has work like Gmail's search operators, for example:
    • has: attachment is translated to match: "has:attachment"
    • is: -snoozed is translated to no_match: "is:snoozed"

Supported actions:

  • archive
  • forward
  • important (also mark_as_important)
  • label, including support for Gmail's category tabs:
  • not_important (also never_mark_as_important)
  • not_spam
  • read (also mark_as_read)
  • star
  • trash (also delete)

Any set of rules with ignore: true will be ignored and not written to XML.

Similar Projects

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for gmail-yaml-filters, version 0.9.4
Filename, size File type Python version Upload date Hashes
Filename, size gmail-yaml-filters-0.9.4.tar.gz (14.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page