From 6a2e30ba8ff5d100c7a68c30387140e83eec4fa4 Mon Sep 17 00:00:00 2001
From: medmunds <medmunds@gmail.com>
Date: Tue, 3 May 2022 15:27:05 -0700
Subject: [PATCH] Docs: note Mailgun broken display name encoding

Document that Mailgun's API can mis-encode
display names containing both punctuation and
non-ASCII characters.

Closes #270
---
 CHANGELOG.rst         |  6 ++++++
 docs/esps/mailgun.rst | 12 +++++++++++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 9651c81..dcc0193 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -33,6 +33,10 @@ vNext
 Other
 ~~~~~
 
+* **Mailgun:** Document Mailgun's incorrect handling of display names containing
+  both non-ASCII characters and punctuation. (Thanks to `@Flexonze`_ for spotting and
+  reporting the issue, and to Mailgun's `@b0d0nne11`_ for investigating.)
+
 * **Mandrill:** Document Mandrill's incorrect handling of non-ASCII attachment filenames.
   (Thanks to `@Thorbenl`_ for reporting the issue and following up with MailChimp.)
 
@@ -1287,6 +1291,7 @@ Features
 .. _@ailionx: https://github.com/ailionx
 .. _@alee: https://github.com/alee
 .. _@anstosa: https://github.com/anstosa
+.. _@b0d0nne11: https://github.com/b0d0nne11
 .. _@calvin: https://github.com/calvin
 .. _@chrisgrande: https://github.com/chrisgrande
 .. _@cjsoftuk: https://github.com/cjsoftuk
@@ -1296,6 +1301,7 @@ Features
 .. _@dominik-lekse: https://github.com/dominik-lekse
 .. _@ewingrj: https://github.com/ewingrj
 .. _@fdemmer: https://github.com/fdemmer
+.. _@Flexonze: https://github.com/Flexonze
 .. _@Honza-m: https://github.com/Honza-m
 .. _@janneThoft: https://github.com/janneThoft
 .. _@jc-ee: https://github.com/jc-ee
diff --git a/docs/esps/mailgun.rst b/docs/esps/mailgun.rst
index 5282a46..595c74b 100644
--- a/docs/esps/mailgun.rst
+++ b/docs/esps/mailgun.rst
@@ -202,6 +202,15 @@ Limitations and quirks
       Earlier Anymail releases did not check for these cases, and attachments
       without filenames/Content-IDs would be ignored by Mailgun without notice.
 
+**Display name problems with punctuation and non-ASCII characters**
+  Mailgun does not correctly handle certain display names in :mailheader:`From`,
+  :mailheader:`To`, and other email headers. If a display name includes *both* non-ASCII characters
+  and certain punctuation (such as parentheses), the resulting email will
+  use a non-standard encoding that causes some email clients to display
+  additional `"` or `\\"` characters wrapping the display name. (Verified
+  and reported to Mailgun engineering 3/2022. See `Anymail issue #270`_
+  for examples and specific details.)
+
 **Envelope sender uses only domain**
   Anymail's :attr:`~anymail.message.AnymailMessage.envelope_sender` is used to
   select your Mailgun :ref:`sender domain <mailgun-sender-domain>`. For
@@ -244,7 +253,8 @@ Limitations and quirks
 
   .. versionadded:: 8.2
 
-
+.. _Anymail issue #270:
+    https://github.com/anymail/django-anymail/issues/270
 .. _undocumented API requirement:
     https://mailgun.uservoice.com/forums/156243-feature-requests/suggestions/35668606