core.email

Module Contents

Classes

EmailTransport

Helper class that provides a standard way to create an ABC using

EmailTransportSendInBlue

Helper class that provides a standard way to create an ABC using

Functions

cleanOldEmailsFromLog(*args, **kwargs)

Start the QueryIter DeleteOldEmailsFromLog to remove old, successfully send emails from the queue

sendEmailDeferred(emailKey)

Callback from the Taskqueue to send the given Email

normalize_to_list(value)

Convert the given value to a list.

sendEMail(*[, tpl, stringTemplate, skel, sender, ...])

General purpose function for sending e-mail.

sendEMailToAdmins(subject, body, *args, **kwargs)

Sends an e-mail to the root users of the current app.
core.email.cleanOldEmailsFromLog(*args, **kwargs)

Start the QueryIter DeleteOldEmailsFromLog to remove old, successfully send emails from the queue

class core.email.EmailTransport

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

maxRetries = 3
abstract static deliverEmail(*, sender, dests, cc, bcc, subject, body, headers, attachments, customData, **kwargs)

The actual email delivery must be implemented here. All email-adresses can be either in the form of “mm@example.com” or “Max Musterman <mm@example.com>”. If the delivery was successful, this method should return normally, if there was an error delivering the message it must raise an exception.

Parameters:

  • sender (str) – The sender to be used on the outgoing email

  • dests (List[str]) – List of recipients

  • cc (List[str]) – : List of carbon copy-recipients

  • bcc (List[str]) – List of blind carbon copy-recipients

  • subject (str) – The subject of this email

  • body (str) – The contents of this email (may be text/plain or text/html)

  • headers (Dict[str, str]) – Custom headers to send along with this email

  • attachments (List[Dict[str, bytes]]) – List of attachments to include in this email

  • customData (Union[dict, None]) –

static validateQueueEntity(entity)

This function can be used to pre-validate the queue entity before it’s deferred into the queue. Must raise an exception if the email cannot be send (f.e. if it contains an invalid attachment) :param entity: The entity to validate

Parameters:

entity (viur.core.db.Entity) –

static transportSuccessfulCallback(entity)

This callback can be overridden by the project to execute additional tasks after an email has been successfully send. :param entity: The entity which has been send

Parameters:

entity (viur.core.db.Entity) –

core.email.sendEmailDeferred(emailKey)

Callback from the Taskqueue to send the given Email :param emailKey: Database-Key of the email we should send

Parameters:

emailKey (viur.core.db.Key) –

core.email.normalize_to_list(value)

Convert the given value to a list.

If the value parameter is callable, it will be called first to get the actual value.

Parameters:

value (Union[None, Any, List[Any], Callable[[], List]]) –

Return type:

List[Any]

core.email.sendEMail(*, tpl=None, stringTemplate=None, skel=None, sender=None, dests=None, cc=None, bcc=None, headers=None, attachments=None, context=None, **kwargs)

General purpose function for sending e-mail. This function allows for sending e-mails, also with generated content using the Jinja2 template engine. Your have to implement a method which should be called to send the prepared email finally. For this you have to allocate viur.email.transportClass in conf.

Parameters:

  • tpl (str) – The name of a template from the deploy/emails directory.

  • stringTemplate (str) – This string is interpreted as the template contents. Alternative to load from template file. :param skel: The data made available to the template. In case of a Skeleton or SkelList, its parsed the usual way; Dictionaries are passed unchanged.

  • sender (str) – The address sending this mail.

  • dests (Union[str, List[str]]) – A list of addresses to send this mail to. A bare string will be treated as a list with 1 address.

  • cc (Union[str, List[str]]) – Carbon-copy recipients. A bare string will be treated as a list with 1 address.

  • bcc (Union[str, List[str]]) – Blind carbon-copy recipients. A bare string will be treated as a list with 1 address.

  • headers (Dict[str, str]) – Specify headers for this email.

  • attachments (List[Dict[str, Any]]) –

    List of files to be sent within the mail as attachments. Each attachment must be a dictionary with these keys:

    • filename (string): Name of the file that’s attached. Always required

    • content (bytes): Content of the attachment as bytes. Required for the send in blue API.

    • mimetype (string): Mimetype of the file. Suggested parameter for other implementations (not used by SIB)

    • gcsfile (string): Link to a GCS-File to include instead of content.

    Not supported by the current SIB implementation

  • context (Union[viur.core.db.DATASTORE_BASE_TYPES, List[viur.core.db.DATASTORE_BASE_TYPES], viur.core.db.Entity]) – Arbitrary data that can be stored along the queue entry to be evaluated in transportSuccessfulCallback (useful for tracking delivery / opening events etc).

  • skel (Union[None, Dict, SkeletonInstance, List[SkeletonInstance]]) –

Return type:

bool

Warning

As emails will be queued (and not send directly) you cannot exceed 1MB in total (for all text and attachments combined)!

core.email.sendEMailToAdmins(subject, body, *args, **kwargs)

Sends an e-mail to the root users of the current app.

If conf[“viur.email.admin_recipients”] is set, these recipients will be used instead of the root users.

Parameters:

  • subject (str) – Defines the subject of the message.

  • body (str) – Defines the message body.

Return type:

bool

class core.email.EmailTransportSendInBlue

Bases: EmailTransport

Helper class that provides a standard way to create an ABC using inheritance.

maxRetries = 3
allowedExtensions
static splitAddress(address)

Splits an Name/Address Pair as “Max Musterman <mm@example.com>” into a dict {“name”: “Max Mustermann”, “email”: “mm@example.com”} :param address: Name/Address pair :return: Splitted dict

Parameters:

address (str) –

Return type:

Dict[str, str]

static deliverEmail(*, sender, dests, cc, bcc, subject, body, headers, attachments, **kwargs)

Internal function for delivering Emails using Send in Blue. This function requires the conf[“viur.email.sendInBlue.apiKey”] to be set. This function is supposed to return on success and throw an exception otherwise. If no exception is thrown, the email is considered send and will not be retried.

Parameters:

  • sender (str) –

  • dests (List[str]) –

  • cc (List[str]) –

  • bcc (List[str]) –

  • subject (str) –

  • body (str) –

  • headers (Dict[str, str]) –

  • attachments (List[Dict[str, bytes]]) –

static validateQueueEntity(entity)

For Send in Blue, we’ll validate the attachments (if any) against the list of supported file extensions

Parameters:

entity (viur.core.db.Entity) –

static check_sib_quota()

Periodically checks the remaining SendInBlue email quota.

This task does not have to be enabled. It automatically checks if the apiKey is configured.

There are three default thresholds: 1000, 500, 100 Others can be set via conf[“viur.email.sendInBlue.thresholds”]. An email will be sent for the lowest threshold that has been undercut.

Return type:

None