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:

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

Often you can set this in your 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 Mako template language and be named based on the 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 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:

[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 send_email() on your 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.",
})