Package: mailflagger
Mail Flagger is a program that flags selected emails in your inbox (or copies them to another folder), typically when a relevant payment is made. This gives the sender a possibility to bring attention to his message and to compensate time spent by the receiver on reading and eventual responding. For rationale and use cases, seethe blog post.Mail Flagger is free software, licensed underApache License 2.0.How to useInstallPython(version 3.8 or newer is required). Windows users: check the “Add Python 3.8 to PATH” option and (if available) click the button “Disable path length limit” at the end of the installation.Install Mail Flagger: eitherdownload a releasefor your platform (Windows & Mac OS X only) or use thecustom installationmethod described below.Start Mail Flagger, fill in the configuration and run thedaemoncommand. Security note: Although your email password is stored locally on your computer, if at all, it is currently not encrypted and may be visible in the process command, which may have security implications especially if your computer is simultaneously being used by other people.Instruct your senders.Specific steps for senders depend on the payment method, but typically they will need to encompass a search query that specifies which message they want to get flagged. Its syntax is the same as the syntax forIMAP search command. An example query:SINCE 20-Mar-2020 FROM john.doe@example.com UNANSWEREDIf the sender knows how to extractMessage-ID, he may use it as follows:HEADER Message-Id <B27397-0100000@Blurdybloop.COM>Mail Flagger automatically adds theUNFLAGGEDsearch term to the provided query.Payment methodsThe daemon only listens and waits until something tells it to flag a message, it does nothing on its own initiative. To make it do something, you need a flagging provider, typically tied to a payment method(s). Two of them are bundled inside the default release packages, but the overall mechanism is extensible and allows writing providers in various programming languages.BankingThis provider adds a subcommand that allows importing a file in the MT940 format containing a list of transactions. Daemon needs to be running separately for this to work. A query needs to be encompassed in transaction message (optionally with a specific prefix to distinguish it from other transfers).Manual export and import is cumbersome, but it is a typical limitation for banking systems, which do not facilitate integration for ordinary users. For a more smooth experience with live transaction processing, consider using cryptocurrencies.ErcoinThis provider adds an optional daemon coroutine that runs along the main daemon and live monitorsErcointransactions. A query needs to be encompassed in transaction message.Advanced usageCustom installationMail Flagger can be installed usingpip:pip install mailflaggerFor GUI support, installmailflagger[GUI]instead of the above. IfwxPython wheelsare not available for your platform, you may want to use a system package of wxPython (if available) instead of building it from source. (When using virtualenv, note the--system-site-packagesoption).Two plugins bundled in the standard release aremailflagger_bankingandmailflagger_ercoin.Command lineIf you don’t want to use the GUI, either make a custom installation without the GUI support or provide any argument to themailflaggercommand.Creating custom providersGeneric methodThe daemon exposes itself as aZeroMQserver. To flag a message, it is sufficient to connect to it and send aMessagePack-encoded map containing IMAP query associated with the"query"key. A reply will be another map containing key"processed"(should betrue).Python pluginsProvider can be embedded into the main Main Flagger program either as subcommands or as coroutines which will be started with the daemon. When writing plugins, themailflagger.client.Clientclass should be helpful. It wraps the ZeroMQ connection and message packing and unpacking.When defining plugin-specific configuration options, remember to avoid name clashes and potential name clashes (with other plugins).When we write about “default arguments”, we mean either default argument values or values saved in a configuration file.SubcommandsThis type of plugin needs to specify amailflagger.plugins.commandsentry point which points to an object which defines the following function attributes:modify_subparser(accepting subparser) — optional, used to add plugin-specific configuration options.run(accepting parsed arguments) — used to do the actual job.command_help(accepting default arguments) — optional, it returns help for the subcommand.See themailflagger_bankingplugin for an example.Daemon coroutinesThis type of plugin needs to specify amailflagger.plugins.daemonentry point which points to an object which defines the following function attributes:modify_subparser(accepting subparser) — optional, used to add plugin-specific configuration options to the daemon subparser.daemon_coroutines(accepting parsed arguments) — returning an iterable of coroutines that shall be started along with the server daemon.See themailflagger_ercoinplugin for an example.