cdh.core.mail.classes module

class cdh.core.mail.classes.BaseCustomTemplateEmail(*args, contents: str, sender: Optional[str] = None, banner: Optional[str] = None, footer: Optional[str] = None, **kwargs)[source]

Bases: BaseEmail

Email class for sending HTML emails using user supplied HTML templates

DO NOT USE THIS CLASS FOR ‘HARDCODED’ EMAILS. Use TemplateEmail instead.

BE CAREFUL WHAT YOU EXPOSE TO THE USER. This method itself is safe, as everything is run in a sandbox. However, template tags can have (nasty) side effects outside the sandbox. Also, some vars might just expose more than you thought.

Unlike TemplateEmail, this class should be extended and not be used directly. It uses class variables, which should not be set on an instance level.

Parameters

  • user_variable_defs (list of CTEVarDef) – a list of user usable variables

  • template_tag_packages (list of CTETagPackage) – a list of template tag packages to load

__init__(*args, contents: str, sender: Optional[str] = None, banner: Optional[str] = None, footer: Optional[str] = None, **kwargs)[source]
Parameters

  • to (list of str) – a list of recipients, can be plain email or formatted (“John Doe <j.doe@example.org>”)

  • subject (str) – the email subject

  • language (str) – the language used during rendering the email. Uses Django’s i18n framework

  • from_email (str or None) – the From: email address. Uses settings.EMAIL_FROM if omitted

  • headers (dict or None) – any additional SMTP headers to be used

  • attachments (list of MimeBase or Tuple) – a list of email attachments to be sent along.

  • cc (list of str or None) – a list of recipients to put as CC:

  • bcc (list of str or None) – a list of recipients to put ad BCC:

  • reply_to (list of str or None) – an email to be set as REPLY_TO: (not set if left empty)

  • context (dict) – any template context needed for both the templates

  • html_context (dict) – any template context needed by the HTML template, will override values in context if both have them

  • plain_context (dict) – any template context needed by the plain template, will override values in context if both have them.

  • theme_settings (dict) – a dict of overrides for the styling of the HTML email does not need to contain all values, only the ones you want to override.

  • html_fallback_template (str) – the base template for HTML emails used for generating an HTML version of a plain text email

  • plain_fallback_template (str) – the base template for plain text emails used for generating a plain text version of an HTML email

classmethod help_text() → str[source]

A (marked_safe) string describing which vars and tags can be used in this template. Intended to be used as a formfield help_text

render_preview()[source]

Returns a rendered HTML document as would be sent as the HTML content.

Uses the variable defaults as defined if nothing was supplied through the context param.

template_tag_packages: List[CTETagPackage] = []
user_variable_defs: List[CTEVarDef] = []
class cdh.core.mail.classes.BaseEmail(to: Union[str, List[str]], subject: str, language: str = 'nl', from_email: Optional[str] = None, headers: Optional[Dict[str, str]] = None, attachments: Optional[List[Union[MIMEBase, Tuple[str, str, str]]]] = None, cc: Optional[List[str]] = None, bcc: Optional[List[str]] = None, reply_to: Optional[str] = None, context: Optional[Dict] = None, plain_context: Optional[Dict] = None, html_context: Optional[Dict] = None, theme_settings: Optional[Dict] = None, html_fallback_template: str = 'cdh.core/mail_template.html', plain_fallback_template: str = 'cdh.core/plain_mail_fallback.txt')[source]

Bases: ABC

Base class for all email classes.

These params mostly correspond to Django’s Message, so read those docs for more details

About render/template contexts: When not supplied with both an HTML and a plain text email, the missing one will be automatically generated. However, it will not use render contexts of the other variant. For example, if you leave the plain text version to be automatically generated, the plain text version will use plain_context and not html_context.

About theme settings: The HTML template has some styling configuration to tweak the appearance of the email. You can specify any changes on this class, but in most cases it’s better to apply app-wide changes using the CDH_EMAIL_THEME_SETTINGS config value in settings.py

About fallback templates: These templates are used when generating a missing variant. For example, if you supply a plain text template only, html_fallback_template will be used as the base template for the generated HTML version. When your app uses a custom base template, it’s best to set this template globally using the settings.py settings. It’s provided on the class only if your app uses multiple base templates.

HTML base templates MUST have a block called ‘content’ and are encouraged to have ‘sender’, ‘banner’ and ‘footer’ blocks. Plain base templates use template vars instead of blocks, but the same requirements apply on those vars as well.

