\n Please click on the link below:\n click me!\n
\n\nNote that this cache is a *per-email-instance* cache.\n\n\nEncrypted Email\n===============\n\nThe genemail ``pgp`` optional feature allows you to generate encrypted\noutbound email. It does this using the ``python-gnupg`` package, which\nin turn uses the ``gpg`` external command-line program. Genemail can\nboth encrypt and sign the emails, or only encrypt. Steps to generate\nencrypted email:\n\n1. First, create a GPG-home directory with all of the necessary\nkeys. For example:\n\n.. code-block:: bash\n\n # create the directory\n $ mkdir -p /path/to/gpghome\n $ chmod 700 /path/to/gpghome\n\n # for signing, a private key is needed. generate one:\n $ gpg --homedir /path/to/gpghome --gen-key\n\n # for encryption, the public key of every recipient of encrypted\n # emails is needed. do this for every recipient:\n $ gpg --homedir /path/to/gpghome --import /path/to/recipient/public.key\n\n2. Then, configure genemail to use the\n``genemail.modifier.PgpModifier`` modifier. For example:\n\n.. code-block:: python\n\n import genemail\n\n # configure a genemail manager using the modifier\n manager = genemail.Manager(\n # ...\n modifier = genemail.modifier.PgpModifier(\n sign = 'noreply@example.com',\n gpg_options = dict(gnupghome = '/path/to/gpghome'),\n ),\n # ...\n )\n\nPgpModifier takes the following parameters:\n\n* ``sign``: str, optional, default: null\n\n If specified, it is taken to be the ID or email address of the GPG\n key to use to sign outbound emails. In this case, either the\n passphrase must be empty, or you must be using a gpg-agent. The\n default is null, which disables signing.\n\n* ``add_key``: list(str), optional, default: 'sign-key'\n\n The `add_key` parameter specifies IDs or email addresses that should\n be added to the encryption list, but not to the recipient list.\n This is useful if a global 'backdoor' key is needed. It can also be\n set to ``'sign-key'`` (the default) which indicates that the signing\n key should be added (thus the sender can decrypt the sent\n messages). Set this to null to disable any addition. It can also be\n a list of values.\n\n* ``prune_keys``: bool, optional, default: true\n\n If truthy (the default), then the list of email addresses for whom\n the email is encrypted for is reduced to the set of recipients that\n have an exactly matching key. If too many addresses are pruned (this\n can happen if the gpg binary is smarter at matching an email address\n to a key), then this may need to be set to false -- but beware, if\n any address cannot be resolved to a key by gpg, then the entire\n encryption process fails, and the email is not sent.\n\n* ``prune_recipients``: bool, optional, default: false\n\n If truthy, then encrypted emails will only be sent to the list of\n addresses that were the result of a `prune_keys` pruning. If they\n are not pruned, the recipients will receive emails that they cannot\n read. This is by default false so that it is more obvious that some\n action needs to be taken (i.e. give the GPG-home directory the\n appropriate list of keys).\n\n* ``gpg_options``: dict, optional\n\n This parameter is a collection of parameters passed to gnupg. The\n only required parameter is `gnupghome`, which is the path to the\n GPG-home directory. All currently available parameters:\n\n * ``gnupghome``: str, optional, default: null\n * ``gpgbinary``: str, optional, default: 'gpg'\n * ``use_agent``: bool, optional, default: false\n * ``verbose``: bool, optional, default: false\n * ``keyring``: str, optional, default: null\n * ``secret_keyring``: str, optional, default: null\n * ``options``: list(str), optional, default: null\n\n\nUnit Testing\n============\n\nThe following example test code illustrates the recommended approach\nto do unit testing with genemail (note the use of the `pxml` library\nto compare HTML output):\n\n.. code-block:: python\n\n import unittest, pxml, genemail, genemail.testing\n\n class AppTest(genemail.testing.EmailTestMixin, pxml.XmlTestMixin, unittest.TestCase):\n\n def setUp(self):\n super(AppTest, self).setUp()\n self.sender = genemail.DebugSender()\n # the following is very subjective to how your app is built & used,\n # but the idea is to provide a different `sender` to genemail...\n self.app = App()\n self.app.genemail.sender = self.sender\n\n def test_email(self):\n\n # do something to cause an email to be sent\n self.app.send_an_email()\n\n # verify the sent email (which will have been trapped by self.sender)\n self.assertEqual(len(self.sender.emails), 1)\n self.assertEmailEqual(self.sender.emails[0], '''\\\n Content-Type: multipart/alternative; boundary=\"==BOUNDARY-MAIN==\"\n MIME-Version: 1.0\n Date: Fri, 13 Feb 2009 23:31:30 -0000\n To: test@example.com\n Message-ID: <1234567890@@genemail.example.com>\n From: noreply@example.com\n Subject: Test Subject\n\n --==BOUNDARY-MAIN==\n MIME-Version: 1.0\n Content-Type: text/plain; charset=\"us-ascii\"\n Content-Transfer-Encoding: 7bit\n\n Email text version.\n\n --==BOUNDARY-MAIN==\n Content-Type: multipart/related; boundary=\"==BOUNDARY-HTMLREL==\"\n MIME-Version: 1.0\n\n --==BOUNDARY-HTMLREL==\n MIME-Version: 1.0\n Content-Type: text/html; charset=\"us-ascii\"\n Content-Transfer-Encoding: 7bit\n\n Email html version.\n\n --==BOUNDARY-HTMLREL==\n Content-Type: image/png\n MIME-Version: 1.0\n Content-Transfer-Encoding: 7bit\n Content-Disposition: attachment\n Content-ID: