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 (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 (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 (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 (str | list[str]) – Carbon-copy recipients. A bare string will be treated as a list with 1 address.

  • bcc (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 (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, viur.core.skeleton.SkeletonInstance, list[viur.core.skeleton.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.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.email.sendinblue_api_key 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.email.sendinblue_thresholds. An email will be sent for the lowest threshold that has been undercut.

Return type:

None