mirror of
https://github.com/pacnpal/django-anymail.git
synced 2025-12-20 11:51:05 -05:00
d0596d100b
A message's `from_email` and each address in its `to`, `cc`, and `bcc` lists must contain exactly one email address. Previous code would silently ignore additional addresses, leading to unusual behavior. Now, raises new `AnymailInvalidAddress` exception. Example: `from_email='Widgets, Inc. <widgets@example.com>'` is invalid: it needs double-quotes around the "Widgets, Inc." display-name portion. In earlier versions, this probably would have sent the message from something like "From: Widgets <@localhost>". Now, it will raise an exception. **Potentially-breaking change:** If your code is using an unquoted display-name containing a comma in an email address, it will now raise an error. In earlier versions, this may have appeared to succeed, but was almost certainly not doing what you intended. Fixes #44.
71 lines
2.5 KiB
ReStructuredText
71 lines
2.5 KiB
ReStructuredText
.. _anymail-exceptions:
|
|
|
|
Exceptions
|
|
----------
|
|
|
|
.. module:: anymail.exceptions
|
|
|
|
.. exception:: AnymailUnsupportedFeature
|
|
|
|
If the email tries to use features that aren't supported by the ESP, the send
|
|
call will raise an :exc:`!AnymailUnsupportedFeature` error, and the message
|
|
won't be sent. See :ref:`unsupported-features`.
|
|
|
|
You can disable this exception (ignoring the unsupported features and
|
|
sending the message anyway, without them) by setting
|
|
:setting:`ANYMAIL_IGNORE_UNSUPPORTED_FEATURES` to `True`.
|
|
|
|
|
|
.. exception:: AnymailRecipientsRefused
|
|
|
|
Raised when *all* recipients (to, cc, bcc) of a message are invalid or rejected by
|
|
your ESP *at send time.* See :ref:`recipients-refused`.
|
|
|
|
You can disable this exception by setting :setting:`ANYMAIL_IGNORE_RECIPIENT_STATUS`
|
|
to `True` in your settings.py, which will cause Anymail to treat any
|
|
non-:exc:`AnymailAPIError` response from your ESP as a successful send.
|
|
|
|
|
|
.. exception:: AnymailAPIError
|
|
|
|
If the ESP's API fails or returns an error response, the send call will
|
|
raise an :exc:`!AnymailAPIError`.
|
|
|
|
The exception's :attr:`status_code` and :attr:`response` attributes may
|
|
help explain what went wrong. (Tip: you may also be able to check the API log in
|
|
your ESP's dashboard. See :ref:`troubleshooting`.)
|
|
|
|
|
|
.. exception:: AnymailInvalidAddress
|
|
|
|
.. versionadded:: 0.7
|
|
|
|
The send call will raise a :exc:`!AnymailInvalidAddress` error if you
|
|
attempt to send a message with invalidly-formatted email addresses in
|
|
the :attr:`from_email` or recipient lists.
|
|
|
|
One source of this error can be using a display-name ("real name") containing
|
|
commas or parentheses. Per :rfc:`5322`, you should use double quotes around
|
|
the display-name portion of an email address:
|
|
|
|
.. code-block:: python
|
|
|
|
# won't work:
|
|
send_mail(from_email='Widgets, Inc. <widgets@example.com>', ...)
|
|
# must use double quotes around display-name containing comma:
|
|
send_mail(from_email='"Widgets, Inc." <widgets@example.com>', ...)
|
|
|
|
|
|
.. exception:: AnymailSerializationError
|
|
|
|
The send call will raise a :exc:`!AnymailSerializationError`
|
|
if there are message attributes Anymail doesn't know how to represent
|
|
to your ESP.
|
|
|
|
The most common cause of this error is including values other than
|
|
strings and numbers in your :attr:`merge_data` or :attr:`metadata`.
|
|
(E.g., you need to format `Decimal` and `date` data to
|
|
strings before setting them into :attr:`merge_data`.)
|
|
|
|
See :ref:`formatting-merge-data` for more information.
|