Add ESP templates, batch send and merge

* message.template_id to use ESP stored templates
* message.merge_data and merge_global_data
  to supply per-recipient/global merge variables
  (with or without an ESP stored template)
* When using per-recipient merge_data, tell ESP to use
  batch send: individual message per "to" address.
  (Mailgun does this automatically; SendGrid requires
  using a different "to" field; Mandrill requires
  `preserve_recipients=False`; Postmark doesn't
  support *this type* of batch sending with merge data.)
* Allow message.from_email=None (must be set after
  init) and message.subject=None to suppress those
  fields in API calls (for ESPs that allow "From" and
  "Subject" in their template definitions).

Mailgun:
* Emulate merge_global_data by copying to
  recipient-variables for each recipient.

SendGrid:
* Add delimiters to merge field names via
  esp_extra['merge_field_format'] or
  ANYMAIL_SENDGRID_MERGE_FIELD_FORMAT setting.

Mandrill:
* Remove Djrill versions of these features;
  update migration notes.

Closes #5.
This commit is contained in:
medmunds
2016-05-03 18:25:37 -07:00
parent 271eb5c926
commit 75730e8219
20 changed files with 882 additions and 245 deletions

View File

@@ -115,6 +115,52 @@ see :ref:`unsupported-features`.
Postmark does not support :attr:`~anymail.message.AnymailMessage.send_at`.
.. _postmark-templates:
Batch sending/merge and ESP templates
-------------------------------------
Postmark supports :ref:`ESP stored templates <esp-stored-templates>`
populated with global merge data for all recipients, but does not
offer :ref:`batch sending <batch-send>` with per-recipient merge data.
Anymail's :attr:`~anymail.message.AnymailMessage.merge_data`
message attribute is not supported with the Postmark backend.
To use a Postmark template, set the message's
:attr:`~anymail.message.AnymailMessage.template_id` to the numeric
Postmark "TemplateID" and supply the "TemplateModel" using
the :attr:`~anymail.message.AnymailMessage.merge_global_data`
message attribute:
.. code-block:: python
message = EmailMessage(
...
subject=None, # use template subject
to=["alice@example.com"] # single recipient...
# ...multiple to emails would all get the same message
# (and would all see each other's emails in the "to" header)
)
message.template_id = 80801 # use this Postmark template
message.merge_global_data = {
'name': "Alice",
'order_no': "12345",
'ship_date': "May 15",
'items': [
{'product': "Widget", 'price': "9.99"},
{'product': "Gadget", 'price': "17.99"},
],
}
Set the EmailMessage's subject to `None` to use the subject from
your Postmark template, or supply a subject with the message to override
the template value.
See this `Postmark blog post on templates`_ for more information.
.. _Postmark blog post on templates:
https://postmarkapp.com/blog/special-delivery-postmark-templates
.. _postmark-webhooks: