wuttjamaican.email

Email Handler

class wuttjamaican.email.EmailHandler(*args, **kwargs)

Base class and default implementation for the email handler.

Responsible for sending email messages on behalf of the app.

You normally would not create this directly, but instead call get_email_handler() on your app handler.

deliver_message(message, sender=None, recips=None)

Deliver a message via SMTP smarthost.

Parameters:

• message – Either a Message object or similar, or a string representing the complete message to be sent as-is.

• sender – Optional sender address to use for delivery. If not specified, will be read from message.

• recips – Optional recipient address(es) for delivery. If not specified, will be read from message.

A general rule here is that you can either provide a proper Message object, or you must provide sender and recips. The logic is not smart enough (yet?) to parse sender/recips from a simple string message.

Note also, this method does not (yet?) have robust error handling, so if an error occurs with the SMTP session, it will simply raise to caller.

Returns:

None

get_auto_bcc(key)

Returns automatic bcc recipient address(es) for a message, as determined by config.

get_auto_cc(key)

Returns automatic cc recipient address(es) for a message, as determined by config.

get_auto_html_body(key, context={})

Returns automatic html_body content for a message, as determined by config. This renders a template with the given context.

get_auto_replyto(key)

Returns automatic replyto address for a message, as determined by config.

get_auto_sender(key)

Returns automatic sender address for a message, as determined by config.

get_auto_subject(key, context={}, rendered=True, setting=None)

Returns automatic subject line for a message, as determined by config.

This calls get_auto_subject_template() and then (usually) renders the result using the given context.

Parameters:

• key – Key for the email type.

• context – Dict of context for rendering the subject template, if applicable.

• rendered – If this is False, the “raw” subject template will be returned, instead of the final/rendered subject text.

• setting – Optional EmailSetting class or instance. This is passed along to get_auto_subject_template().

Returns:

Final subject text, either “raw” or rendered.

get_auto_subject_template(key, setting=None)

Returns the template string to use for automatic subject line of a message, as determined by config.

In many cases this will be a simple string and not a “template” per se; however it is still treated as a template.

The template returned from this method is used to render the final subject line in get_auto_subject().

Parameters:

• key – Key for the email type.

• setting – Optional EmailSetting class or instance. This may be used to determine the “default” subject if none is configured. You can specify this as an optimization; otherwise it will be fetched if needed via get_email_setting().

Returns:

Final subject template, as raw text.

get_auto_to(key)

Returns automatic to recipient address(es) for a message, as determined by config.

get_auto_txt_body(key, context={})

Returns automatic txt_body content for a message, as determined by config. This renders a template with the given context.

get_email_modules()

Returns a list of all known email modules.

This will discover all email modules exposed by the app, and/or its providers.

get_email_setting(key, instance=True)

Retrieve the email setting for the given email key (if it exists).

Parameters:

• key – Key for the email type.

• instance – Whether to return the class, or an instance.

Returns:

EmailSetting class or instance, or None if the setting could not be found.

get_email_settings()

Returns a dict of all known email settings, keyed by email key.

This calls get_email_modules() and for each module, it discovers all the email settings it contains.

get_notes(key)

Returns configured “notes” for the given email key.

Parameters:

key – Key for the email type.

Returns:

Notes as string if found; otherwise None.

is_enabled(key)

Returns flag indicating whether the given email type is “enabled” - i.e. whether it should ever be sent out (enabled) or always suppressed (disabled).

All email types are enabled by default, unless config says otherwise; e.g. to disable foo emails:

[wutta.email]

# nb. this is fallback if specific type is not configured
default.enabled = true

# this disables 'foo' but e.g 'bar' is still enabled per default above
foo.enabled = false

In a development setup you may want a reverse example, where all emails are disabled by default but you can turn on just one type for testing:

[wutta.email]

# do not send any emails unless explicitly enabled
default.enabled = false

# turn on 'bar' for testing
bar.enabled = true

See also sending_is_enabled() which is more of a master shutoff switch.

Parameters:

key – Unique identifier for the email type.

Returns:

True if this email type is enabled, otherwise false.

make_auto_message(key, context={}, **kwargs)

Make a new email message using config to determine its properties, and auto-generating body from a template.

Once everything has been collected/prepared, make_message() is called to create the final message, and that is returned.

Parameters:

• key – Unique key for this particular “type” of message. This key is used as a prefix for all config settings and template names pertinent to the message.

• context – Context dict used to render template(s) for the message.

• **kwargs – Any remaining kwargs are passed as-is to make_message(). More on this below.

Returns:

Message object.

