core.email

Module Contents

Classes

EmailTransport	Transport handler to deliver emails.
EmailTransportBrevo	Send emails with Brevo, formerly Sendinblue.
EmailTransportSendInBlue	Send emails with Brevo, formerly Sendinblue.
EmailTransportMailjet	Send emails with Mailjet.
EmailTransportSendgrid	Send emails with SendGrid.
EmailTransportSmtp	Send emails using the Simple Mail Transfer Protocol (SMTP).
EmailTransportAppengine	Abstraction of the Google AppEngine Mail API for email transportation.

Functions

clean_old_emails_from_log(*args, **kwargs)	Periodically delete sent emails, which are older than conf.email.log_retention from datastore queue
send_email_deferred(key)	Task that send an email.
normalize_to_list(value)	Convert the given value to a list.
send_email(*[, tpl, stringTemplate, skel, sender, ...])	General purpose function for sending email.
sendEMail(*args, **kwargs)
send_email_to_admins(subject, body, *args, **kwargs)	Sends an email to the root users of the current app.
sendEMailToAdmins(*args, **kwargs)

Attributes

mailjet_dependencies
mailjet_dependencies
EMAIL_KINDNAME	Kindname for the email-queue entities in datastore
EMAIL_QUEUE	Name of the Cloud Tasks queue
AttachmentInline
AttachmentViurFile
AttachmentGscFile
Attachment
AddressPair

core.email.mailjet_dependencies = True

core.email.mailjet_dependencies = False

core.email.EMAIL_KINDNAME: Final[str] = 'viur-emails'

Kindname for the email-queue entities in datastore

core.email.EMAIL_QUEUE: Final[str] = 'viur-emails'

Name of the Cloud Tasks queue

core.email.AttachmentInline

core.email.AttachmentViurFile

core.email.AttachmentGscFile

core.email.Attachment: TypeAlias

core.email.AddressPair

core.email.clean_old_emails_from_log(*args, **kwargs)

Periodically delete sent emails, which are older than conf.email.log_retention from datastore queue

class core.email.EmailTransport

Bases: abc.ABC

Transport handler to deliver emails.

Implement for a specific service and set the instance to conf.email.transport_class

max_retries = 3

maximum number of attempts to send a email.

abstract deliver_email(*, sender, dests, cc, bcc, subject, body, headers, attachments, **kwargs)

This method handles the actual sending of emails.

It must be implemented by each type. All email-addresses can be either in the form of “mm@example.com” or “Max Mustermann <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[Attachment]) – List of attachments to include in this email

• kwargs (Any) –

Returns:

Any value that can be stored in the datastore in the queue entity as transportFuncResult.

Return type:

Any

validate_queue_entity(entity)

This function can be implemented 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) –

Return type:

None

transport_successful_callback(entity)

This callback can be implemented to execute additional tasks after an email has been successfully send. :param entity: The entity which has been sent

Parameters:

entity (viur.core.db.Entity) –

split_address(address)

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

Parameters:

address (str) –

Return type:

AddressPair

validate_attachment(attachment)

Validate attachment before queueing the email

Parameters:

attachment (Attachment) –

Return type:

None

fetch_attachment(attachment)

Fetch attachment (if necessary) in send_email_deferred deferred task

This allows sending emails with large attachments, and prevents the queue entry from exceeding the maximum datastore Entity size.

Parameters:

attachment (Attachment) –

Return type:

AttachmentInline

core.email.send_email_deferred(key)

Task that send an email.

This task is enqueued into the Cloud Tasks queue viur-email (see EMAIL_QUEUE) by send_email(). Send the email by calling the implemented EmailTransport.deliver_email() of the configures conf.email.transport_class.

Parameters:

key (viur.core.db.Key) – Datastore key of the email to send

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.send_email(*, 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 email. This function allows for sending emails, 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.transport_class 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 email.

• dests (str | list[str]) – A list of addresses to send this email 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[Attachment]) –

  List of files to be sent within the email 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.

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

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

  • file_key (string): Key of a FileSkeleton to include instead of content.

