API Reference

Like the standard django.core.mail module, mail_templated provides two options to send an email message:

send_mail()

mail_templated.send_mail(template_name, context, from_email, recipient_list, fail_silently=False, auth_user=None, auth_password=None, connection=None, **kwargs)[source]

Easy wrapper for sending a single email message to a recipient list using django template system.

It works almost the same way as the standard send_mail() function.

The main difference is that two first arguments subject and body are replaced with template_name and context. However you still can pass subject or body as keyword arguments to provide static content if needed.

The template_name, context, from_email and recipient_list parameters are required.

Note

The set of possible parameters is not limited by the list below. Any additional parameters are passed to the constructor of EmailMultiAlternatives class.

Parameters:
  • template_name (str) – The template name that extends mail_templated/base.tpl with (optional) blocks {% subject %}, {% body %} and {% html %}.
  • context (dict) – A dictionary to be used as a context for template rendering.
  • from_email (str) – The email address for the “From:” field.
  • recipient_list (list) – The recipient email addresses. Each member of this list will see the other recipients in the “To:” field of the email message.
Keyword Arguments:
 
  • fail_silently (bool) – If it’s False, send_mail will raise an smtplib.SMTPException. See the smtplib docs for a list of possible exceptions, all of which are subclasses of smtplib.SMTPException.
  • auth_user | str – The optional username to use to authenticate to the SMTP server. If this isn’t provided, Django will use the value of the EMAIL_HOST_USER setting.
  • auth_password | str – The optional password to use to authenticate to the SMTP server. If this isn’t provided, Django will use the value of the EMAIL_HOST_PASSWORD setting.
  • connection (EmailBackend) – The optional email backend to use to send the mail. If unspecified, an instance of the default backend will be used. See the documentation on Email backends for more details.
  • subject (str) – Default message subject. Used if {% subject %} block is empty or does not exist in the specified email template.
  • body (str) – Default message body. Used if {% body %} block is empty or does not exist in the specified email template.
  • render (bool) – If True, render template and set subject, body and html properties immediately. Default is False.
Returns:

The number of successfully delivered messages (which can be 0 or 1 since it can only send one message).

Return type:

int

See also

django.core.mail.send_mail()
Documentation for the standard send_mail() function.

EmailMessage

class mail_templated.EmailMessage(template_name=None, context={}, *args, **kwargs)[source]

Extends standard EmailMultiAlternatives class with ability to use templates

See also

django.core.mail.EmailMessage
Documentation for the standard email message classes.
__init__(template_name=None, context={}, *args, **kwargs)[source]

Initialize single templated email message (which can be sent to multiple recipients).

When using with a user-specific message template for mass mailing, create new EmailMessage object for each user. Think about this class instance like about a single paper letter (you would not reuse it, right?).

The class tries to provide interface as close to the standard Django classes as possible. The main difference is that two first arguments subject and body are replaced with template_name and context. However you still can pass subject or body as keyword arguments to provide static content if needed.

All parameters are optional and can be set at any time prior to calling the render() and send() methods.

Note

The set of possible parameters is not limited by the list below. Any additional parameters are passed to the constructor of EmailMultiAlternatives class.

Parameters:
  • template_name (str) – The template name that extends mail_templated/base.tpl with (optional) blocks {% subject %}, {% body %} and {% html %}.
  • context (dict) – A dictionary to be used as a context for template rendering.
  • from_email (str) – The email address for the “From:” field.
  • recipient_list (list) – The recipient email addresses. Each member of this list will see the other recipients in the “To:” field of the email message.
Keyword Arguments:
 
  • subject (str) – Default message subject. Used if {% subject %} block is empty or does not exist in the specified email template.
  • body (str) – Default message body. Used if {% body %} block is empty or does not exist in the specified email template.
  • render (bool) – If True, render template and set subject, body and html properties immediately. Default is False.
  • clean (bool) – If True, remove any template specific properties from the message object. This may be useful if you pass render=True. Default is False.
attach(filename=None, content=None, mimetype=None)[source]

Attaches a file with the given filename and content. The filename can be omitted and the mimetype is guessed, if not provided.

If the first parameter is a MIMEBase subclass it is inserted directly into the resulting message attachments.

attach_alternative(content, mimetype)

Attach an alternative content representation.

attach_file(path, mimetype=None)[source]

Attaches a file from the filesystem.

The mimetype will be set to the DEFAULT_ATTACHMENT_MIME_TYPE if it is not specified and cannot be guessed or (PY3 only) if it suggests text/* for a binary file.

clean()[source]

Remove any template specific properties from the message object.

Useful if you want to serialize rendered message without template-specific properties. Also allows to avoid conflicts with Djrill/Mandrill and other third-party systems that may fail because of non-standard properties of the message object.

The messages should be rendered already, or you will have to setup the context and template/template_name after deserialization.

In most cases you can pass the clean parameter to the constructor or another appropriate method of this class.

load_template(template_name=None)[source]

Load a template by it’s name using the current template loaders.

Parameters:template_name (str) – The template name that extends mail_templated/base.tpl with (optional) blocks {% subject %}, {% body %} and {% html %}. If not specified then the template_name property is used.
recipients()[source]

Returns a list of all recipients of the email (includes direct addressees as well as Cc and Bcc entries).

render(context=None, clean=False)[source]

Render email with provided context

Parameters:context (dict) – A dictionary to be used as a context for template rendering. If not specified then the context property is used.
Keyword Arguments:
 clean (bool) – If True, remove any template specific properties from the message object. Default is False.
send(*args, **kwargs)[source]

Send email message, render if it is not rendered yet.

Note

Any extra arguments are passed to EmailMultiAlternatives.send().

Keyword Arguments:
 clean (bool) – If True, remove any template specific properties from the message object. Default is False.