This method may invoke some others, to gather the message attributes. Each will check config, or render a template, or both. However if a particular attribute is provided by the caller, the corresponding “auto” method is skipped.

• get_auto_sender()

• get_auto_subject()

• get_auto_to()

• get_auto_cc()

• get_auto_bcc()

• get_auto_txt_body()

• get_auto_html_body()

make_message(**kwargs)

Make and return a new email message.

This is the “raw” factory which is simply a wrapper around the class constructor. See also make_auto_message().

Returns:

Message object.

send_email(key=None, context={}, message=None, sender=None, recips=None, **kwargs)

Send an email message.

This method can send a message you provide, or it can construct one automatically from key / config / templates.

The most common use case is assumed to be the latter, where caller does not provide the message proper, but specifies key and context so the message is auto-created. In that case this method will also check is_enabled() and skip the sending if that returns false.

Parameters:

• key – When auto-creating a message, this is the email key identifying the type of email to send. Used to lookup config settings and template files.

• context – Context dict for rendering automatic email template(s).

• message – Optional pre-built message instance, to send as-is. If specified, nothing about the message will be auto-assigned from config.

• sender –

  Optional sender address for the message/delivery.

  If message is not provided, then the sender (if provided) will also be used when constructing the auto-message (i.e. to set the From: header).

  In any case if sender is provided, it will be used for the actual SMTP delivery.

• recips –

  Optional list of recipient addresses for delivery. If not specified, will be read from the message itself (after auto-generating it, if applicable).

  Note

  This param does not affect an auto-generated message; it is used for delivery only. As such it must contain all true recipients.

  If you provide the message but not the recips, the latter will be read from message headers: To:, Cc: and Bcc:

  If you want an auto-generated message but also want to override various recipient headers, then you must provide those explicitly:

  context = {'data': [1, 2, 3]}
  app.send_email('foo', context, to='me@example.com', cc='bobby@example.com')
  

• **kwargs – Any remaining kwargs are passed along to make_auto_message(). So, not used if you provide the message.

sending_is_enabled()

Returns boolean indicating if email sending is enabled.

Set this flag in config like this:

[wutta.mail]
send_emails = true

Note that it is OFF by default.

class wuttjamaican.email.EmailSetting(config)

Base class for all email settings.

Each email type which needs to have settings exposed e.g. for editing, should define a subclass within the appropriate email module.

The name of each subclass should match the email key which it represents. For instance:

from wuttjamaican.email import EmailSetting

class poser_alert_foo(EmailSetting):
    """
    Sent when something happens that we think deserves an alert.
    """

    default_subject = "Something happened!"

    def sample_data(self):
        return {
            'foo': 1234,
            'msg': "Something happened, thought you should know.",
        }

# (and elsewhere..)
app.send_email('poser_alert_foo', {
    'foo': 5678,
    'msg': "Can't take much more, she's gonna blow!",
})

Defining a subclass for each email type can be a bit tedious, so why do it? In fact there is no need, if you just want to send emails.

The purpose of defining a subclass for each email type is 2-fold, but really the answer is “for maintenance sake” -

• gives the app a way to discover all emails, so settings for each can be exposed for editing

• allows for hard-coded sample context which can be used to render templates for preview

default_subject

Default Message.subject for the email, if none is configured.

This is technically a Mako template string, so it will be rendered with the email context. But in most cases that feature can be ignored, and this will be a simple string.

sample_data()

Should return a dict with sample context needed to render the email template for message body. This can be used to show a “preview” of the email.

class wuttjamaican.email.Message(key=None, sender=None, subject=None, to=None, cc=None, bcc=None, replyto=None, txt_body=None, html_body=None)

Represents an email message to be sent.

Parameters:

to – Recipient(s) for the message. This may be either a string, or list of strings. If a string, it will be converted to a list since that is how the to attribute tracks it. Similar logic is used for cc and bcc.

All attributes shown below may also be specified via constructor.

key

Unique key indicating the “type” of message. An “ad-hoc” message created arbitrarily may not have/need a key; however one created via make_auto_message() will always have a key.

This key is not used for anything within the Message class logic. It is used by make_auto_message() when constructing the message, and the key is set on the final message only as a reference.

sender

Sender (From:) address for the message.

subject

Subject text for the message.

to

List of To: recipients for the message.

cc

List of Cc: recipients for the message.

bcc

List of Bcc: recipients for the message.

replyto

Optional reply-to (Reply-To:) address for the message.

txt_body

String with the text/plain body content.

html_body

String with the text/html body content.

as_string()

Returns the complete message as string. This is called from within deliver_message() to obtain the SMTP payload.