From 6c5b6b76fc918e17ef2697f1cc5d66df68ab85d0 Mon Sep 17 00:00:00 2001
From: Mike Edmunds <medmunds@gmail.com>
Date: Thu, 24 Aug 2023 17:19:56 -0700
Subject: [PATCH] Mailgun (docs): Clarify API keys

Explain account-level "Mailgun API keys"
vs. domain-level "sending API keys."
---
 CHANGELOG.rst         | 14 ++++++++++++++
 docs/esps/mailgun.rst | 36 +++++++++++++++++++++++++++++++++---
 2 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index c2670ab4..de004b08 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -25,6 +25,19 @@ Release history
 ^^^^^^^^^^^^^^^
     ..  This extra heading level keeps the ToC from becoming unmanageably long
 
+vNext
+-----
+
+*unreleased changes*
+
+Other
+~~~~~
+
+* **Mailgun (docs):** Clarify account-level "Mailgun API keys" vs.
+  domain-level "sending API keys." (Thanks to `@sdarwin`_ for
+  reporting the issue.)
+
+
 v10.1
 -----
 
@@ -1562,6 +1575,7 @@ Features
 .. _@puru02: https://github.com/puru02
 .. _@RignonNoel: https://github.com/RignonNoel
 .. _@sblondon: https://github.com/sblondon
+.. _@sdarwin: https://github.com/sdarwin
 .. _@sebashwa: https://github.com/sebashwa
 .. _@sebbacon: https://github.com/sebbacon
 .. _@slinkymanbyday: https://github.com/slinkymanbyday
diff --git a/docs/esps/mailgun.rst b/docs/esps/mailgun.rst
index ba176ae4..9081933a 100644
--- a/docs/esps/mailgun.rst
+++ b/docs/esps/mailgun.rst
@@ -34,8 +34,7 @@ in your settings.py.
 
 .. rubric:: MAILGUN_API_KEY
 
-Required for sending. Your Mailgun "Private API key" from the Mailgun
-`API security settings`_:
+Required for sending:
 
   .. code-block:: python
 
@@ -44,6 +43,37 @@ Required for sending. Your Mailgun "Private API key" from the Mailgun
           "MAILGUN_API_KEY": "<your API key>",
       }
 
+The key can be either:
+
+* (recommended) a domain-level Mailgun "Sending API key," found in Mailgun's dashboard
+  under "Sending" > "Domain settings" > "Sending API keys" (make sure the correct
+  domain is selected in the popup at top right!)
+* an account-level "Mailgun API key" from your Mailgun `API security settings`_.
+
+The account-level API key permits sending from any verified domain,
+but it also allows access to all other Mailgun APIs for your account
+(which Anymail doesn't need).
+
+The domain-level sending API key is preferred if you send from only
+a single domain. With multiple domains, either use an account API key,
+or supply the sending API key for a default domain in settings.py and
+use Django's :func:`~django.core.mail.get_connection` to substitute
+a different sending API key for other domains:
+
+    .. code-block:: python
+
+        from django.core.mail import EmailMessage, get_connection
+        # By default, use the settings.py MAILGUN_API_KEY:
+        message1 = EmailMessage(from_email="support@default-domain.example.com", ...)
+        message1.send()
+
+        # Use a different sending API key for this message:
+        connection = get_connection(api_key=SENDING_API_KEY_FOR_OTHER_DOMAIN)
+        message2 = EmailMessage(from_email="support@other-domain.example.com", ...,
+                                connection=connection)
+        message2.send()
+
+
 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.
@@ -115,7 +145,7 @@ Email sender domain
 -------------------
 
 Mailgun's API requires identifying the sender domain.
-By default, Anymail uses the domain of each messages's `from_email`
+By default, Anymail uses the domain of each message's `from_email`
 (e.g., "example.com" for "from\@example.com").
 
 You will need to override this default if you are using