__init__(to: Union[str, List[str]], subject: str, language: str = 'nl', from_email: Optional[str] = None, headers: Optional[Dict[str, str]] = None, attachments: Optional[List[Union[MIMEBase, Tuple[str, str, str]]]] = None, cc: Optional[List[str]] = None, bcc: Optional[List[str]] = None, reply_to: Optional[str] = None, context: Optional[Dict] = None, plain_context: Optional[Dict] = None, html_context: Optional[Dict] = None, theme_settings: Optional[Dict] = None, html_fallback_template: str = 'cdh.core/mail_template.html', plain_fallback_template: str = 'cdh.core/plain_mail_fallback.txt')[source]
Parameters

  • to (list of str) – a list of recipients, can be plain email or formatted (“John Doe <j.doe@example.org>”)

  • subject (str) – the email subject

  • language (str) – the language used during rendering the email. Uses Django’s i18n framework

  • from_email (str or None) – the From: email address. Uses settings.EMAIL_FROM if omitted

  • headers (dict or None) – any additional SMTP headers to be used

  • attachments (list of MimeBase or Tuple) – a list of email attachments to be sent along.

  • cc (list of str or None) – a list of recipients to put as CC:

  • bcc (list of str or None) – a list of recipients to put ad BCC:

  • reply_to (list of str or None) – an email to be set as REPLY_TO: (not set if left empty)

  • context (dict) – any template context needed for both the templates

  • html_context (dict) – any template context needed by the HTML template, will override values in context if both have them

  • plain_context (dict) – any template context needed by the plain template, will override values in context if both have them.

  • theme_settings (dict) – a dict of overrides for the styling of the HTML email does not need to contain all values, only the ones you want to override.

  • html_fallback_template (str) – the base template for HTML emails used for generating an HTML version of a plain text email

  • plain_fallback_template (str) – the base template for plain text emails used for generating a plain text version of an HTML email

apply_theme_settings(theme_settings: dict) → None[source]

Applies theme settings

Parameters

theme_settings (dict) – a dict of overrides for the styling of the HTML email does not need to contain all values, only the ones you want to override.

attach(filename, content=None, mimetype=None) → None[source]

Attach a new attachment to this email

Parameters

  • filename (str or MIMEBase) – either a string of the filename, or a MIMEBase object representing the entire file

  • content (str or None) – If filename is a string, the contents of the file. Ignored otherwise

  • mimetype (str or None) – If filename is a string, the mimetype of the file. Ignored otherwise

send(connection=None, fail_silently=True) → int[source]

Sends the email

If sending multiple emails in a row, it’s recommended to create a connection yourself and use them on all emails for performance reasons.

Parameters

  • connection – a Django email backend to send the mail with. If omitted, the default backend will be used

  • fail_silently (bool) – whether errors during sending should be suppressed

Returns

number of emails sent

Return type

int

class cdh.core.mail.classes.CTETagPackage(package: str, tags: List[Tuple[str, Optional[list], Optional[str]]])[source]

Bases: object

Configuration class for loading template tag packages

This class serves two roles: - Providing information for loading template tag packages in the template - Provide information for help text generation

All packages need to be importable by the Django rendering engine

__init__(package: str, tags: List[Tuple[str, Optional[list], Optional[str]]])[source]
Parameters

  • package (str) – the name of the package to load

  • tags – a list of 3-tuples; The tuple should contain: - The name of the usable tag inside the package - A list of arguments that tag accepts - A help string explaining what the tag does

class cdh.core.mail.classes.CTEVarDef(name: str, help_text: str = None, preview_value=None)[source]

Bases: object

Descriptor class for user-usable variables in a Custom Template Email

This class serves two roles: - Provide information for help text generation - Provide a default value when rendering the preview

__init__(name: str, help_text: str = None, preview_value=None)[source]
Parameters

  • name (str) – The variable name

  • help_text (str or None) – a short description of what this var will output (optional)

  • preview_value – a placeholder value that will be inserted when rendering the preview (optional)

class cdh.core.mail.classes.TemplateEmail(*args, html_template: Optional[str] = None, plain_template: Optional[str] = None, **kwargs)[source]

Bases: BaseEmail

Regular Django template files based emails

One of the two templates is required. If one is missing, it will be generated from the other.

__init__(*args, html_template: Optional[str] = None, plain_template: Optional[str] = None, **kwargs)[source]
Parameters

  • html_template (str) – the HTML template to send

  • plain_template (str) – the plain text template to send

  • to (list of str) – a list of recipients, can be plain email or formatted (“John Doe <j.doe@example.org>”)

  • subject (str) – the email subject

  • language (str) – the language used during rendering the email. Uses Django’s i18n framework

  • from_email (str or None) – the From: email address. Uses settings.EMAIL_FROM if omitted

  • headers (dict or None) – any additional SMTP headers to be used

  • attachments (list of MimeBase or Tuple) – a list of email attachments to be sent along.

  • cc (list of str or None) – a list of recipients to put as CC:

  • bcc (list of str or None) – a list of recipients to put ad BCC:

  • reply_to (list of str or None) – an email to be set as REPLY_TO: (not set if left empty)

  • context (dict) – any template context needed for both the templates

  • html_context (dict) – any template context needed by the HTML template, will override values in context if both have them

  • plain_context (dict) – any template context needed by the plain template, will override values in context if both have them.

  • theme_settings (dict) – a dict of overrides for the styling of the HTML email does not need to contain all values, only the ones you want to override.

  • html_fallback_template (str) – the base template for HTML emails used for generating an HTML version of a plain text email

  • plain_fallback_template (str) – the base template for plain text emails used for generating a plain text version of an HTML email