API Reference

nti.mailer

nti.mailer.interfaces

Mailing interfaces.

This package is based upon both pyramid_mailer and repoze.sendmail, but the relevant parts are re-exported from this package.

interface nti.mailer.interfaces.IMailDelivery

Send an email to a group of people.

transaction_manager

The transaction manager to use.

send(fromaddr, toaddrs, message)

Send an email message.

fromaddr is the sender address (byte string),

toaddrs is a sequence of recipient addresses (byte strings).

message is a Message object from the stdlib email.message module. If it does not contain a Message-Id header, one will be generated and added automatically.

Returns the message ID.

Messages are actually sent during transaction commit.

interface nti.mailer.interfaces.IPrincipalEmailValidation

A principal adapter that validates the given principal has a valid email. Currently, we only refuse to send an email if the given principal is adaptable to IPrincipalEmailValidation and this func returns False.

This is useful to filter out bounced emails or users without an email.

is_valid_email()

Returns a bool whether or not the given principal has a valid email.

interface nti.mailer.interfaces.IEmailAddressable

Something containing an email address. Commonly, when the object containing the email address represents a “user” of the system, it should also be adaptable to zope.security.interfaces.IPrincipal.

See EmailAddressablePrincipal for a simple serialization-safe example.

email

The email address to send to

class nti.mailer.interfaces.EmailAddressablePrincipal(context)

Bases: object

An implementation of both IEmailAddressable and IPrincipal that combines both interfaces from something (a context) that is adaptable to both. Use this when the weight of the context is undesirable, such as during serialization (pickling), or when concurrency is a factor.

This object copies the attributes from both interfaces into itself at construction time.

interface nti.mailer.interfaces.ITemplatedMailer

An object, typically registered as a utility, that can handle putting together an email (having both text and HTML parts) by rendering templates.

queue_simple_html_text_email(base_template, subject='', request=None, recipients=(), bcc=(), template_args=None, attachments=(), package=None, text_template_extension='.txt', message_factory=None, context=None)

Transactionally queues an email for sending. The email has both a plain text and an HTML version.

Parameters:

• recipients – A sequence of RFC822 email addresses as strings, or objects that can be adapted to an IEmailAddressable object. If no recipients are given, this does nothing. If any recipients are not strings, then if they cannot be adapted to IEmailAddressable or if the email attribute of the adapted object is false (none, empty) they will silently be dropped from the list. Objects that are IEmailAddressable should also (optionally) be able to become zope.security.interfaces.IPrincipal by adaptation; this may permit us to construct a better (e.g., VERP) message.

• bcc – As for recipients.

• text_template_extension – The filename extension for the plain text template. Valid values are “.txt” for Chameleon templates (this is the default and preferred version) and “.mak” for Mako templates. Note that if you use Mako, the usual context argument is renamed to nti_context, as context is a reserved word in Mako (this may change in the future).

• package – If given, and the template is not an absolute asset spec, then the template will be interpreted relative to this package (and its templates/ subdirectory if no subdirectory is specified). If no package is given, the package of the caller of this function is used.

• message_factory – A callable, called with the same arguments passed to this function (minus this param) to create a pyramid_mailer.message.Message by rendering the pair of templates to create a text and html part. Defaults to create_simple_html_text_email(). This argument is deprecated; if you need it, please file an issue explaining your use-case.

Returns:

The pyramid_mailer.message.Message we sent, if we sent one, otherwise None.

Changed in version 0.0.1: Now, if the subject is a zope.i18nmessageid.Message, it will be translated. Note that this only works if you do not override the message_factory argument.

Changed in version 0.0.1: Added the context argument. If this argument is not supplied, the value of request.context will be used. As a last resort, template_args['context'] will be used. (If both *context* or ``request.context and a template argument value are given, they should all be the same object.)

create_simple_html_text_email(base_template, subject='', request=None, recipients=(), template_args=None, attachments=(), package=None, bcc=(), text_template_extension='.txt', context=None)

The same arguments and return types as queue_simple_html_text_email(), but without the actual transactional delivery.

do_html_text_templates_exist(base_template, text_template_extension='.txt', package=None)

A preflight method for checking if templates exist. Returns a True value if they do.

interface nti.mailer.interfaces.IVERP

Amazon SES now supports labels for sending emails, making it possible to do VERP, meaning we can directly identify the account we sent to (or even type of email) in case of a bounce. This requires using ‘labels’ and modifying the sending address: foo+label@domain.com. Note that SES makes no mention of the Sender header, instead putting the labels directly in the From line (which is what, for example, Facebook does) or in the Return-Path line (which is what trello does). However, SES only deals with the Return-Path header if you use its API, not if you use SMTP

realname_from_recipients(fromaddr, recipients, request=None)

This function takes a given From address and manipulates it to include a default realname, usually based on the current site and possibly the recipient list.

