mirror of
https://github.com/pacnpal/django-anymail.git
synced 2025-12-21 20:31:06 -05:00
Docs: break apart the lengthy readme into organized docs
Also sphinx-ify where appropriate, and lots of general cleanup/editing.
This commit is contained in:
medmunds
225
docs/usage/sending_mail.rst
Normal file
225
docs/usage/sending_mail.rst
Normal file
@@ -0,0 +1,225 @@
|
||||
Sending Mail
|
||||
============
|
||||
|
||||
Djrill handles **all** outgoing email sent through Django's standard
|
||||
:mod:`django.core.mail` package, including :func:`~django.core.mail.send_mail`,
|
||||
:func:`~django.core.mail.send_mass_mail`, the :class:`~django.core.mail.EmailMessage` class,
|
||||
and even :func:`~django.core.mail.mail_admins`.
|
||||
|
||||
If you'd like to selectively send only some messages through Mandrill,
|
||||
there is a way to :ref:`use multiple email backends <multiple-backends>`.
|
||||
|
||||
|
||||
.. _django-send-support:
|
||||
|
||||
Django Email Support
|
||||
--------------------
|
||||
|
||||
Djrill supports most of the functionality of Django's :class:`~django.core.mail.EmailMessage`
|
||||
and :class:`~django.core.mail.EmailMultiAlternatives` classes.
|
||||
|
||||
Some notes and limitations:
|
||||
|
||||
**Display Names**
|
||||
All email addresses (from, to, cc) can be simple
|
||||
("email\@example.com") or can include a display name
|
||||
("Real Name <email\@example.com>").
|
||||
|
||||
**From Address**
|
||||
The ``from_email`` must be in one of the approved sending
|
||||
domains in your Mandrill account, or Mandrill will refuse to send the message.
|
||||
|
||||
**CC Recipients**
|
||||
Djrill treats all "cc" recipients as if they were
|
||||
additional "to" addresses. (Mandrill does not distinguish "cc" from "to".)
|
||||
|
||||
.. note::
|
||||
|
||||
By default, Mandrill hides all recipients from each other. If you want the
|
||||
headers to list everyone who was sent the message, you'll also need to set the
|
||||
Mandrill option :attr:`preserve_recipients` to `!True`
|
||||
|
||||
**BCC Recipients**
|
||||
Mandrill does not permit more than one "bcc" address.
|
||||
Djrill raises :exc:`~djrill.NotSupportedByMandrillError` if you attempt to send a
|
||||
message with multiple bcc's.
|
||||
|
||||
(Mandrill's bcc option seems intended primarily
|
||||
for logging. To send a single message to multiple recipients without exposing
|
||||
their email addresses to each other, simply include them all in the "to" list
|
||||
and leave Mandrill's :attr:`preserve_recipients` set to `!False`.)
|
||||
|
||||
.. versionadded:: 0.3
|
||||
Previously "bcc" was treated as "cc"
|
||||
|
||||
|
||||
.. _sending-html:
|
||||
|
||||
**HTML/Alternative Parts**
|
||||
To include an HTML version of a message, use
|
||||
:meth:`~django.core.mail.EmailMultiAlternatives.attach_alternative`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.core.mail import EmailMultiAlternatives
|
||||
|
||||
msg = EmailMultiAlternatives("Subject", "text body",
|
||||
"from@example.com", ["to@example.com"])
|
||||
msg.attach_alternative("<html>html body</html>", "text/html")
|
||||
|
||||
Djrill allows a maximum of one
|
||||
:meth:`~django.core.mail.EmailMultiAlternatives.attach_alternative`
|
||||
on a message, and it must be ``mimetype="text/html"``.
|
||||
Otherwise, Djrill will raise :exc:`~djrill.NotSupportedByMandrillError` when you
|
||||
attempt to send the message. (Mandrill doesn't support sending multiple html
|
||||
alternative parts, or any non-html alternatives.)
|
||||
|
||||
|
||||
.. _sending-attachments:
|
||||
|
||||
**Attachments**
|
||||
Djrill will send a message's attachments. (Note that Mandrill may impose limits
|
||||
on size and type of attachments.)
|
||||
|
||||
Also, if an image attachment has a Content-ID header, Djrill will tell Mandrill
|
||||
to treat that as an embedded image rather than an ordinary attachment.
|
||||
(For an example, see :meth:`~DjrillBackendTests.test_embedded_images`
|
||||
in :file:`tests/test_mandrill_send.py`.)
|
||||
|
||||
.. versionadded:: 0.3
|
||||
Attachments
|
||||
|
||||
.. versionchanged:: 0.4
|
||||
Special handling for embedded images
|
||||
|
||||
**Headers**
|
||||
Djrill accepts additional headers, but only ``Reply-To`` and
|
||||
``X-*`` (since that is all that Mandrill accepts). Any other extra headers
|
||||
will raise :exc:`~djrill.NotSupportedByMandrillError` when you attempt to send the
|
||||
message.
|
||||
|
||||
|
||||
.. _mandrill-send-support:
|
||||
|
||||
Mandrill-Specific Options
|
||||
-------------------------
|
||||
|
||||
Most of the options from the Mandrill
|
||||
`messages/send API <https://mandrillapp.com/api/docs/messages.html#method=send>`_
|
||||
`message` struct can be set directly on an :class:`~django.core.mail.EmailMessage`
|
||||
(or subclass) object:
|
||||
|
||||
.. attribute:: track_opens
|
||||
|
||||
``Boolean``: whether Mandrill should enable open-tracking for this message.
|
||||
Default from your Mandrill account settings. ::
|
||||
|
||||
message.track_opens = True
|
||||
|
||||
.. attribute:: track_clicks
|
||||
|
||||
``Boolean``: whether Mandrill should enable click-tracking for this message.
|
||||
Default from your Mandrill account settings.
|
||||
|
||||
.. note::
|
||||
|
||||
Mandrill has an option to track clicks in HTML email but not plaintext, but
|
||||
it's *only* available in your Mandrill account settings. If you want to use that
|
||||
option, set it at Mandrill, and *don't* set the ``track_clicks`` attribute here.
|
||||
|
||||
.. attribute:: auto_text
|
||||
|
||||
``Boolean``: whether Mandrill should automatically generate a text body from the HTML.
|
||||
Default from your Mandrill account settings.
|
||||
|
||||
.. attribute:: url_strip_qs
|
||||
|
||||
``Boolean``: whether Mandrill should ignore any query parameters when aggregating
|
||||
URL tracking data. Default from your Mandrill account settings.
|
||||
|
||||
.. attribute:: preserve_recipients
|
||||
|
||||
``Boolean``: whether Mandrill should include all recipients in the "to" message header.
|
||||
Default from your Mandrill account settings.
|
||||
|
||||
.. attribute:: global_merge_vars
|
||||
|
||||
``dict``: merge variables to use for all recipients (most useful with :ref:`mandrill-templates`). ::
|
||||
|
||||
message.global_merge_vars = {'company': "ACME", 'offer': "10% off"}
|
||||
|
||||
.. attribute:: recipient_merge_vars
|
||||
|
||||
``dict``: per-recipient merge variables (most useful with :ref:`mandrill-templates`). The keys
|
||||
in the dict are the recipient email addresses, and the values are dicts of merge vars for
|
||||
each recipient::
|
||||
|
||||
message.recipient_merge_vars = {
|
||||
'wiley@example.com': {'offer': "15% off anvils"},
|
||||
'rr@example.com': {'offer': "instant tunnel paint"}
|
||||
}
|
||||
|
||||
.. attribute:: tags
|
||||
|
||||
``list`` of ``str``: tags to apply to the message, for filtering reports in the Mandrill
|
||||
dashboard. (Note that Mandrill prohibits tags longer than 50 characters or starting with
|
||||
underscores.) ::
|
||||
|
||||
message.tags = ["Order Confirmation", "Test Variant A"]
|
||||
|
||||
.. attribute:: google_analytics_domains
|
||||
|
||||
``list`` of ``str``: domain names for links where Mandrill should add Google Analytics
|
||||
tracking parameters. ::
|
||||
|
||||
message.google_analytics_domains = ["example.com"]
|
||||
|
||||
.. attribute:: google_analytics_campaign
|
||||
|
||||
``str`` or ``list`` of ``str``: the utm_campaign tracking parameter to attach to links
|
||||
when adding Google Analytics tracking. (Mandrill defaults to the message's from_email as
|
||||
the campaign name.)
|
||||
|
||||
.. attribute:: metadata
|
||||
|
||||
``dict``: metadata values Mandrill should store with the message for later search and
|
||||
retrieval. ::
|
||||
|
||||
message.metadata = {'customer': customer.id, 'order': order.reference_number}
|
||||
|
||||
.. attribute:: recipient_metadata
|
||||
|
||||
``dict``: per-recipient metadata values. Keys are the recipient email addresses,
|
||||
and values are dicts of metadata for each recipient (similar to
|
||||
:attr:`recipient_merge_vars`)
|
||||
|
||||
|
||||
These Mandrill-specific properties work with *any*
|
||||
:class:`~django.core.mail.EmailMessage`-derived object, so you can use them with
|
||||
many other apps that add Django mail functionality.
|
||||
|
||||
If you have questions about the python syntax for any of these properties,
|
||||
see :class:`DjrillMandrillFeatureTests` in :file:`tests/test_mandrill_send.py` for examples.
|
||||
|
||||
|
||||
.. _djrill-exceptions:
|
||||
|
||||
Exceptions
|
||||
----------
|
||||
|
||||
.. versionadded:: 0.3
|
||||
Djrill-specific exceptions
|
||||
|
||||
.. exception:: djrill.NotSupportedByMandrillError
|
||||
|
||||
If the email tries to use features that aren't supported by Mandrill, the send
|
||||
call will raise a :exc:`~!djrill.NotSupportedByMandrillError` exception (a subclass
|
||||
of :exc:`ValueError`).
|
||||
|
||||
|
||||
.. exception:: djrill.MandrillAPIError
|
||||
|
||||
If the Mandrill API fails or returns an error response, the send call will
|
||||
raise a :exc:`~!djrill.MandrillAPIError` exception (a subclass of :exc:`requests.HTTPError`).
|
||||
The exception's :attr:`status_code` and :attr:`response` attributes may
|
||||
help explain what went wrong.
|
||||
Reference in New Issue
Block a user