mirror of
https://github.com/pacnpal/django-anymail.git
synced 2025-12-20 11:51:05 -05:00
cc56b96efa
* Add some context to exceptions on unserializable values (addresses #89). * Document need to format merge data (into something JSON-serializable). * Add RemovedInDjrill2 DeprecationWarning. * Deprecate blanket date/datetime serialization.
137 lines
4.7 KiB
ReStructuredText
137 lines
4.7 KiB
ReStructuredText
Sending Template Mail
|
|
=====================
|
|
|
|
.. _mandrill-templates:
|
|
|
|
Mandrill Templates
|
|
------------------
|
|
|
|
.. versionadded:: 0.3
|
|
Mandrill template support
|
|
|
|
To use a *Mandrill* (MailChimp) template stored in your Mandrill account,
|
|
set a :attr:`template_name` and (optionally) :attr:`template_content`
|
|
on your :class:`~django.core.mail.EmailMessage` object::
|
|
|
|
from django.core.mail import EmailMessage
|
|
|
|
msg = EmailMessage(subject="Shipped!", from_email="store@example.com",
|
|
to=["customer@example.com", "accounting@example.com"])
|
|
msg.template_name = "SHIPPING_NOTICE" # A Mandrill template name
|
|
msg.template_content = { # Content blocks to fill in
|
|
'TRACKING_BLOCK': "<a href='.../*|TRACKINGNO|*'>track it</a>"
|
|
}
|
|
msg.global_merge_vars = { # Merge tags in your template
|
|
'ORDERNO': "12345", 'TRACKINGNO': "1Z987"
|
|
}
|
|
msg.merge_vars = { # Per-recipient merge tags
|
|
'accounting@example.com': {'NAME': "Pat"},
|
|
'customer@example.com': {'NAME': "Kim"}
|
|
}
|
|
msg.send()
|
|
|
|
If :attr:`template_name` is set, Djrill will use Mandrill's
|
|
`messages/send-template API <https://mandrillapp.com/api/docs/messages.html#method=send-template>`_,
|
|
and will ignore any `body` text set on the `EmailMessage`.
|
|
|
|
All of Djrill's other :ref:`Mandrill-specific options <mandrill-send-support>`
|
|
can be used with templates.
|
|
|
|
|
|
.. _formatting-merge-data:
|
|
|
|
Formatting Merge Data
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you're using dates, datetimes, Decimals, or anything other than strings and integers,
|
|
you'll need to format them into strings for use as merge data::
|
|
|
|
product = Product.objects.get(123) # A Django model
|
|
total_cost = Decimal('19.99')
|
|
ship_date = date(2015, 11, 18)
|
|
|
|
# Won't work -- you'll get "not JSON serializable" exceptions:
|
|
msg.global_merge_vars = {
|
|
'PRODUCT': product,
|
|
'TOTAL_COST': total_cost,
|
|
'SHIP_DATE': ship_date
|
|
}
|
|
|
|
# Do something this instead:
|
|
msg.global_merge_vars = {
|
|
'PRODUCT': product.name, # assuming name is a CharField
|
|
'TOTAL_COST': "%.2f" % total_cost,
|
|
'SHIP_DATE': ship_date.strftime('%B %d, %Y') # US-style "March 15, 2015"
|
|
}
|
|
|
|
These are just examples. You'll need to determine the best way to format
|
|
your merge data as strings.
|
|
|
|
Although floats are allowed in merge vars, you'll generally want to format them
|
|
into strings yourself to avoid surprises with floating-point precision.
|
|
|
|
Technically, Djrill will accept anything serializable by the Python json package --
|
|
which means advanced template users can include dicts and lists as merge vars
|
|
(for templates designed to handle objects and arrays).
|
|
See the Python :class:`json.JSONEncoder` docs for a list of allowable types.
|
|
|
|
|
|
How To Use Default Mandrill Subject and From fields
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To use default Mandrill "subject" or "from" field from your template definition
|
|
(overriding your EmailMessage and Django defaults), set the following attrs:
|
|
:attr:`use_template_subject` and/or :attr:`use_template_from` on
|
|
your :class:`~django.core.mail.EmailMessage` object::
|
|
|
|
msg.use_template_subject = True
|
|
msg.use_template_from = True
|
|
msg.send()
|
|
|
|
.. attribute:: use_template_subject
|
|
|
|
If `True`, Djrill will omit the subject, and Mandrill will
|
|
use the default subject from the template.
|
|
|
|
.. versionadded:: 1.1
|
|
|
|
.. attribute:: use_template_from
|
|
|
|
If `True`, Djrill will omit the "from" field, and Mandrill will
|
|
use the default "from" from the template.
|
|
|
|
.. versionadded:: 1.1
|
|
|
|
|
|
|
|
.. _django-templates:
|
|
|
|
Django Templates
|
|
----------------
|
|
|
|
To compose email using *Django* templates, you can use Django's
|
|
:func:`~django.template.loaders.django.template.loader.render_to_string`
|
|
template shortcut to build the body and html.
|
|
|
|
Example that builds an email from the templates ``message_subject.txt``,
|
|
``message_body.txt`` and ``message_body.html``::
|
|
|
|
from django.core.mail import EmailMultiAlternatives
|
|
from django.template import Context
|
|
from django.template.loader import render_to_string
|
|
|
|
template_data = {
|
|
'ORDERNO': "12345", 'TRACKINGNO': "1Z987"
|
|
}
|
|
|
|
plaintext_context = Context(autoescape=False) # HTML escaping not appropriate in plaintext
|
|
subject = render_to_string("message_subject.txt", template_data, plaintext_context)
|
|
text_body = render_to_string("message_body.txt", template_data, plaintext_context)
|
|
html_body = render_to_string("message_body.html", template_data)
|
|
|
|
msg = EmailMultiAlternatives(subject=subject, from_email="store@example.com",
|
|
to=["customer@example.com"], body=text_body)
|
|
msg.attach_alternative(html_body, "text/html")
|
|
msg.send()
|
|
|