Despite being located in the VERP module, this function does not actually do any signing.

Returns:

The fromaddr, guaranteed to be in “Realname <to@example.com>” format.

verp_from_recipients(fromaddr, recipients, request=None)

This function takes a given from address and manipulates it to include VERP information that identifies the accounts of the recipients. For this to work, the recipients must initially be passed as things that can be adapted to IEmailAddressable objects; for those objects that can be adapted, then if they can be adapted to IPrincipal, we include the principal ID.

In addition, if the fromaddr does not include a realname, adds a default.

Note

We take the request as an argument because at some point we may want to include some notion of the sending site, although it’s probably better to use separate SES/SNS queues if possible.

Parameters:

fromaddr – The initial from address, without any labels, possibly including a realname portion.

Returns:

The fromaddr, manipulated to include a VERP label, if possible, identifying the principals related to the recipients and/or request.

principal_ids_from_verp(fromaddr, request=None)

Decode the VERP information as encoded in verp_from_recipients(), returning a sequence of positively-identified principal IDs for the current environment, if any.

interface nti.mailer.interfaces.IMailerPolicy

Mailer policy utility

DEFAULT_EMAIL_SENDER

An optional email sender

An email address used to send emails to userssuch as account creation, both on behalf of thisobject as well as from other places. Optional.

Implementation:

zope.schema.TextLine

Read Only:

False

Required:

False

Default Value:

None

Allowed Type:

str

get_default_sender()

Returns a default sender to be used when no fromaddr is provided.

get_signer_secret()

Returns a signer secret, used for verp.

interface nti.mailer.interfaces.IMailerTemplateArgsUtility

A utility that can supplement mail template args.

get_template_args()

Returns a (possibly empty) dict of supplemental template args.

Implementation Details

Default mailer

Utility functions having to do with sending emails.

This module provides the nti.mailer.interfaces.ITemplatedMailer interface.

nti.mailer._default_template_mailer.do_html_text_templates_exist(base_template, text_template_extension='.txt', package=None, _level=3)

A preflight method for checking if templates exist. Returns a True value if they do.

nti.mailer._default_template_mailer.create_simple_html_text_email(base_template, subject='', request=None, recipients=(), template_args=None, reply_to=None, attachments=(), package=None, cc=(), bcc=(), text_template_extension='.txt', context=<object object>, _level=3)

Create a pyramid_mailer.message.Message by rendering the pair of templates to create a text and html part.

Parameters:

• text_template_extension (str) – The filename extension for the plain text template. Valid values are “.txt” for Chameleon templates (this is the default and preferred version) and “.mak” for Mako templates. Note that if you use Mako, the usual context argument is renamed to nti_context, as context is a reserved word in Mako.

• package – If given, and the template is not an absolute asset spec, then the template will be interpreted relative to this package (and its templates/ subdirectory if no subdirectory is specified). If no package is given, the package of the caller of this function is used.

Changed in version 0.0.1: Now, if the subject is a zope.i18nmessageid.Message, it will be translated.

Changed in version 0.0.1: Added the context argument. If this argument is not supplied, the value of request.context will be used. As a last resort, template_args['context'] will be used. (If both *context* or ``request.context and a template argument value are given, they should be the same object.)

nti.mailer._default_template_mailer.queue_simple_html_text_email(*args, **kwargs)

Transactionally queues an email for sending. The email has both a plain text and an HTML version.

Parameters:

text_template_extension – The filename extension for the plain text template. Valid values are “.txt” for Chameleon templates (this is the default and preferred version) and “.mak” for Mako templates. Note that if you use Mako, the usual context argument is renamed to nti_context, as context is a reserved word in Mako.

Returns:

The pyramid_mailer.message.Message we sent.

Queue

See Console Programs for Mail Processing for information on how these are intended to be used.

Processors for repoze.sendmail, intended as a drop-in replacement for the qp command line, using Amazon SES.

class nti.mailer.queue.SESMailer(region='us-east-1')

Bases: object

This object does not handle throttling or quata actions; see also nti.app.bulkemail.process.

class nti.mailer.queue.ConsoleApp(argv=None)

Bases: ConsoleApp

class nti.mailer.queue.LoopingMailerProcess(mailer_factory, queue_path, sleep_seconds=120)

Bases: _AbstractMailerProcess

A mailer processor that dumps the queue on a provided interval.

class nti.mailer.queue.MailerWatcher(*args, **kwargs)

Bases: _AbstractMailerProcess

A Mailer processor that watches for changes in the mail directory using gevent stat watchers.

nti.mailer.queue.MailerProcess

Backwards compatibility alias

Deprecated since version 0.0.1: Use LoopingMailerProcess

VERP

Implementation of the nti.mailer.interfaces.IVERP protocol.