core.email ========== .. py:module:: core.email Attributes ---------- .. autoapisummary:: core.email.mailjet_dependencies core.email.mailjet_dependencies core.email.EMAIL_KINDNAME core.email.EMAIL_QUEUE core.email.AttachmentInline core.email.AttachmentViurFile core.email.AttachmentGscFile core.email.Attachment core.email.AddressPair Classes ------- .. autoapisummary:: core.email.EmailTransport core.email.EmailTransportBrevo core.email.EmailTransportSendInBlue core.email.EmailTransportMailjet core.email.EmailTransportSendgrid core.email.EmailTransportSmtp core.email.EmailTransportAppengine Functions --------- .. autoapisummary:: core.email.clean_old_emails_from_log core.email.send_email_deferred core.email.normalize_to_list core.email.send_email core.email.sendEMail core.email.send_email_to_admins core.email.sendEMailToAdmins Module Contents --------------- .. py:data:: mailjet_dependencies :value: True .. py:data:: mailjet_dependencies :value: False .. py:data:: EMAIL_KINDNAME :type: Final[str] :value: 'viur-emails' Kindname for the email-queue entities in datastore .. py:data:: EMAIL_QUEUE :type: Final[str] :value: 'viur-emails' Name of the Cloud Tasks queue .. py:data:: AttachmentInline .. py:data:: AttachmentViurFile .. py:data:: AttachmentGscFile .. py:type:: Attachment :canonical: AttachmentInline | AttachmentViurFile | AttachmentGscFile .. py:data:: AddressPair .. py:function:: clean_old_emails_from_log(*args, **kwargs) Periodically delete sent emails, which are older than :attr:`conf.email.log_retention` from datastore queue .. py:class:: EmailTransport Bases: :py:obj:`abc.ABC` Transport handler to deliver emails. Implement for a specific service and set the instance to :attr:`conf.email.transport_class` .. py:attribute:: max_retries :value: 3 maximum number of attempts to send a email. .. py:method:: deliver_email(*, sender, dests, cc, bcc, subject, body, headers, attachments, **kwargs) :abstractmethod: 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 ". 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 :return: Any value that can be stored in the datastore in the queue entity as `transportFuncResult`. .. py:method:: 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 .. py:method:: 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 .. py:method:: split_address(address) Splits a Name/Address Pair into a dict, i.e. "Max Mustermann " into {"name": "Max Mustermann", "email": "mm@example.com"} :param address: Name/Address pair :return: split dict .. py:method:: validate_attachment(attachment) Validate attachment before queueing the email .. py:method:: 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. .. py:function:: send_email_deferred(key) Task that send an email. This task is enqueued into the Cloud Tasks queue viur-email (see :attr:`EMAIL_QUEUE`) by :meth:`send_email`. Send the email by calling the implemented :meth:`EmailTransport.deliver_email` of the configures :attr:`conf.email.transport_class`. :param key: Datastore key of the email to 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:: 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. :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 email. :param dests: A list of addresses to send this email 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 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. :param context: Arbitrary data that can be stored along the queue entry to be evaluated in transport_successful_callback (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:: sendEMail(*args, **kwargs) .. py:function:: send_email_to_admins(subject, body, *args, **kwargs) Sends an email to the root users of the current app. If :attr:`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:function:: sendEMailToAdmins(*args, **kwargs) .. py:class:: EmailTransportBrevo(*, api_key, thresholds = (1000, 500, 100)) Bases: :py:obj:`EmailTransport` Send emails with `Brevo`_, formerly Sendinblue. .. _Brevo: https://www.brevo.com :param api_key: API key :param thresholds: Warning thresholds for remaining email quota. .. py:attribute:: allowed_extensions List of allowed file extensions that can be send from Brevo .. py:attribute:: api_key .. py:attribute:: thresholds :value: (1000, 500, 100) .. py:method:: deliver_email(*, sender, dests, cc, bcc, subject, body, headers, attachments, **kwargs) Internal function for delivering emails using Brevo. .. py:method:: 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 .. seealso:: :attr:`allowed_extensions` .. py:method:: check_sib_quota() :staticmethod: 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 :attr:`thresholds`. An email will be sent for the lowest threshold that has been undercut. .. seealso:: https://developers.brevo.com/reference/getaccount .. py:class:: EmailTransportSendInBlue(*, api_key, thresholds = (1000, 500, 100)) Bases: :py:obj:`EmailTransportBrevo` Send emails with `Brevo`_, formerly Sendinblue. .. _Brevo: https://www.brevo.com :param api_key: API key :param thresholds: Warning thresholds for remaining email quota. .. py:class:: EmailTransportMailjet(*, api_key, secret_key) Bases: :py:obj:`EmailTransport` Send emails with `Mailjet`_. .. _Mailjet: https://www.mailjet.com/products/email-api/ .. py:attribute:: api_key .. py:attribute:: secret_key .. py:method:: 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 ". 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 :return: Any value that can be stored in the datastore in the queue entity as `transportFuncResult`. .. py:class:: EmailTransportSendgrid(*, api_key) Bases: :py:obj:`EmailTransport` Send emails with `SendGrid`_. .. _SendGrid: https://sendgrid.com/en-us/solutions/email-api .. py:attribute:: api_key .. py:method:: 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 ". 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 :return: Any value that can be stored in the datastore in the queue entity as `transportFuncResult`. .. py:class:: EmailTransportSmtp(*, host, port = smtplib.SMTP_SSL_PORT, user, password) Bases: :py:obj:`EmailTransport` Send emails using the Simple Mail Transfer Protocol (SMTP). Needs an email server. .. py:attribute:: host .. py:attribute:: port :value: 465 .. py:attribute:: user .. py:attribute:: password .. py:attribute:: context .. py:method:: 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 ". 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 :return: Any value that can be stored in the datastore in the queue entity as `transportFuncResult`. .. py:class:: EmailTransportAppengine Bases: :py:obj:`EmailTransport` Abstraction of the Google AppEngine Mail API for email transportation. .. warning: Works only in a deployed Google Cloud environment. .. seealso:: https://cloud.google.com/appengine/docs/standard/python3/services/mail .. py:method:: 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 ". 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 :return: Any value that can be stored in the datastore in the queue entity as `transportFuncResult`.