wuttjamaican/docs/narr/email/custom.rst

Custom Emails
=============

It is fairly straightforward to add a new type of email for your app
to send.


Configure Template Dir
----------------------

Your project should contain a folder dedicated to email templates;
these would be committed to your repo as for other project files.
This is often ``email/templates`` or ``templates/email`` under the
package root.

Also the app config must include this path for the email templates
setting.  The order matters here as the first template found via
lookup will be used, for a given key (and content-type).  To include
"Poser" as well as built-in WuttaWeb template dirs:

.. code-block:: ini

   [wutta.email]
   templates =
       poser:templates/email
       wuttaweb:email/templates

Often you can set this in your :term:`config extension` instead of
needing to set it in the config file::

    from wuttjamaican.conf import WuttaConfigExtension

    class PoserConfigExtension(WuttaConfigExtension):

        def configure(self, config):
            config.setdefault('wutta.email.templates',
                              'poser:templates/email wuttaweb:email/templates')

However the config file value, if set, will override the extension
default.


Create the Template
-------------------

Now that you have a configured template folder, create the template
file(s) within it.  Each type of email is expected to have templates
for one or both of the ``text/plain`` and ``text/html`` content-types
(using ``txt`` and ``html`` as shorthand name, respectively).

Template files must use the :doc:`Mako template language <mako:index>`
and be named based on the :attr:`~wuttjamaican.email.Message.key` for
the email type, as well as content-type.

Therefore a new email of type ``poser_alert_foo`` would need one or
both of these defined:

* ``poser_alert_foo.html.mako``
* ``poser_alert_foo.txt.mako``

It is generally a good idea to create both templates but for internal
emails, it is often sufficient to define only the HTML template.  And
styles for email messages are notoriously wonky but again, for
internal use one need not worry about that so much.

Keep in mind, any context you wish to reference within the template,
must be provided by caller when sending email.

.. note::

   At this time there are no built-in email templates for
   WuttJamaican.  However there is (at least) one template defined in
   `wuttaweb:email/templates
   <https://forgejo.wuttaproject.org/wutta/wuttaweb/src/branch/master/src/wuttaweb/email/templates>`_
   which you can reference as a real example.


Configure Sending
-----------------

With template file in the right place, your email can already be used.
However it would be sent only to the (app-wide) "default" recipients,
and with generic subject line.

To fix that you can add to your config file, again based on your email
key:

.. code-block:: ini

   [wutta.email]
   poser_alert_foo.subject = HIGH ALERT TYPE ${alert_type.upper()}
   poser_alert_foo.sender = poser@example.com
   poser_alert_foo.to = alert-monitor@example.com
   poser_alert_foo.cc = admin@example.com

Note the subject line can be a Mako template string, referencing the
template context etc.


Test Sending
------------

Now you should be all set.  When sending the email, you must provide
any context which may be needed for the template rendering.  Assuming
you have that, call :meth:`~wuttjamaican.app.AppHandler.send_email()`
on your :term:`app handler`, giving it key and context::

   app.send_email('poser_alert_foo', {
       'alert_type': 'foo',
       'alert_msg': "foo has unexpected value! or something happened, etc.",
   })