• 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 transport_successful_callback (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.sendEMail(*args, **kwargs)

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

Sends an email 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

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

class core.email.EmailTransportBrevo(*, api_key, thresholds=(1000, 500, 100))

Bases: EmailTransport

Send emails with Brevo, formerly Sendinblue.

Parameters:

• api_key (str) – API key

• thresholds (tuple[int] | list[int]) – Warning thresholds for remaining email quota.

allowed_extensions

List of allowed file extensions that can be send from Brevo

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

Internal function for delivering emails using Brevo.

Parameters:

• sender (str) –

• dests (list[str]) –

• cc (list[str]) –

• bcc (list[str]) –

• subject (str) –

• body (str) –

• headers (dict[str, str]) –

• attachments (list[Attachment]) –

• kwargs (Any) –

Return type:

str

validate_queue_entity(entity)

Validate the attachments (if any) against the list of supported file extensions by Brevo.

Raises:

ValueError – If the attachment was not allowed

Parameters:

entity (viur.core.db.Entity) –

Return type:

None

See also

allowed_extensions

static check_sib_quota()

Periodically checks the remaining Brevo 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 thresholds. An email will be sent for the lowest threshold that has been undercut.

See also

https://developers.brevo.com/reference/getaccount

Return type:

None

class core.email.EmailTransportSendInBlue(*, api_key, thresholds=(1000, 500, 100))

Bases: EmailTransportBrevo

Send emails with Brevo, formerly Sendinblue.

Parameters:

• api_key (str) – API key

• thresholds (tuple[int] | list[int]) – Warning thresholds for remaining email quota.

class core.email.EmailTransportMailjet(*, api_key, secret_key)

Bases: EmailTransport

Send emails with Mailjet.

Parameters:

• api_key (str) –

• secret_key (str) –

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

This method handles the actual sending of emails.

It must be implemented by each type. All email-addresses can be either in the form of “mm@example.com” or “Max Mustermann <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[Attachment]) – List of attachments to include in this email

• kwargs (Any) –

Returns:

Any value that can be stored in the datastore in the queue entity as transportFuncResult.

Return type:

str

class core.email.EmailTransportSendgrid(*, api_key)

Bases: EmailTransport

Send emails with SendGrid.

Parameters:

api_key (str) –

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

This method handles the actual sending of emails.

It must be implemented by each type. All email-addresses can be either in the form of “mm@example.com” or “Max Mustermann <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[Attachment]) – List of attachments to include in this email

• kwargs (Any) –

Returns:

Any value that can be stored in the datastore in the queue entity as transportFuncResult.

Return type:

dict[str, str]

class core.email.EmailTransportSmtp(*, host, port=smtplib.SMTP_SSL_PORT, user, password)

Bases: EmailTransport

Send emails using the Simple Mail Transfer Protocol (SMTP).

Needs an email server.

Parameters:

• host (str) –

• port (int) –

• user (str) –

• password (str) –

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

This method handles the actual sending of emails.

It must be implemented by each type. All email-addresses can be either in the form of “mm@example.com” or “Max Mustermann <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[Attachment]) – List of attachments to include in this email

• kwargs (Any) –

Returns:

Any value that can be stored in the datastore in the queue entity as transportFuncResult.

Return type:

dict[str, tuple[int, bytes]]

class core.email.EmailTransportAppengine

Bases: EmailTransport

Abstraction of the Google AppEngine Mail API for email transportation.

See also

https://cloud.google.com/appengine/docs/standard/python3/services/mail

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

This method handles the actual sending of emails.

It must be implemented by each type. All email-addresses can be either in the form of “mm@example.com” or “Max Mustermann <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[Attachment]) – List of attachments to include in this email

• kwargs (Any) –

Returns:

Any value that can be stored in the datastore in the queue entity as transportFuncResult.

Return type:

None