# mongars - count inbox emails
Count inbox emails using Gmail API or Gnome Online Accounts (limited support)
## Description
`mongars` will take an email account as configured in Gnome Online account
(only oauth based email account is supported) or via the GMAIL API and will
output how many unread emails you have in there.
## Usage
### Gmail API
You need to [generate a OAUTH
credentials.json](https://developers.google.com/workspace/guides/create-credentials)
via the google API console.
When it's done using [pass](https://www.passwordstore.org/) you need to insert
it in your pass store:
```shell
pass insert -m google/$EMAIL.mail.credential
INSERT YOUR CREDENTIALS HERE
```
Run `mongars` on your terminal for the first time with the flag `--gauth` and
your `$EMAIL` as argument:
```shell
mongars --gauth $EMAIL
```
It will print a URL to open in your web browser and start the google Oauth flow
to allow it to access to read your email on your `$EMAIL` account. It stores and
refresh the temporary token in `~/.cache/mongars/token.$EMAIL.json`.
You can define the pass key to other values by defining the flags
`--gauth-pass-cred-key`. If you want to use the same credentials for multiple
emails you would want to define this flag to the same value to both pass key
path.
If you want you can as well redefine the `--gauth-pass-token-file` somewhere else.
You will have notification on new email if you have the `notify-send`
command installed. The notifications include an Open and Archive option,
the Open is limited to a search because the Gmail interface don't have direct links support.
You can customize the template and the command with the
`--notify-command-template` flag the default is:
`notify-send -i "{icon}" "{sender}" "{subject}"`
The variables supported are `icon`, `sender`, `subject` and `snippet`
are replaced with the values from the email.
You can output a markdown formatted (optionally) with `gum` if you pass the
option `-M/--show-markdown`
You can output as json for waybar with `-J/--show-json` and it will show a
tooltip of your last 5 message and subject snippet.
We are generally just quiet and don't output anything if there is an error,
just use `-v` to see the error.
### Gnome Online Accounts
You just need to specify the email to check as an argument i.e:
```shell
mongars john.snow@gmail.com
```
By default it will output the number of messages from your mailbox with an icon of different
colours if there is unread message or not.
The `INBOX` folder is the default folder, if you would like to count another folder you can specify the `-m` option to it :
```shell
mongars -m Label1 john.snow@gmail.com
```
You can further customize the colour output which uses lemonbar formatting with :
- `--icon`: the glyph icon default to ``
- `--icon-color-unreads`: the color when unreads, default to a yellow `#ffd700` set this to empty if you don't want any color formatting.
- `--icon-color-normal`: the normal colors. (no default)
By default if you have no mail it will output a 0 unless you specify the flag `--no-mail-no-zero`
If you don't want any icons you can simply use the `--no-icon` and it will just output the number.
This currently only support oauth2 based accounts, imap account with username,
password are not currently supported (patch welcome but you probably want to use
something more secure).
I only tested it with Google/Gmail accounts (enterprise and personal) so let me
know if it works or not on other oauth2 based email accounts.
## Install
### Arch
You can install this [from aur](https://aur.archlinux.org/packages/mongars) with your aurhelper, like yay :
```
yay -S mongars
```
### pip
With pip from pypip - https://pypi.org/project/mongars/
```
pip install --user mongars
```
(make sure $HOME/.local/bin is in your PATH)
### Manual
Checkout this repository, [install poetry](https://python-poetry.org/docs/#installation) and run it with :
```shell
poetry install mongars
poetry run mongars
```
## Running it without Gnome
If you run this outside of gnome environement (ie: from a windows manager), you have to configure the accounts
first in Gnone Online Account settings from gnome and then you can use it from your windows manager.
From your window manager start scripts or [somewhere else](https://wiki.archlinux.org/title/Xinit) you need to make sure to run the goa-daemon, for example on arch the path is `/usr/lib/goa-daemon` and from your startup script you will do :
```shell
/usr/lib/goa-daemon --replace &
```
different distros may have a different path, see also this bugzilla bug
[#1340203](https://bugzilla.redhat.com/show_bug.cgi?id=1340203))
## Polybar
You can easily integrate this with [Polybar](https://github.com/polybar/polybar) :
```ini
[module/email]
type = custom/script
exec = mongars email@gmail.com
interval = 30
click-left = xdg-open https://mail.google.com/
exec-if = grep -q email@gmail.com ~/.config/goa-1.0/accounts.conf 2>/dev/null && ping -c1 mail.google.com
```
## Waybar
```json
"custom/email": {
"format": " {} ",
"interval": 15,
"exec": "mongars email@gmail.com --no-mail-no-zero --no-icon",
"on-click": "xdg-open https://mail.google.com"
},
```
and you can style it in `style.css` file :
```css
#custom-email {
color: #b22222;
}
```
#### Waybar as Json with Gauth
The gauth method support output to json, here is an example integrating it:
```json
{
"custom/email-work": {
"format": "{} ",
"return-type": "json",
"tooltip": "true",
"tooltip-format": "{tooltip}",
"interval": 15,
"exec": "poetry run mongars --gauth myemail@gmail.com -J",
"on-click-middle": "kitty -T \"Email for myemail@gmail.com\" bash -c \"mongars --gauth myemail@gmail.com -M|less -R\"",
"on-click": "xdg-open https://mail.google.com/"
}
}
```
## License
[Apache 2.0](./LICENSE)
## Authors
© 2021 Chmouel Boudjnah ([@chmouel](https://twitter.com/chmouel)) - https://chmouel.com
Raw data
{
"_id": null,
"home_page": "https://github.com/chmouel/mongars",
"name": "mongars",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "email,cli",
"author": "Chmouel Boudjnah",
"author_email": "chmouel@chmouel.com",
"download_url": "https://files.pythonhosted.org/packages/eb/fe/2979a6dda1d7813ce591366663c9c3dcd6cce21bcd673091d4e5f9a639e0/mongars-1.4.3.tar.gz",
"platform": null,
"description": "# mongars - count inbox emails\n\nCount inbox emails using Gmail API or Gnome Online Accounts (limited support)\n\n## Description\n\n`mongars` will take an email account as configured in Gnome Online account\n(only oauth based email account is supported) or via the GMAIL API and will\noutput how many unread emails you have in there.\n\n## Usage\n\n### Gmail API\n\nYou need to [generate a OAUTH\ncredentials.json](https://developers.google.com/workspace/guides/create-credentials)\nvia the google API console.\n\nWhen it's done using [pass](https://www.passwordstore.org/) you need to insert\nit in your pass store:\n\n```shell\npass insert -m google/$EMAIL.mail.credential\nINSERT YOUR CREDENTIALS HERE\n```\n\nRun `mongars` on your terminal for the first time with the flag `--gauth` and\nyour `$EMAIL` as argument:\n\n```shell\nmongars --gauth $EMAIL\n```\n\nIt will print a URL to open in your web browser and start the google Oauth flow\nto allow it to access to read your email on your `$EMAIL` account. It stores and\nrefresh the temporary token in `~/.cache/mongars/token.$EMAIL.json`.\n\nYou can define the pass key to other values by defining the flags\n`--gauth-pass-cred-key`. If you want to use the same credentials for multiple\nemails you would want to define this flag to the same value to both pass key\npath.\n\nIf you want you can as well redefine the `--gauth-pass-token-file` somewhere else.\n\nYou will have notification on new email if you have the `notify-send`\ncommand installed. The notifications include an Open and Archive option,\nthe Open is limited to a search because the Gmail interface don't have direct links support.\n\n\n\nYou can customize the template and the command with the\n`--notify-command-template` flag the default is:\n\n`notify-send -i \"{icon}\" \"{sender}\" \"{subject}\"`\n\nThe variables supported are `icon`, `sender`, `subject` and `snippet`\nare replaced with the values from the email.\n\nYou can output a markdown formatted (optionally) with `gum` if you pass the\noption `-M/--show-markdown`\n\n\n\nYou can output as json for waybar with `-J/--show-json` and it will show a\ntooltip of your last 5 message and subject snippet.\n\n\n\nWe are generally just quiet and don't output anything if there is an error,\njust use `-v` to see the error.\n\n### Gnome Online Accounts\n\nYou just need to specify the email to check as an argument i.e:\n\n```shell\nmongars john.snow@gmail.com\n```\n\nBy default it will output the number of messages from your mailbox with an icon of different\ncolours if there is unread message or not.\n\nThe `INBOX` folder is the default folder, if you would like to count another folder you can specify the `-m` option to it :\n\n```shell\nmongars -m Label1 john.snow@gmail.com\n```\n\nYou can further customize the colour output which uses lemonbar formatting with :\n\n- `--icon`: the glyph icon default to `\uf2b6`\n- `--icon-color-unreads`: the color when unreads, default to a yellow `#ffd700` set this to empty if you don't want any color formatting.\n- `--icon-color-normal`: the normal colors. (no default)\n\nBy default if you have no mail it will output a 0 unless you specify the flag `--no-mail-no-zero`\n\nIf you don't want any icons you can simply use the `--no-icon` and it will just output the number.\n\nThis currently only support oauth2 based accounts, imap account with username,\npassword are not currently supported (patch welcome but you probably want to use\nsomething more secure).\n\nI only tested it with Google/Gmail accounts (enterprise and personal) so let me\nknow if it works or not on other oauth2 based email accounts.\n\n## Install\n\n### Arch\n\nYou can install this [from aur](https://aur.archlinux.org/packages/mongars) with your aurhelper, like yay :\n\n```\nyay -S mongars\n```\n\n### pip\n\nWith pip from pypip - https://pypi.org/project/mongars/\n\n```\npip install --user mongars\n```\n\n(make sure $HOME/.local/bin is in your PATH)\n\n### Manual\n\nCheckout this repository, [install poetry](https://python-poetry.org/docs/#installation) and run it with :\n\n```shell\npoetry install mongars\npoetry run mongars\n```\n\n## Running it without Gnome\n\nIf you run this outside of gnome environement (ie: from a windows manager), you have to configure the accounts\nfirst in Gnone Online Account settings from gnome and then you can use it from your windows manager.\n\nFrom your window manager start scripts or [somewhere else](https://wiki.archlinux.org/title/Xinit) you need to make sure to run the goa-daemon, for example on arch the path is `/usr/lib/goa-daemon` and from your startup script you will do :\n\n```shell\n/usr/lib/goa-daemon --replace &\n```\n\ndifferent distros may have a different path, see also this bugzilla bug\n[#1340203](https://bugzilla.redhat.com/show_bug.cgi?id=1340203))\n\n## Polybar\n\nYou can easily integrate this with [Polybar](https://github.com/polybar/polybar) :\n\n```ini\n[module/email]\ntype = custom/script\nexec = mongars email@gmail.com\ninterval = 30\nclick-left = xdg-open https://mail.google.com/\nexec-if = grep -q email@gmail.com ~/.config/goa-1.0/accounts.conf 2>/dev/null && ping -c1 mail.google.com\n```\n\n## Waybar\n\n```json\n \"custom/email\": {\n \"format\": \" {} \",\n \"interval\": 15,\n \"exec\": \"mongars email@gmail.com --no-mail-no-zero --no-icon\",\n \"on-click\": \"xdg-open https://mail.google.com\"\n },\n```\n\nand you can style it in `style.css` file :\n\n```css\n#custom-email {\n color: #b22222;\n}\n```\n\n#### Waybar as Json with Gauth\n\nThe gauth method support output to json, here is an example integrating it:\n\n```json\n{\n \"custom/email-work\": {\n \"format\": \"{} \",\n \"return-type\": \"json\",\n \"tooltip\": \"true\",\n \"tooltip-format\": \"{tooltip}\",\n \"interval\": 15,\n \"exec\": \"poetry run mongars --gauth myemail@gmail.com -J\",\n \"on-click-middle\": \"kitty -T \\\"Email for myemail@gmail.com\\\" bash -c \\\"mongars --gauth myemail@gmail.com -M|less -R\\\"\",\n \"on-click\": \"xdg-open https://mail.google.com/\"\n }\n}\n```\n\n## License\n\n[Apache 2.0](./LICENSE)\n\n## Authors\n\n\u00a9 2021 Chmouel Boudjnah ([@chmouel](https://twitter.com/chmouel)) - https://chmouel.com\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Show unread emails in INBOX using Gmail Api or Gnome Online Accounts",
"version": "1.4.3",
"project_urls": {
"Homepage": "https://github.com/chmouel/mongars",
"Repository": "https://github.com/chmouel/mongars"
},
"split_keywords": [
"email",
"cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ebfe2979a6dda1d7813ce591366663c9c3dcd6cce21bcd673091d4e5f9a639e0",
"md5": "6fb27e4a6bcba5fc118ca2b66d70fb44",
"sha256": "70db430efd5c26e31c96c84ac0c3620c3ae806426dbbfb9b4976183ec30e82b2"
},
"downloads": -1,
"filename": "mongars-1.4.3.tar.gz",
"has_sig": false,
"md5_digest": "6fb27e4a6bcba5fc118ca2b66d70fb44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 15843,
"upload_time": "2024-02-19T09:32:17",
"upload_time_iso_8601": "2024-02-19T09:32:17.802323Z",
"url": "https://files.pythonhosted.org/packages/eb/fe/2979a6dda1d7813ce591366663c9c3dcd6cce21bcd673091d4e5f9a639e0/mongars-1.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-19 09:32:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chmouel",
"github_project": "mongars",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mongars"
}
JSON
