:py:mod:`core.email` ==================== .. py:module:: core.email Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: core.email.EmailTransport core.email.EmailTransportSendInBlue core.email.EmailTransportMailjet core.email.EmailTransportAppengine Functions ~~~~~~~~~ .. autoapisummary:: core.email.cleanOldEmailsFromLog core.email.sendEmailDeferred core.email.normalize_to_list core.email.sendEMail core.email.sendEMailToAdmins Attributes ~~~~~~~~~~ .. autoapisummary:: core.email.mailjet_dependencies core.email.mailjet_dependencies core.email.EMAIL_KINDNAME core.email.AttachmentInline core.email.AttachmentViurFile core.email.AttachmentGscFile core.email.Attachment .. py:data:: mailjet_dependencies :value: True .. py:data:: mailjet_dependencies :value: False .. py:data:: EMAIL_KINDNAME :value: 'viur-emails' .. py:data:: AttachmentInline .. py:data:: AttachmentViurFile .. py:data:: AttachmentGscFile .. py:data:: Attachment :type: TypeAlias .. py:function:: cleanOldEmailsFromLog(*args, **kwargs) Start the QueryIter DeleteOldEmailsFromLog to remove old, successfully send emails from the queue .. py:class:: EmailTransport Bases: :py:obj:`abc.ABC` Helper class that provides a standard way to create an ABC using inheritance. .. py:attribute:: maxRetries :value: 3 .. py:method:: deliverEmail(*, sender, dests, cc, bcc, subject, body, headers, attachments, customData, **kwargs) :staticmethod: :abstractmethod: The actual email delivery must be implemented here. All email-adresses can be either in the form of "mm@example.com" or "Max Musterman ". If the delivery was successful, this method should return normally, if there was an error delivering the message it *must* raise an exception. :param sender: The sender to be used on the outgoing email :param dests: List of recipients :param cc: : List of carbon copy-recipients :param bcc: List of blind carbon copy-recipients :param subject: The subject of this email :param body: The contents of this email (may be text/plain or text/html) :param headers: Custom headers to send along with this email :param attachments: List of attachments to include in this email :param customData: .. py:method:: validateQueueEntity(entity) :staticmethod: 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 .. py:method:: transportSuccessfulCallback(entity) :staticmethod: 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 .. py:method:: splitAddress(address) :staticmethod: Splits a Name/Address Pair into a dict, i.e. "Max Musterman " into {"name": "Max Mustermann", "email": "mm@example.com"} :param address: Name/Address pair :return: split dict .. py:method:: validate_attachment(attachment) :staticmethod: Validate attachment before queueing the email .. py:method:: fetch_attachment(attachment) :staticmethod: Fetch attachment (if necessary) in sendEmailDeferred deferred task This allows sending emails with large attachments, and prevents the queue entry from exceeding the maximum datastore Entity size. .. py:function:: sendEmailDeferred(key) Callback from the Taskqueue to send the given Email :param emailKey: Database-Key of the email we should send .. py:function:: 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. .. py:function:: 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.transport_class* in conf. :param tpl: The name of a template from the deploy/emails directory. :param stringTemplate: 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. :param sender: The address sending this mail. :param dests: A list of addresses to send this mail to. A bare string will be treated as a list with 1 address. :param cc: Carbon-copy recipients. A bare string will be treated as a list with 1 address. :param bcc: Blind carbon-copy recipients. A bare string will be treated as a list with 1 address. :param headers: Specify headers for this email. :param attachments: 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. - 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. :param context: Arbitrary data that can be stored along the queue entry to be evaluated in transportSuccessfulCallback (useful for tracking delivery / opening events etc). .. warning:: As emails will be queued (and not send directly) you cannot exceed 1MB in total (for all text and attachments combined)! .. py:function:: 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. :param subject: Defines the subject of the message. :param body: Defines the message body. .. py:class:: EmailTransportSendInBlue Bases: :py:obj:`EmailTransport` Helper class that provides a standard way to create an ABC using inheritance. .. py:attribute:: maxRetries :value: 3 .. py:attribute:: allowedExtensions .. py:method:: deliverEmail(*, sender, dests, cc, bcc, subject, body, headers, attachments, **kwargs) :staticmethod: 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. .. py:method:: validateQueueEntity(entity) :staticmethod: For Send in Blue, we'll validate the attachments (if any) against the list of supported file extensions .. py:method:: check_sib_quota() :staticmethod: 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. .. py:class:: EmailTransportMailjet Bases: :py:obj:`EmailTransport` Helper class that provides a standard way to create an ABC using inheritance. .. py:method:: deliverEmail(*, sender, dests, cc, bcc, subject, body, headers, attachments, **kwargs) :staticmethod: The actual email delivery must be implemented here. All email-adresses can be either in the form of "mm@example.com" or "Max Musterman ". If the delivery was successful, this method should return normally, if there was an error delivering the message it *must* raise an exception. :param sender: The sender to be used on the outgoing email :param dests: List of recipients :param cc: : List of carbon copy-recipients :param bcc: List of blind carbon copy-recipients :param subject: The subject of this email :param body: The contents of this email (may be text/plain or text/html) :param headers: Custom headers to send along with this email :param attachments: List of attachments to include in this email :param customData: .. py:class:: EmailTransportAppengine Bases: :py:obj:`EmailTransport` Abstraction of the Google AppEngine Mail API for email transportation. .. py:method:: deliverEmail(*, sender, dests, cc, bcc, subject, body, headers, attachments, **kwargs) :staticmethod: The actual email delivery must be implemented here. All email-adresses can be either in the form of "mm@example.com" or "Max Musterman ". If the delivery was successful, this method should return normally, if there was an error delivering the message it *must* raise an exception. :param sender: The sender to be used on the outgoing email :param dests: List of recipients :param cc: : List of carbon copy-recipients :param bcc: List of blind carbon copy-recipients :param subject: The subject of this email :param body: The contents of this email (may be text/plain or text/html) :param headers: Custom headers to send along with this email :param attachments: List of attachments to include in this email :param customData: