This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Script to count the number of emails in your gmail inbox

Project Description

gmailcount is a simple script to count the number of emails in your gmail
inbox. It's primary purpose is to allow status-bar programs like xmobar or
i3bar to poll your inbox without the need to store your password in plaintext.


gmailcount is tested on python 3.5. It may work on older versions of python 3.

Installation is simple:

pip3 install gmailcount

with Secret Service support (gnome-keyring):

pip3 install gmailcount[secretservice]

gnome-keyring support also requires the `dbus-python` package which can't be
installed via pip. It can be installed via system package manager (python3-dbus
on Debian) or from source.

If your system keyring isn't working you can install alternative keyring support:

pip3 install gmailcount[altkeyrings]

Alternative keyring support includes keyring backends that should work on
almost any system, but may not be as secure. For more information on keyring
configuration check out the python keyring


usage: gmailcount [-h] [-s | -d | -p] [-t TIMEOUT] [--debug] email_address

Check gmail message count.

positional arguments:
email_address email address to use

optional arguments:
-h, --help show this help message and exit
-s, --set-password set the password for email_address
-d, --delete-password
delete the password for email_address
-p, --prompt have gmail-count prompt you for your password
-t TIMEOUT, --timeout TIMEOUT
request timeout
--debug print any exception traceback

Before you can use gmailcount in your status bar, you'll need to run it with
the `-s` flag to set the password for your email address. Once you've set your
password it will be stored in your system keyring. Any program using your
gmailcount will need to have access to your keyring.

When used with no flags, gmailcount will print the number of emails in your
inbox to stdout or nothing in case of failure.

Security concerns

One of the main goals of gmailcount is to provide a minimum level of
security. To that end, all requests are sent via SSL, passwords are stored in
your system keyring (and are presumably encrypted if your system keyring is
worth anything), and the recommended use pattern is with app passwords on
accounts with two-factor authentication enabled. This allows you to keep your
password out of your dotfiles and encrypted, and to revoke your password in
case your system is compromised.

Obviously though any system that allows your computer to poll your email
without any human interaction isn't going to be ideal from a security
standpoint. gmailcount is only as secure as your system keyring, which
depending on how you use it and your configuration may not be very secure at
all. Certainly if you're using gmailcount in a status bar, any one who
manages to get access to your logged in user account will have access to your
email, and if your keyring is secured by an insufficently strong password,
someone with access to your harddrive may be able to crack your keyring
password and access your gmail password.

Use gmailcount at your own risk! Still, it should be a lot more secure than a
system that just stores your password as plain text at least.

Sample xmobar script

Here's an example of a script suitable for use with xmobar:

#!/usr/bin/env sh


full_text=$(/path/to/gmailcount -t 0.3 "$email")

case $full_text in
''|*[!0-9]*) color=\#FF0000 ;;
0) color=\#888888 ;;
*) color=\#00FF00 ;;

echo "<action=\`xdg-open $url\`><fc=$color>✉ $full_text</fc></action>"

Sample i3blocks script

Here's one suitable for use with i3blocks:

#!/usr/bin/env sh


[ "$BLOCK_BUTTON" = 1 ] && xdg-open "$url"

full_text=$(/path/to/gmailcount -t 0.3 "$email")

case $full_text in
''|*[!0-9]*) color=\#FF0000 ;;
0) color=\#888888 ;;
*) color=\#00FF00 ;;

echo "$full_text"
echo "$short_text"
echo "$color"

Sample Asynchrnous xmobar script

Here's a somewhat more sophisticated script for xmobar which never blocks
waiting for the google servers. It works by writing the data asynchronously to
a temp file. The first argument to the script will set a timeout for writing
the data so that you can check gmail just before your status bar updates.
Something similar should work for i3blocks.

#!/usr/bin/env sh


echo_status() {
echo "<action=\`xdg-open $URL\`><fc=$2><fn=1></fn> $1</fc></action>"

write_data() {
sleep "$SLEEPTIME"
full_text=$("$GMAILCOUNT" "$EMAIL")

case $full_text in
''|*[!0-9]*) color=\#FF0000 ;;
0) color=\#888888 ;;
*) color=\#00FF00 ;;

echo_status "$full_text" "$color" > "$STATUSFILE"

output=$(cat "$STATUSFILE")
[ ! -z "$output" ] && echo "$output" || echo_status "?" \#880088
write_data &
Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
gmailcount-0.1.5.tar.gz (5.6 kB) Copy SHA256 Checksum SHA256 Source Aug 28, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting