pacnpal/django-anymail
1
0
Fork 0
mirror of https://github.com/pacnpal/django-anymail.git synced 2025-12-22 21:01:05 -05:00
Code Issues Packages Projects Releases Wiki Activity

Expose most Mandrill send features on EmailMessage objects.

Browse Source 
* Supports additional Mandrill send-API attributes on any ``EmailMessage``-derived object -- see details in readme
* Removes need for MANDRILL_API_URL in settings (since this is tightly tied to the code)
* Removes ``DjrillMessage`` from the readme (but not the code or tests) -- its functionality is now duplicated or exceeded by standard EmailMessage with additional attributes
* Ensures send(fail_silently=True) works as expected
This commit is contained in:
medmunds
2012-12-04 17:28:15 -08:00
parent 7d658f2f00
commit 8aab5e31b7
4 changed files with 291 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
README.rst
View File

@@ -17,38 +17,45 @@ Djrill is made available under the BSD license.
Installation
------------
::
Install from PyPI::
pip install djrill
The only dependency other than Django is the requests_ library from Kenneth Reitz. If you do not install through PyPI you will
need to do ::
The only dependency other than Django is the requests_ library from Kenneth
Reitz. (If you do not install Djrill using pip or setuptools, you will also
need to ``pip install requests``.)
pip install requests
Configuration
-------------
In ``settings.py``:
1. Add ``djrill`` to your ``INSTALLED_APPS``. ::
1. Add ``djrill`` to your ``INSTALLED_APPS``:
.. code:: python
INSTALLED_APPS = (
...
"djrill"
)
2. Add the following two lines, substituting your own ``MANDRILL_API_KEY``::
2. Add the following line, substituting your own ``MANDRILL_API_KEY``:
.. code:: python
MANDRILL_API_KEY = "brack3t-is-awesome"
MANDRILL_API_URL = "http://mandrillapp.com/api/1.0"
3. Override your existing email backend with the following line::
3. Override your existing email backend with the following line:
.. code:: python
EMAIL_BACKEND = "djrill.mail.backends.djrill.DjrillBackend"
4. (optional) If you want to be able to add senders through Django's admin or view stats about your
messages, do the following in your base ``urls.py`` ::
4. (optional) If you want to be able to add senders through Django's admin or
view stats about your messages, do the following in your base ``urls.py``:
.. code:: python
...
from django.contrib import admin
@@ -69,46 +76,86 @@ Usage
Since you are replacing the global ``EMAIL_BACKEND``, **all** emails are sent through Mandrill's service.
If you just want to use Mandrill for sending emails through Django's built-in ``send_mail`` and ``send_mass_mail`` methods, all
you need to do is follow steps 1 through 3 of the above Configuration.
In general, Djrill "just works" with Django's built-in `django.core.mail`_
package, including ``send_mail``, ``send_mass_mail``, ``EmailMessage`` and
``EmailMultiAlternatives``.
If, however, you want more control over the messages, to include an HTML version, or to attach tags or tracked URLs to an email,
usage of our ``DjrillMessage`` class, which is a thin wrapper around Django's ``EmailMultiAlternatives`` is required.
You can also take advantage of Mandrill-specific features like tags, metadata,
and tracking by creating a ``django.mail.EmailMessage`` (or for HTML,
``django.mail.EmailMultiAlternatives``) object and setting Mandrill-specific
properties on it before calling its ``send`` method.
Example, in a view: ::
Example:
from django.views.generic import View
.. code:: python
from djrill.mail import DjrillMessage
from django.core.mail import EmailMultiAlternatives # or just EmailMessage if you don't need HTML
class SendEmailView(View):
subject = "Djrill Message"
from_email = "Djrill Sender <djrill@example.com>" # this has to be in your Mandrill account's sending domains
to = ["Djrill Receiver <djrill.receiver@example.com>", "djrill.two@example.com"]
reply_email = "Customer Service <support@example.com>" # optional
text_content = "This is the text version of your email"
html_content = "<p>This is the HTML version of your email</p>" # optional, use with ``attach_alternative`` below
def get(self, request):
subject = "Djrill Message"
from_email = "djrill@example.com" # this has to be one of your approved senders
from_name = "Djrill" # optional
to = ["Djrill Receiver <djrill.receiver@example.com>", "djrill.two@example.com"]
text_content = "This is the text version of your email"
html_content = "<p>This is the HTML version of your email</p>" # optional, requires the ``attach_alternative`` line below
tags = ["one tag", "two tag", "red tag", "blue tag"] # optional, can't be over 50 chars or start with an underscore
msg = EmailMultiAlternatives(subject, text_content, from_email, to, headers={'Reply-To': reply_email})
msg.tags = ["one tag", "two tag", "red tag", "blue tag"] # optional, Mandrill-specific message extension
msg.metadata = {'user_id': "8675309"} # optional, Mandrill-specific message extension
msg.attach_alternative(html_content, "text/html")
msg.send()
msg = DjrillMessage(subject, text_content, from_email, to, tags=tags, from_name=from_name)
msg.attach_alternative(html_content, "text/html")
msg.send()
... # you'll want to return some sort of HttpResponse
If the Mandrill API returns an error response for any reason, the send call will
raise a ``djrill.mail.backends.djrill.DjrillBackendHTTPError`` exception
(unless called with fail_silently=True).
Any tags over 50 characters in length are silently ignored since Mandrill doesn't support them. Any tags starting with an underscore will raise an ``ImproperlyConfigured``
exception. Tags with an underscore are reserved by Mandrill.
Djrill supports most of the functionality of Django's ``EmailMessage`` and
``EmailMultiAlternatives``. Some limitations:
If you attach more than one alternative type, an ``ImproperlyConfigured`` exception will be raised. Mandrill does not support attaching
files to an email, so attachments will be silently ignored.
* Djrill accepts additional headers, but only ``Reply-To`` and ``X-*`` (since
that is all that Mandrill accepts). Any other extra headers will raise a
``ValueError`` exception when you attempt to send the message.
* Djrill requires that if you ``attach_alternative`` to a message, there must be
only one alternative type, and it must be text/html. Otherwise, Djrill will
raise a ``ValueError`` exception when you attempt to send the message.
(Mandrill doesn't support sending multiple html alternative parts, or any
non-html alternatives.)
* Djrill (currently) silently ignores all attachments on a message.
* Djrill treats all cc and bcc recipients as if they were additional "to"
addresses. (Mandrill does not distinguish cc, and only allows a single bcc --
which Djrill doesn't use. *Caution:* depending on the ``preserve_recipients``
setting, this could result in exposing bcc addresses to all recipients. It's
probably best to just avoid bcc.)
Not shown above, but settable, are the two options, ``track_clicks`` and ``track_opens``. They are both set to ``True`` by default, but can be set to ``False`` and passed in when you instantiate your ``DjrillMessage``
object.
Many of the options from the Mandrill `messages/send.json API`_ ``message``
struct can be set directly on an ``EmailMessage`` (or subclass) object:
* ``track_opens`` - Boolean
* ``track_clicks`` - Boolean (If you want to track clicks in HTML only, not
plaintext mail, you must *not* set this property, and instead just set the
default in your Mandrill account sending options.)
* ``auto_text`` - Boolean
* ``url_strip_qs`` - Boolean
* ``preserve_recipients`` - Boolean -- see the caution about bcc addresses above
* ``global_merge_vars`` - a dict -- e.g.,
``{ 'company': "ACME", 'offer': "10% off" }``
* ``recipient_merge_vars`` - a dict whose keys are the recipient email addresses
and whose values are dicts of merge vars for each recipient -- e.g.,
``{ 'wiley@example.com': { 'offer': "15% off anvils" } }``
* ``tags`` - a list of strings
* ``google_analytics_domains`` - a list of string domain names
* ``google_analytics_campaign`` - a string or list of strings
* ``metadata`` - a dict
* ``recipient_metadata`` - a dict whose keys are the recipient email addresses,
and whose values are dicts of metadata for each recipient (similar to
``recipient_merge_vars``)
These Mandrill-specific properties work with *any* ``EmailMessage``-derived
object, so you can use them with many other apps that add Django mail
functionality (such as Django template-based messages).
If you have any questions about the python syntax for any of these properties,
see ``DjrillMandrillFeatureTests`` in tests.py for examples.
Just like Django's ``EmailMessage`` and ``EmailMultiAlternatives``, ``DjrillMessage`` accepts extra headers through the
``headers`` argument. Currently it only accepts ``Reply-To`` and ``X-*`` headers since that is all that Mandrill accepts. Any
extra headers are silently discarded.
Testing
-------
@@ -145,3 +192,6 @@ the awesome ``requests`` library.
.. _requests: http://docs.python-requests.org
.. _django-adminplus: https://github.com/jsocol/django-adminplus
.. _mock: http://www.voidspace.org.uk/python/mock/index.html
.. _django.core.mail: https://docs.djangoproject.com/en/dev/topics/email/
.. _messages/send.json API: https://mandrillapp.com/api/docs/messages.html#method=send