Raise error for invalid/rejected recipients

Raise new MandrillRecipientsRefused exception
when Mandrill returns 'reject' or 'invalid' status
for *all* recipients of a message.

(Similar to Django's SMTP email backend raising
SMTPRecipientsRefused.)

Add setting MANDRILL_IGNORE_RECIPIENT_STATUS
to override the new exception.

Trap JSON parsing errors in Mandrill API response,
and raise MandrillAPIError for them. (Helps with #93.)

Closes #80.
Closes #81.

docs/history.rst

@@ -48,6 +48,18 @@ Removed DjrillAdminSite
   (Do this only if you changed to SimpleAdminConfig for Djrill, and aren't
   creating custom admin sites for any other Django apps you use.)
 
+Added exception for invalid or rejected recipients
+  Djrill 2.0 raises a new :exc:`djrill.MandrillRecipientsRefused` exception when
+  all recipients of a message invalid or rejected by Mandrill. This parallels
+  the behavior of Django's default :setting:`SMTP email backend <EMAIL_BACKEND>`,
+  which raises :exc:`SMTPRecipientsRefused <smtplib.SMTPRecipientsRefused>` when
+  all recipients are refused.
+
+  Your email-sending code should handle this exception (along with other
+  exceptions that could occur during a send). However, if you want to retain the
+  Djrill 1.x behavior and treat invalid or rejected recipients as successful sends,
+  you can set :setting:`MANDRILL_IGNORE_RECIPIENT_STATUS` to ``True`` in your settings.py.
+
 Removed unintended date-to-string conversion
   If your code was relying on Djrill to automatically convert date or datetime
   values to strings in :attr:`merge_vars`, :attr:`metadata`, or other Mandrill

docs/installation.rst

@@ -47,11 +47,25 @@ Djrill includes optional support for Mandrill webhooks, including inbound email.
 See the Djrill :ref:`webhooks <webhooks>` section for configuration details.
 
 
-Mandrill Subaccounts (Optional)
--------------------------------
+Other Optional Settings
+-----------------------
+
+.. setting:: MANDRILL_IGNORE_RECIPIENT_STATUS
+
+MANDRILL_IGNORE_RECIPIENT_STATUS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Set to ``True`` to disable :exc:`djrill.MandrillRecipientsRefused` exceptions
+on invalid or rejected recipients. (Default ``False``.)
+
+.. versionadded:: 2.0
+
 
 .. setting:: MANDRILL_SUBACCOUNT
 
+MANDRILL_SUBACCOUNT
+~~~~~~~~~~~~~~~~~~~
+
 If you are using Mandrill's `subaccounts`_ feature, you can globally set the
 subaccount for all messages sent through Djrill::
 

docs/usage/sending_mail.rst

@@ -362,6 +362,27 @@ Exceptions
     of :exc:`ValueError`).
 
 
+.. exception:: djrill.MandrillRecipientsRefused
+
+    If *all* recipients (to, cc, bcc) of a message are invalid or rejected by Mandrill
+    (e.g., because they are your Mandrill blacklist), the send call will raise a
+    :exc:`~!djrill.MandrillRecipientsRefused` exception.
+    You can examine the message's :ref:`mandrill_response property <mandrill-response>`
+    to determine the cause of the error.
+
+    If a single message is sent to multiple recipients, and *any* recipient is valid
+    (or the message is queued by Mandrill because of rate limiting or :attr:`send_at`), then
+    this exception will not be raised. You can still examine the mandrill_response
+    property after the send to determine the status of each recipient.
+
+    You can disable this exception by setting :setting:`MANDRILL_IGNORE_RECIPIENT_STATUS`
+    to True in your settings.py, which will cause Djrill to treat any non-API-error response
+    from Mandrill as a successful send.
+
+    .. versionadded:: 2.0
+       Djrill 1.x behaved as if ``MANDRILL_IGNORE_RECIPIENT_STATUS = True``.
+
+
 .. exception:: djrill.MandrillAPIError
 
     If the Mandrill API fails or returns an error response, the send call will
@@ -370,3 +391,4 @@ Exceptions
     help explain what went wrong. (Tip: you can also check Mandrill's
     `API error log <https://mandrillapp.com/settings/api>`_ to view the full API
     request and error response.)
+