Update (almost) all the docs

docs/esps/index.rst

@@ -0,0 +1,23 @@
+.. _supported-esps:
+
+Supported ESPs
+--------------
+
+Anymail supports these ESPs. Click in for the specific
+settings required and notes about any quirks or limitations:
+
+.. these are listed in alphabetical order
+
+.. toctree::
+   :maxdepth: 1
+
+   mailgun
+   mandrill
+   postmark
+   sendgrid
+
+
+Don't see your favorite ESP here? You can suggest that
+Anymail add it, or even :ref:`contribute <contributing>`
+your own implementation to Anymail.
+

docs/esps/mailgun.rst

@@ -0,0 +1,103 @@
+.. _mailgun-backend:
+
+Mailgun
+-------
+
+Anymail integrates with the `Mailgun <https://mailgun.com>`_
+transactional email service from Rackspace, using their
+REST API.
+
+
+Settings
+========
+
+.. rubric:: EMAIL_BACKEND
+
+To use Anymail's Mailgun backend, set:
+
+  .. code-block:: python
+
+      EMAIL_BACKEND = "anymail.backends.mailgun.MailgunBackend"
+
+in your settings.py. (Watch your capitalization: Mailgun spells their name with a
+lowercase "g", so Anymail does too.)
+
+
+.. setting:: ANYMAIL_MAILGUN_API_KEY
+
+.. rubric:: MAILGUN_API_KEY
+
+Required. Your Mailgun API key:
+
+  .. code-block:: python
+
+      ANYMAIL = {
+          ...
+          "MAILGUN_API_KEY": "<your API key>",
+      }
+
+Anymail will also look for ``MAILGUN_API_KEY`` at the
+root of the settings file if neither ``ANYMAIL["MAILGUN_API_KEY"]``
+nor ``ANYMAIL_MAILGUN_API_KEY`` is set.
+
+
+.. setting:: ANYMAIL_MAILGUN_API_URL
+
+.. rubric:: MAILGUN_API_URL
+
+The base url for calling the Mailgun API. It does not include
+the sender domain. (Anymail :ref:`figures this out <mailgun-sender-domain>`
+for you.)
+
+The default is ``MAILGUN_API_URL = "https://api.mailgun.net/v3"``
+(It's unlikely you would need to change this.)
+
+
+.. _mailgun-sender-domain:
+
+Email sender domain
+===================
+
+Mailgun's API requires a sender domain `in the API url <base-url>`_.
+By default, Anymail will use the domain of each email's from address
+as the domain for the Mailgun API.
+
+If you need to override this default, you can use Anymail's
+:attr:`esp_extra` dict, either on an individual message:
+
+    .. code-block:: python
+
+        message = EmailMessage(from_email="sales@europe.example.com", ...)
+        message.esp_extra = {"sender_domain": "example.com"}
+
+
+... or as a global :ref:`send default <send-defaults>` setting that applies
+to all messages:
+
+    .. code-block:: python
+
+        ANYMAIL = {
+            ...
+            "MAILGUN_SEND_DEFAULTS": {
+                "esp_extra": {"sender_domain": "example.com"}
+            }
+        }
+
+.. _base-url: https://documentation.mailgun.com/api-intro.html#base-url
+
+
+Mailgun esp_extra
+=================
+
+Anymail's Mailgun backend will pass all :attr:`~anymail.message.AnymailMessage.esp_extra`
+values directly to Mailgun. You can use any of the (non-file) parameters listed in the
+`Mailgun sending docs`_. Example:
+
+  .. code-block:: python
+
+      message = AnymailMessage(...)
+      message.esp_extra = {
+          'o:testmode': 'yes',  # use Mailgun's test mode
+      }
+
+.. _Mailgun sending docs: https://documentation.mailgun.com/api-sending.html#sending

docs/esps/mandrill.rst

@@ -0,0 +1,151 @@
+.. _mandrill-backend:
+
+Mandrill
+--------
+
+Anymail integrates with the `Mandrill <http://mandrill.com/>`_
+transactional email service from MailChimp.
+
+
+Settings
+========
+
+.. rubric:: EMAIL_BACKEND
+
+To use Anymail's Mandrill backend, set:
+
+  .. code-block:: python
+
+      EMAIL_BACKEND = "anymail.backends.mandrill.MandrillBackend"
+
+in your settings.py.
+
+
+.. setting:: ANYMAIL_MANDRILL_API_KEY
+
+.. rubric:: MANDRILL_API_KEY
+
+Required. Your Mandrill API key:
+
+  .. code-block:: python
+
+      ANYMAIL = {
+          ...
+          "MANDRILL_API_KEY": "<your API key>",
+      }
+
+Anymail will also look for ``MANDRILL_API_KEY`` at the
+root of the settings file if neither ``ANYMAIL["MANDRILL_API_KEY"]``
+nor ``ANYMAIL_MANDRILL_API_KEY`` is set.
+
+
+.. setting:: ANYMAIL_MANDRILL_API_URL
+
+.. rubric:: MANDRILL_API_URL
+
+The base url for calling the Mandrill API. The default is
+``MANDRILL_API_URL = "https://mandrillapp.com/api/1.0"``,
+which is the secure, production version of Mandrill's 1.0 API.
+
+(It's unlikely you would need to change this.)
+
+
+Mandrill esp_extra
+==================
+
+Anymail's Mandrill backend does not yet implement the
+:attr:`~anymail.message.AnymailMessage.esp_extra` feature.
+
+
+.. _migrating-from-djrill:
+
+Migrating from Djrill
+=====================
+
+Anymail has its origins as a fork of the `Djrill`_
+package, which supported only Mandrill. If you are migrating
+from Djrill to Anymail -- e.g., because you are thinking
+of switching ESPs -- you'll need to make a few changes
+to your code.
+
+.. _Djrill: https://github.com/brack3t/Djrill
+
+Changes to settings
+~~~~~~~~~~~~~~~~~~~
+
+``MANDRILL_API_KEY``
+  Will still work, but consider moving it into the :setting:`ANYMAIL`
+  settings dict, or changing it to :setting:`ANYMAIL_MANDRILL_API_KEY`.
+
+``MANDRILL_SETTINGS``
+  Use :setting:`ANYMAIL_SEND_DEFAULTS` and/or :setting:`ANYMAIL_MANDRILL_SEND_DEFAULTS`
+  (see :ref:`send-defaults`).
+
+  There is one slight behavioral difference between :setting:`ANYMAIL_SEND_DEFAULTS`
+  and Djrill's ``MANDRILL_SETTINGS``: in Djrill, setting :attr:`tags` or
+  :attr:`merge_vars` on a message would completely override any global
+  settings defaults. In Anymail, those message attributes are merged with
+  the values from :setting:`ANYMAIL_SEND_DEFAULTS`.
+
+``MANDRILL_SUBACCOUNT``
+  Use :attr:`esp_extra` in :setting:`ANYMAIL_MANDRILL_SEND_DEFAULTS`:
+
+    .. code-block:: python
+
+        ANYMAIL = {
+            ...
+            "MANDRILL_SEND_DEFAULTS": {
+                "esp_extra": {"subaccount": "<your subaccount>"}
+            }
+        }
+
+``MANDRILL_IGNORE_RECIPIENT_STATUS``
+  Renamed to :setting:`ANYMAIL_IGNORE_RECIPIENT_STATUS`
+  (or just `IGNORE_RECIPIENT_STATUS` in the :setting:`ANYMAIL`
+  settings dict).
+
+
+Changes to EmailMessage attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``message.send_at``
+  If you are using an aware datetime for :attr:`send_at`,
+  it will keep working unchanged with Anymail.
+
+  If you are using a date (without a time), or a naive datetime,
+  be aware that these now default to Django's current_timezone,
+  rather than UTC as in Djrill.
+
+  (As with Djrill, it's best to use an aware datetime
+  that says exactly when you want the message sent.)
+
+
+``message.mandrill_response``
+  Anymail normalizes ESP responses, so you don't have to be familiar
+  with the format of Mandrill's JSON. See :attr:`anymail_status`.
+
+  The *raw* ESP response is attached to a sent message as
+  ``anymail_status.esp_response``, so the direct replacement
+  for message.mandrill_response is:
+
+    .. code-block:: python
+
+        mandrill_response = message.anymail_status.esp_response.json()
+
+**Templates and merge variables**
+  Coming to Anymail soon.
+
+  However, no other ESPs support MailChimp's templating language, so
+  you'll need to rewrite your templates as you switch ESPs.
+
+  Consider converting to :ref:`Django templates <django-templates>`
+  instead, as these can be used with any email backend.
+
+**Other Mandrill-specific attributes**
+  Are currently still supported by Anymail's Mandrill backend,
+  but will be ignored by other Anymail backends.
+
+  It's best to eliminate them if they're not essential
+  to your code. In the future, the Mandrill-only attributes
+  will be moved into the
+  :attr:`~anymail.message.AnymailMessage.esp_extra` dict.

docs/esps/postmark.rst

@@ -0,0 +1,17 @@
+.. _postmark:
+
+Postmark
+--------
+
+.. note::
+
+    Postmark support coming soon
+
+
+Settings
+========
+
+    EMAIL_BACKEND = "anymail.backends.postmark.PostmarkBackend"
+
+(Watch your capitalization: Postmark spells their name with a
+lowercase "m", so Anymail does too.)

docs/esps/sendgrid.rst

@@ -0,0 +1,17 @@
+.. _sendgrid:
+
+SendGrid
+--------
+
+.. note::
+
+    SendGrid support is being developed now
+
+
+Settings
+========
+
+    EMAIL_BACKEND = "anymail.backends.sendgrid.SendGridBackend"
+
+(Watch your capitalization: SendGrid spells their name with an
+uppercase "G", so Anymail does too.)