API Reference¶
Like the standard django.core.mail
module, mail_templated
provides two options to send an email message:
- send_mail() function for simple usage,
- EmailMessage class for advanced usage.
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
andbody
are replaced withtemplate_name
andcontext
. However you still can pass subject or body as keyword arguments to provide static content if needed.The
template_name
,context
,from_email
andrecipient_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 thesmtplib
docs for a list of possible exceptions, all of which are subclasses ofsmtplib.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 setsubject
,body
andhtml
properties immediately. Default isFalse
.
Returns: The number of successfully delivered messages (which can be 0 or 1 since it can only send one message).
Return type: See also
django.core.mail.send_mail()
- Documentation for the standard
send_mail()
function.
- template_name (str) – The template name that extends
mail_templated/base.tpl with (optional) blocks
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
andbody
are replaced withtemplate_name
andcontext
. 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()
andsend()
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 setsubject
,body
andhtml
properties immediately. Default isFalse
. - clean (bool) – If
True
, remove any template specific properties from the message object. This may be useful if you passrender=True
. Default isFalse
.
- template_name (str) – The template name that extends
mail_templated/base.tpl with (optional) blocks
-
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
andtemplate
/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 thetemplate_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 isFalse
.
-
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 isFalse
.