Docs: document AMPHTML

* Add general instructions for sending AMP Email
  with Django
* Document ability of Amazon SES and SendGrid backends
  to send AMPHTML (via arbitrary alternative parts)
* Add AMP Email row to ESP support table

Author: medmunds

CHANGELOG.rst

@@ -50,6 +50,8 @@ Other
 
 * Test against Django 3.2 prerelease (including support for Python 3.9)
 
+* Document how to send AMP for Email with Django, and note which ESPs support it.
+
 * Move CI testing to GitHub Actions (and stop using Travis-CI).
 
 * Internal: catch invalid recipient status earlier in ESP response parsing

docs/esps/amazon_ses.rst

@@ -93,6 +93,11 @@ Limitations and quirks
   Amazon SES is one of the few ESPs that *does* support sending arbitrary alternative
   message parts (beyond just a single text/plain and text/html part).
 
+**AMP for Email**
+  Amazon SES supports sending AMPHTML email content. To include it, use
+  ``message.attach_alternative("...AMPHTML content...", "text/x-amp-html")``
+  (and be sure to also include regular HTML and text bodies, too).
+
 **Spoofed To header and multiple From emails allowed**
   Amazon SES is one of the few ESPs that supports spoofing the :mailheader:`To` header
   (see :ref:`message-headers`) and supplying multiple addresses in a message's `from_email`.
@@ -252,7 +257,7 @@ message attributes.
 Amazon's templated email APIs don't support several features available for regular email.
 When :attr:`~anymail.message.AnymailMessage.template_id` is used:
 
-* Attachments are not supported
+* Attachments and alternative parts (including AMPHTML) are not supported
 * Extra headers are not supported
 * Overriding the template's subject or body is not supported
 * Anymail's :attr:`~anymail.message.AnymailMessage.metadata` is not supported

docs/esps/index.rst

@@ -43,6 +43,7 @@ Email Service Provider                        |Amazon SES|  |Mailgun|    |Mailje
 :attr:`~AnymailMessage.tags`                  Yes           Yes          Max 1 tag   Yes          Max 1 tag   Yes         Yes           Max 1 tag
 :attr:`~AnymailMessage.track_clicks`          No            Yes          Yes         Yes          Yes         Yes         No            Yes
 :attr:`~AnymailMessage.track_opens`           No            Yes          Yes         Yes          Yes         Yes         No            Yes
+:ref:`amp-email`                              Yes           Yes          No          No           No          Yes         No            Yes
 
 .. rubric:: :ref:`templates-and-merge`
 ---------------------------------------------------------------------------------------------------------------------------------------------------

docs/esps/sendgrid.rst

@@ -237,6 +237,15 @@ Limitations and quirks
 
   (Noted June, 2019 and December, 2019)
 
+**Arbitrary alternative parts allowed**
+  SendGrid is one of the few ESPs that *does* support sending arbitrary alternative
+  message parts (beyond just a single text/plain and text/html part).
+
+**AMP for Email**
+  SendGrid supports sending AMPHTML email content. To include it, use
+  ``message.attach_alternative("...AMPHTML content...", "text/x-amp-html")``
+  (and be sure to also include regular HTML and text bodies, too).
+
 **No envelope sender overrides**
   SendGrid does not support overriding :attr:`~anymail.message.AnymailMessage.envelope_sender`
   on individual messages.

docs/sending/django_email.rst

@@ -58,6 +58,34 @@ It's good practice to send equivalent content in your plain-text body
 and the html version.
 
 
+.. _amp-email:
+
+.. rubric:: AMP Email
+
+Django's :class:`~django.core.mail.EmailMultiAlternatives` also supports sending
+`AMP for email`_ content. Attach the AMP alternative with the MIME type
+:mimetype:`text/x-amp-html`. Add the AMPHTML first, before the regular html alternative,
+to keep the parts in the recommended order:
+
+    .. code-block:: python
+        :emphasize-lines: 5-6
+
+        from django.core.mail import EmailMultiAlternatives
+
+        msg = EmailMultiAlternatives("Subject", "text body",
+                                     "[email protected]", ["[email protected]"])
+        msg.attach_alternative("<!doctype html><html amp4email data-css-strict>...",
+                               "text/x-amp-html")
+        msg.attach_alternative("<!doctype html><html>...", "text/html")
+        msg.send()
+
+Not all ESPs allow AMPHTML (check the chart under :ref:`supported-esps`).
+If yours doesn't, trying to send AMP content will raise an
+:ref:`unsupported feature <unsupported-features>` error.
+
+.. _AMP for Email: https://amp.dev/about/email/
+
+
 .. _sending-attachments:
 
 Attachments