bgneal@8: ========= bgneal@8: weighmail bgneal@8: ========= bgneal@8: An application to label your Gmail messages according to size bgneal@8: ------------------------------------------------------------- bgneal@8: bgneal@8: :Author: Brian Neal bgneal@8: :Version: 0.1.0 bgneal@8: :Date: May 19, 2012 bgneal@8: :Home Page: https://bitbucket.org/bgneal/weighmail/ bgneal@8: :Download: TODO bgneal@8: :License: New BSD License (see COPYING) bgneal@8: :Support: https://bitbucket.org/bgneal/weighmail/issues bgneal@8: bgneal@8: bgneal@8: Overview bgneal@8: -------- bgneal@8: bgneal@8: ``weighmail`` is a program that analyzes your Gmail and applies labels to your bgneal@8: messages according to their size. This is useful if you are close to reaching bgneal@8: your quota as it allows you to quickly identify large messages. You have bgneal@8: complete control over the rules used to create the labels. bgneal@8: bgneal@8: bgneal@8: Installation bgneal@8: ------------ bgneal@8: bgneal@8: ``weighmail`` can be installed using Pip_:: bgneal@8: bgneal@8: $ pip install weighmail # TODO: get up on PyPI bgneal@8: bgneal@8: Alternatively you can download a tarball and install with:: bgneal@8: bgneal@8: $ python setup.py install bgneal@8: bgneal@8: ``weighmail`` depends on the IMAPClient_ library. This library is automatically bgneal@8: installed if you use Pip_. bgneal@8: bgneal@8: Gmail Notes bgneal@8: ----------- bgneal@8: bgneal@8: In case it isn't clear, ``weighmail`` works with Gmail_. You must have a Gmail bgneal@8: account with `IMAP support turned on`_. Please go into your settings and verify bgneal@8: IMAP support is turned on before proceeding. bgneal@8: bgneal@8: If you are using `two-step verification`_ on your Gmail account (**and you bgneal@8: really should be**), you `need to generate an application specific password`_ bgneal@8: for ``weighmail`` to use. In this case you will use an application specific bgneal@8: password instead of your normal password when running ``weighmail``. bgneal@8: bgneal@8: bgneal@8: Usage bgneal@8: ----- bgneal@8: bgneal@8: ``weighmail`` can accept options from a configuration file and/or the bgneal@8: command-line. Command-line arguments always take precedence over options found bgneal@8: in the configuration file. bgneal@8: bgneal@8: Command-Line Arguments bgneal@8: ~~~~~~~~~~~~~~~~~~~~~~ bgneal@8: bgneal@8: ``weighmail`` takes a fair number of arguments on the command-line. Most of bgneal@8: these can be omitted however, as they all have sensible defaults. In fact, the bgneal@8: simplest way to run ``weighmail`` is as follows:: bgneal@8: bgneal@8: $ weighmail --labels big:1MB-5MB huge:5MB-10MB enormous:10MB- bgneal@8: bgneal@8: This example demonstrates: bgneal@8: bgneal@8: * A *big* label will be applied to messages between 1 and 5 Megabytes bgneal@8: * A *huge* label will be applied to messages between 5 and 10 Megabytes bgneal@8: * An *enormous* label will be applied to messages 10 MB and bigger bgneal@8: * Since no ``user`` or ``password`` options were supplied on the command-line, bgneal@8: ``weighmail`` will interactively prompt for them. Neither will be echoed out bgneal@8: for privacy reasons. bgneal@8: bgneal@8: To see a list of all command-line options:: bgneal@8: bgneal@8: $ weighmail --help bgneal@8: bgneal@8: Some notes on the options follows. bgneal@8: bgneal@8: * The ``--config`` option is used to specify a configuration file that bgneal@8: ``weighmail`` will read for options. Any options supplied on the command-line bgneal@8: will override any options from this file. In particular, if you specify any bgneal@8: label rules on the command-line, all label rules in the configuration file bgneal@8: will be ignored. bgneal@8: * The ``--folder`` option can be used to specify which Gmail label to search for bgneal@8: messages. This defaults to your *All Mail* label. bgneal@8: * The ``--user`` and ``--password`` options are used to specify which Gmail bgneal@8: account to log into. If these are not supplied, and also omitted from a config bgneal@8: file (or if no config file is being used), ``weighmail`` will prompt you for bgneal@8: these options. bgneal@8: * The ``--labels`` argument is how you specify the rules for labeling your bgneal@8: messages. See the sub-section below for more detail on this syntax. bgneal@8: * The ``--host``, ``--port``, and ``--nossl`` arguments are for advanced use bgneal@8: only, and may in fact not work. The defaults should work for most people, and bgneal@8: will connect you to ``imap.gmail.com`` port 993 using SSL. bgneal@8: bgneal@8: The --labels argument syntax bgneal@8: ++++++++++++++++++++++++++++ bgneal@8: bgneal@8: To specify label rules on the command-line, use the following syntax:: bgneal@8: bgneal@8: $ weighmail --labels name:min-max [name:min-max] ... bgneal@8: bgneal@8: Where: bgneal@8: bgneal@8: * *name* is the name of the label. Note that Gmail labels cannot have spaces in bgneal@8: them. bgneal@8: * *min* and *max* specify the message size range in bytes. Either one, but not bgneal@8: both, may be omitted (but the dash must remain). You may use the suffixes bgneal@8: ``KB``, ``MB``, or ``GB`` to indicate kilobytes, Megabytes, or Gigabytes, bgneal@8: respectively. bgneal@8: bgneal@8: Another example:: bgneal@8: bgneal@8: $ weighmail --labels normal:-2MB big:2MB-7MB huge:7MB- bgneal@8: bgneal@8: In all these examples the label ranges do not overlap. This does not have to be bgneal@8: the case; overlapping ranges may be defined if desired. bgneal@8: bgneal@8: bgneal@8: Configuration File bgneal@8: ~~~~~~~~~~~~~~~~~~ bgneal@8: bgneal@8: If you specify the ``--config=filename`` option on the command-line, bgneal@8: ``weighmail`` will parse this file for options. Please see the included bgneal@8: `sample-weighmail.ini` file for the syntax and option descriptions. bgneal@8: bgneal@8: Again, note that command-line arguments take precedence over options found in bgneal@8: the configuration file. If you specify *any* label rules on the command-line, bgneal@8: *all* label rules in the configuration file are ignored. bgneal@8: bgneal@8: bgneal@8: Thanks bgneal@8: ~~~~~~ bgneal@8: bgneal@8: A big thank-you to Menno Smits, the author of the IMAPClient_ library. This bgneal@8: application would have been considerably more complicated if the awesome bgneal@8: IMAPClient library did not exist. bgneal@8: bgneal@8: bgneal@8: .. _Pip: http://pypi.python.org/pypi/pip bgneal@8: .. _Gmail: http://mail.google.com/ bgneal@8: .. _IMAP support turned on: http://support.google.com/mail/bin/answer.py?hl=en&answer=77695 bgneal@8: .. _two-step verification: http://support.google.com/accounts/bin/answer.py?hl=en&answer=180744 bgneal@8: .. _need to generate an application specific password: http://support.google.com/accounts/bin/answer.py?hl=en&answer=185833&topic=1056283&ctx=topic bgneal@8: .. _IMAPClient: http://pypi.python.org/pypi/IMAPClient/