# gmail_filter_manager
Gmail filer manager using YAML format.
## Installation
By pip:
```
$ pip install gmail_filter_manager
```
By Homebrew:
```
$ brew install rcmdnk/rcmdnkpac/gmail_filter_manager
```
By script:
```
$ curl -fsSL https://raw.github.com/rcmdnk/gmail_filter_manager/install/install.sh| sh
```
This will install scripts to `/usr/bin`
and you may be asked root password.
If you want to install other directory, do like:
```
$ curl -fsSL https://raw.github.com/rcmdnk/gmail_filter_manager/install/install.sh| prefix=~/usr/local/ sh
```
Or, simply download scripts in bin/ and place where you like.
If you use the script directly, you need to install ruaml.yaml:
```
$ pip install ruamel.yaml
```
## Scripts
### gfm_extract
A script to convert mailFilters.xml, which can be exported from Gmail,
to YAML format.
Default input name is **mailFilters.xml**.
Default ouput name is **mailFilters.yaml**.
They can be changed by arguments:
```
$ gfm_extract [input name [output name]]
```
Once you have YAML file,
you can edit it and use it as an input for `gfm_make`.
### gfm_make
A script to make XML of filters to be imported in Gmail.
Input is YAML format.
Default input name is **mailFilters.yaml**.
Default ouput name is **mailFilters.yaml**.
```yaml
filters:
- from: "foo@example.com"
lable: "foo"
- subject: "[test]"
lable: "test"
shouldMarkAsRead: "true"
namespaces:
apps: http://schemas.google.com/apps/2006
atom: http://www.w3.org/2005/Atom
```
**namespaces** can be omitted.
It is included if you use `gfm_extract`,
but it will be automatically added by `gfm_make` even if is omitted.
## Filter properties
### Filter Criteria Properties
| Name | XML attribute | Description |
| :------------------ | :------------------------ | :---------------------------------------------------------------------------------------------------------- |
| From | name="from" | The email comes from this address. |
| To | name="to" | The email is sent to this address. |
| Subject | name="subject" | The email's title includes this value. |
| Has the words | name="hasTheWord" | The email has this value (search operators). |
| Doesn't have | name="doesNotHaveTheWord" | The email doesn't have this value (search operators). |
| Has attachment | name="hasAttachment" | true or false for if the email has attachments. |
| Don't include chats | name="excludeChats" | true or false for if the email includes chats. |
| Size | name="size" | The email size. If it is specified, the mail size is compared to this value with sizeOperator and sizeUnit. |
| Size operator | name="sizeOperator" | s_sl (greater than) or s_ss (smaller than). |
| Size unit | name="sizeUnit" | Unit of email size: s_sb (B), s_skb (kB) or s_smb (MB). |
**hasTheWord** and **doesNotHaveTheWord** are search operators.
Such a label can be specified here.
Please check following help for more details:
> [Search operators you can use with Gmail - Gmail Help](https://support.google.com/mail/answer/7190)
### Filter Action Properties
| Name | XML attribute | Description |
| :-------------------------- | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| Skip the Inbox (Archive it) | name="shouldArchive" | |
| Mark as read | name="shouldMarkAsRead" | |
| Star it | name="shouldStar" | |
| Apply the label | name="label" | |
| Forward it to | name="forwrdTo" | |
| Delete it | name="shouldTrash" | |
| Never send it to Spam | name="shouldNeverSpam" | |
| Always mark it as important | name="shouldAlwaysMarkAsImportant" | |
| Never mark it as important | name="should | |
| Categorize as | name="smartLabelToApply" | Add smart label. value can be "^smartlabel_personal", "^smartlabel_social", "^smartlabel_promo", "^smartlabel_group" or "^smartlabel_notification". |
Tips:
You can use array for **label** to set several labels on the same criteria.
## How to export/import filters
Check **Export or import filters** in the official help:
> [Create rules to filter your emails - Gmail Help](https://support.google.com/mail/answer/6579)
## Filter Tips
### Numbering labels
Gmail's labels are sorted automatically.
But you may want to put some labels such **Work**, which is always at the bottom,
on the top.
To do it, you can set prefix numbers on labels.
- 01_Work
- 02_Private
- 03_Others
Then, these labels are listed in this order.
### Use labels like folder
Gmail has only **label**, but some other mail clients have **folder**.
- Label: User can set several labels on the same message.
- Folder: A message is included only in one folder.
And all filters are always applied to the new mail.
In this case, if the mail is caught by several filters for labels,
several labels are set.
To avoid several labels to use it as **folder**,
**has:nouserlabels** keyword is useful.
If **hasTheWord** includes this keyword,
only the mail which still does not have the label can be caught.
e.g.)
```
filters:
- hasTheWord: "from:foo@example.com"
label: "00_foo"
- hasTheWord: "has:nouserlabels from:example.com"
label: "01_example"
shouldArchive: "true"
- hasTheWord: "has:nouserlabels"
label: "09_others"
shouldArchive: "true"
```
These filters put a label **foo** for mails from **foo@example.com**,
and put a label **example** for mails from **example.com** domain other than **foo@example.com**.
In addition, if it is not from **foo**, the mail is archived.
And the last filter send other mails to **others** label,
and skip the Inbox.
Such a filter make you free from notification bombs
in the Gmail app of a cell phone.
To use such filters, the order is important.
Note: If you modify filters in the Gmail web interface,
the order is changed: the modified one goes to the bottom.
This is one of the reasons why I wanted these scripts.
### Use DummyInbox to leave only specific mails in the Inbox
You may have more labels with which mails must skip the Inbox.
In this case, **DummyInbox** method label can be used instead of
setting **shouldArchive: "true"** for filters.
The setting is like this:
```
filters:
- hasTheWord: "from:foo@example.com"
label:
- "00_foo"
- "99_DummyInbox"
- hasTheWord: "from:example.com"
label:
- "01_example"
- "99_DummyInbox"
- hasTheWord: "from:example2.com"
label: "02_example2"
- hasTheWord: "from:example3.com"
label: "03_example3"
- hasTheWord: "from:example4.com"
label: "04_example4"
- hasTheWord: "from:example5.com"
label: "05_example5"
- hasTheWord: "has:nouserlabels"
label: "09_others"
- hasTheWord: "-label:99_DummyInbox"
shouldArchive: "true"
```
This setting put additional **99_DummyInbox** label
to which you want to remain in the Inbox.
And the final filter archives mails without **99_DummyInbox** label.
In the above setting, **has:nouserlabels** is not used for **from:example.com**.
Therefore the mail from **foo@example.com** has two labels.
The main difference from
[Use labels like folder](https://github.com/rcmdnk/gmail_filter_manager#use-labels-like-folder) method
is that you can put two different labels between them archive policies are different.
If **shouldArchive** is in the each label, all mails associated to the label are archived.
But this method can remain what you want easily.
In addition, only the order of the filters can be free other than the last label,
so that it makes easy to modify with the web interface.
Although you still need to "modify"
**hasTheWord: "-label:99_DummyInbox"** filter after any other filter changes...
(such adding one space in **Has the words** and save, and remove the space and save again...)
## References
- [gmail_filter_manager: GmailのフィルタをYAMLで簡単に管理する](https://rcmdnk.com/blog/2018/07/07/computer-gmail-python/)
Raw data
{
"_id": null,
"home_page": "https://github.com/rcmdnk/gmail_filter_manager",
"name": "gmail-filter-manager",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<3.12",
"maintainer_email": "",
"keywords": "gmail,yaml,cli",
"author": "rcmdnk",
"author_email": "rcmdnk@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/40/26/aff8d554774eebc09cc96eb2ef9d1588ffadd7f0e01ec155f398d33fc12b/gmail_filter_manager-0.1.1.tar.gz",
"platform": null,
"description": "# gmail_filter_manager\n\nGmail filer manager using YAML format.\n\n## Installation\n\nBy pip:\n\n```\n$ pip install gmail_filter_manager\n```\n\nBy Homebrew:\n\n```\n$ brew install rcmdnk/rcmdnkpac/gmail_filter_manager\n```\n\nBy script:\n\n```\n$ curl -fsSL https://raw.github.com/rcmdnk/gmail_filter_manager/install/install.sh| sh\n```\n\nThis will install scripts to `/usr/bin`\nand you may be asked root password.\n\nIf you want to install other directory, do like:\n\n```\n$ curl -fsSL https://raw.github.com/rcmdnk/gmail_filter_manager/install/install.sh| prefix=~/usr/local/ sh\n```\n\nOr, simply download scripts in bin/ and place where you like.\n\nIf you use the script directly, you need to install ruaml.yaml:\n\n```\n$ pip install ruamel.yaml\n```\n\n## Scripts\n\n### gfm_extract\n\nA script to convert mailFilters.xml, which can be exported from Gmail,\nto YAML format.\n\nDefault input name is **mailFilters.xml**.\nDefault ouput name is **mailFilters.yaml**.\n\nThey can be changed by arguments:\n\n```\n$ gfm_extract [input name [output name]]\n```\n\nOnce you have YAML file,\nyou can edit it and use it as an input for `gfm_make`.\n\n### gfm_make\n\nA script to make XML of filters to be imported in Gmail.\n\nInput is YAML format.\n\nDefault input name is **mailFilters.yaml**.\nDefault ouput name is **mailFilters.yaml**.\n\n```yaml\nfilters:\n- from: \"foo@example.com\"\n lable: \"foo\"\n- subject: \"[test]\"\n lable: \"test\"\n shouldMarkAsRead: \"true\"\nnamespaces:\n apps: http://schemas.google.com/apps/2006\n atom: http://www.w3.org/2005/Atom\n```\n\n**namespaces** can be omitted.\nIt is included if you use `gfm_extract`,\nbut it will be automatically added by `gfm_make` even if is omitted.\n\n## Filter properties\n\n### Filter Criteria Properties\n\n| Name | XML attribute | Description |\n| :------------------ | :------------------------ | :---------------------------------------------------------------------------------------------------------- |\n| From | name=\"from\" | The email comes from this address. |\n| To | name=\"to\" | The email is sent to this address. |\n| Subject | name=\"subject\" | The email's title includes this value. |\n| Has the words | name=\"hasTheWord\" | The email has this value (search operators). |\n| Doesn't have | name=\"doesNotHaveTheWord\" | The email doesn't have this value (search operators). |\n| Has attachment | name=\"hasAttachment\" | true or false for if the email has attachments. |\n| Don't include chats | name=\"excludeChats\" | true or false for if the email includes chats. |\n| Size | name=\"size\" | The email size. If it is specified, the mail size is compared to this value with sizeOperator and sizeUnit. |\n| Size operator | name=\"sizeOperator\" | s_sl (greater than) or s_ss (smaller than). |\n| Size unit | name=\"sizeUnit\" | Unit of email size: s_sb (B), s_skb (kB) or s_smb (MB). |\n\n**hasTheWord** and **doesNotHaveTheWord** are search operators.\nSuch a label can be specified here.\n\nPlease check following help for more details:\n\n> [Search operators you can use with Gmail - Gmail Help](https://support.google.com/mail/answer/7190)\n\n### Filter Action Properties\n\n| Name | XML attribute | Description |\n| :-------------------------- | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Skip the Inbox (Archive it) | name=\"shouldArchive\" | |\n| Mark as read | name=\"shouldMarkAsRead\" | |\n| Star it | name=\"shouldStar\" | |\n| Apply the label | name=\"label\" | |\n| Forward it to | name=\"forwrdTo\" | |\n| Delete it | name=\"shouldTrash\" | |\n| Never send it to Spam | name=\"shouldNeverSpam\" | |\n| Always mark it as important | name=\"shouldAlwaysMarkAsImportant\" | |\n| Never mark it as important | name=\"should | |\n| Categorize as | name=\"smartLabelToApply\" | Add smart label. value can be \"^smartlabel_personal\", \"^smartlabel_social\", \"^smartlabel_promo\", \"^smartlabel_group\" or \"^smartlabel_notification\". |\n\nTips:\n\nYou can use array for **label** to set several labels on the same criteria.\n\n## How to export/import filters\n\nCheck **Export or import filters** in the official help:\n\n> [Create rules to filter your emails - Gmail Help](https://support.google.com/mail/answer/6579)\n\n## Filter Tips\n\n### Numbering labels\n\nGmail's labels are sorted automatically.\n\nBut you may want to put some labels such **Work**, which is always at the bottom,\non the top.\n\nTo do it, you can set prefix numbers on labels.\n\n- 01_Work\n- 02_Private\n- 03_Others\n\nThen, these labels are listed in this order.\n\n### Use labels like folder\n\nGmail has only **label**, but some other mail clients have **folder**.\n\n- Label: User can set several labels on the same message.\n- Folder: A message is included only in one folder.\n\nAnd all filters are always applied to the new mail.\n\nIn this case, if the mail is caught by several filters for labels,\nseveral labels are set.\n\nTo avoid several labels to use it as **folder**,\n**has:nouserlabels** keyword is useful.\n\nIf **hasTheWord** includes this keyword,\nonly the mail which still does not have the label can be caught.\n\ne.g.)\n\n```\nfilters:\n- hasTheWord: \"from:foo@example.com\"\n label: \"00_foo\"\n- hasTheWord: \"has:nouserlabels from:example.com\"\n label: \"01_example\"\n shouldArchive: \"true\"\n- hasTheWord: \"has:nouserlabels\"\n label: \"09_others\"\n shouldArchive: \"true\"\n```\n\nThese filters put a label **foo** for mails from **foo@example.com**,\nand put a label **example** for mails from **example.com** domain other than **foo@example.com**.\nIn addition, if it is not from **foo**, the mail is archived.\n\nAnd the last filter send other mails to **others** label,\nand skip the Inbox.\nSuch a filter make you free from notification bombs\nin the Gmail app of a cell phone.\n\nTo use such filters, the order is important.\n\nNote: If you modify filters in the Gmail web interface,\nthe order is changed: the modified one goes to the bottom.\n\nThis is one of the reasons why I wanted these scripts.\n\n### Use DummyInbox to leave only specific mails in the Inbox\n\nYou may have more labels with which mails must skip the Inbox.\n\nIn this case, **DummyInbox** method label can be used instead of\nsetting **shouldArchive: \"true\"** for filters.\n\nThe setting is like this:\n\n```\nfilters:\n- hasTheWord: \"from:foo@example.com\"\n label:\n - \"00_foo\"\n - \"99_DummyInbox\"\n- hasTheWord: \"from:example.com\"\n label:\n - \"01_example\"\n - \"99_DummyInbox\"\n- hasTheWord: \"from:example2.com\"\n label: \"02_example2\"\n- hasTheWord: \"from:example3.com\"\n label: \"03_example3\"\n- hasTheWord: \"from:example4.com\"\n label: \"04_example4\"\n- hasTheWord: \"from:example5.com\"\n label: \"05_example5\"\n- hasTheWord: \"has:nouserlabels\"\n label: \"09_others\"\n- hasTheWord: \"-label:99_DummyInbox\"\n shouldArchive: \"true\"\n```\n\nThis setting put additional **99_DummyInbox** label\nto which you want to remain in the Inbox.\n\nAnd the final filter archives mails without **99_DummyInbox** label.\n\nIn the above setting, **has:nouserlabels** is not used for **from:example.com**.\nTherefore the mail from **foo@example.com** has two labels.\n\nThe main difference from\n[Use labels like folder](https://github.com/rcmdnk/gmail_filter_manager#use-labels-like-folder) method\nis that you can put two different labels between them archive policies are different.\n\nIf **shouldArchive** is in the each label, all mails associated to the label are archived.\nBut this method can remain what you want easily.\n\nIn addition, only the order of the filters can be free other than the last label,\nso that it makes easy to modify with the web interface.\nAlthough you still need to \"modify\"\n**hasTheWord: \"-label:99_DummyInbox\"** filter after any other filter changes...\n(such adding one space in **Has the words** and save, and remove the space and save again...)\n\n## References\n\n- [gmail_filter_manager: Gmail\u306e\u30d5\u30a3\u30eb\u30bf\u3092YAML\u3067\u7c21\u5358\u306b\u7ba1\u7406\u3059\u308b](https://rcmdnk.com/blog/2018/07/07/computer-gmail-python/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Gmail filer manager using YAML format.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/rcmdnk/gmail_filter_manager",
"Repository": "https://github.com/rcmdnk/gmail_filter_manager"
},
"split_keywords": [
"gmail",
"yaml",
"cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "261805f28e68298d0d143598e0f42b9f939fbbc8f896c1e35ec7fb6f21e8d4c6",
"md5": "de0c62a590347ba2d26a9f213179998b",
"sha256": "d8fe10a71beb20e3d89ccadbaccc698a6ce4d78a5b6aa098abf191f29eacd72c"
},
"downloads": -1,
"filename": "gmail_filter_manager-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de0c62a590347ba2d26a9f213179998b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<3.12",
"size": 7399,
"upload_time": "2023-07-03T15:27:00",
"upload_time_iso_8601": "2023-07-03T15:27:00.423467Z",
"url": "https://files.pythonhosted.org/packages/26/18/05f28e68298d0d143598e0f42b9f939fbbc8f896c1e35ec7fb6f21e8d4c6/gmail_filter_manager-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4026aff8d554774eebc09cc96eb2ef9d1588ffadd7f0e01ec155f398d33fc12b",
"md5": "c20a5af1c07de0e71fe22ece9540ff20",
"sha256": "7efdabf2f2e6cf384f6b8796dcd24fc9db41ff3d8eb5d2e98fc6249b60baabbb"
},
"downloads": -1,
"filename": "gmail_filter_manager-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "c20a5af1c07de0e71fe22ece9540ff20",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<3.12",
"size": 6952,
"upload_time": "2023-07-03T15:27:01",
"upload_time_iso_8601": "2023-07-03T15:27:01.971611Z",
"url": "https://files.pythonhosted.org/packages/40/26/aff8d554774eebc09cc96eb2ef9d1588ffadd7f0e01ec155f398d33fc12b/gmail_filter_manager-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-03 15:27:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rcmdnk",
"github_project": "gmail_filter_manager",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gmail-filter-manager"
}
JSON
