mirror of
https://github.com/pacnpal/django-anymail.git
synced 2025-12-20 11:51:05 -05:00
0776b12331
Implement and document `merge_headers` for all other ESPs that can support it. (See #371 for base and Amazon SES implementation.) Closes #374
454 lines
19 KiB
Python
454 lines
19 KiB
Python
from datetime import datetime
|
|
from urllib.parse import quote
|
|
|
|
from ..exceptions import AnymailError, AnymailRequestsAPIError
|
|
from ..message import AnymailRecipientStatus
|
|
from ..utils import get_anymail_setting, rfc2822date
|
|
from .base_requests import AnymailRequestsBackend, RequestsPayload
|
|
|
|
|
|
class EmailBackend(AnymailRequestsBackend):
|
|
"""
|
|
Mailgun API Email Backend
|
|
"""
|
|
|
|
esp_name = "Mailgun"
|
|
|
|
def __init__(self, **kwargs):
|
|
"""Init options from Django settings"""
|
|
esp_name = self.esp_name
|
|
self.api_key = get_anymail_setting(
|
|
"api_key", esp_name=esp_name, kwargs=kwargs, allow_bare=True
|
|
)
|
|
self.sender_domain = get_anymail_setting(
|
|
"sender_domain",
|
|
esp_name=esp_name,
|
|
kwargs=kwargs,
|
|
allow_bare=True,
|
|
default=None,
|
|
)
|
|
api_url = get_anymail_setting(
|
|
"api_url",
|
|
esp_name=esp_name,
|
|
kwargs=kwargs,
|
|
default="https://api.mailgun.net/v3",
|
|
)
|
|
if not api_url.endswith("/"):
|
|
api_url += "/"
|
|
super().__init__(api_url, **kwargs)
|
|
|
|
def build_message_payload(self, message, defaults):
|
|
return MailgunPayload(message, defaults, self)
|
|
|
|
def raise_for_status(self, response, payload, message):
|
|
# Mailgun issues a terse 404 for unrecognized sender domains.
|
|
# Add some context:
|
|
if response.status_code == 404 and "Domain not found" in response.text:
|
|
raise AnymailRequestsAPIError(
|
|
"Unknown sender domain {sender_domain!r}.\n"
|
|
"Check the domain is verified with Mailgun, and that the ANYMAIL"
|
|
" MAILGUN_API_URL setting {api_url!r} is the correct region.".format(
|
|
sender_domain=payload.sender_domain, api_url=self.api_url
|
|
),
|
|
email_message=message,
|
|
payload=payload,
|
|
response=response,
|
|
backend=self,
|
|
)
|
|
|
|
super().raise_for_status(response, payload, message)
|
|
|
|
# Mailgun issues a cryptic "Mailgun Magnificent API" success response
|
|
# for invalid API endpoints. Convert that to a useful error:
|
|
if response.status_code == 200 and "Mailgun Magnificent API" in response.text:
|
|
raise AnymailRequestsAPIError(
|
|
"Invalid Mailgun API endpoint %r.\n"
|
|
"Check your ANYMAIL MAILGUN_SENDER_DOMAIN"
|
|
" and MAILGUN_API_URL settings." % response.url,
|
|
email_message=message,
|
|
payload=payload,
|
|
response=response,
|
|
backend=self,
|
|
)
|
|
|
|
def parse_recipient_status(self, response, payload, message):
|
|
# The *only* 200 response from Mailgun seems to be:
|
|
# {
|
|
# "id": "<20160306015544.116301.25145@example.org>",
|
|
# "message": "Queued. Thank you."
|
|
# }
|
|
#
|
|
# That single message id applies to all recipients.
|
|
# The only way to detect rejected, etc. is via webhooks.
|
|
# (*Any* invalid recipient addresses will generate a 400 API error)
|
|
parsed_response = self.deserialize_json_response(response, payload, message)
|
|
try:
|
|
message_id = parsed_response["id"]
|
|
mailgun_message = parsed_response["message"]
|
|
except (KeyError, TypeError) as err:
|
|
raise AnymailRequestsAPIError(
|
|
"Invalid Mailgun API response format",
|
|
email_message=message,
|
|
payload=payload,
|
|
response=response,
|
|
backend=self,
|
|
) from err
|
|
if not mailgun_message.startswith("Queued"):
|
|
raise AnymailRequestsAPIError(
|
|
"Unrecognized Mailgun API message '%s'" % mailgun_message,
|
|
email_message=message,
|
|
payload=payload,
|
|
response=response,
|
|
backend=self,
|
|
)
|
|
# Simulate a per-recipient status of "queued":
|
|
status = AnymailRecipientStatus(message_id=message_id, status="queued")
|
|
return {recipient.addr_spec: status for recipient in payload.all_recipients}
|
|
|
|
|
|
class MailgunPayload(RequestsPayload):
|
|
def __init__(self, message, defaults, backend, *args, **kwargs):
|
|
auth = ("api", backend.api_key)
|
|
self.sender_domain = backend.sender_domain
|
|
self.all_recipients = [] # used for backend.parse_recipient_status
|
|
|
|
# late-binding of recipient-variables:
|
|
self.merge_data = {}
|
|
self.merge_global_data = {}
|
|
self.metadata = {}
|
|
self.merge_metadata = {}
|
|
self.merge_headers = {}
|
|
self.to_emails = []
|
|
|
|
super().__init__(message, defaults, backend, auth=auth, *args, **kwargs)
|
|
|
|
def get_api_endpoint(self):
|
|
if self.sender_domain is None:
|
|
raise AnymailError(
|
|
"Cannot call Mailgun unknown sender domain. "
|
|
"Either provide valid `from_email`, "
|
|
"or set `message.esp_extra={'sender_domain': 'example.com'}`",
|
|
backend=self.backend,
|
|
email_message=self.message,
|
|
payload=self,
|
|
)
|
|
if "/" in self.sender_domain or "%2f" in self.sender_domain.lower():
|
|
# Mailgun returns a cryptic 200-OK "Mailgun Magnificent API" response
|
|
# if '/' (or even %-encoded '/') confuses it about the API endpoint.
|
|
raise AnymailError(
|
|
"Invalid '/' in sender domain '%s'" % self.sender_domain,
|
|
backend=self.backend,
|
|
email_message=self.message,
|
|
payload=self,
|
|
)
|
|
return "%s/messages" % quote(self.sender_domain, safe="")
|
|
|
|
def serialize_data(self):
|
|
self.populate_recipient_variables()
|
|
return self.data
|
|
|
|
# A not-so-brief digression about Mailgun's batch sending, template personalization,
|
|
# and metadata tracking capabilities...
|
|
#
|
|
# Mailgun has two kinds of templates:
|
|
# * ESP-stored templates (handlebars syntax), referenced by template name in the
|
|
# send API, with substitution data supplied as "custom data" variables.
|
|
# Anymail's `template_id` maps to this feature.
|
|
# * On-the-fly templating (`%recipient.KEY%` syntax), with template variables
|
|
# appearing directly in the message headers and/or body, and data supplied
|
|
# as "recipient variables" per-recipient personalizations. Mailgun docs also
|
|
# sometimes refer to this data as "template variables," but it's distinct from
|
|
# the substitution data used for stored handelbars templates.
|
|
#
|
|
# Mailgun has two mechanisms for supplying additional data with a message:
|
|
# * "Custom data" is supplied via `v:KEY` and/or `h:X-Mailgun-Variables` fields.
|
|
# Custom data is passed to tracking webhooks (as 'user-variables') and is
|
|
# available for `{{substitutions}}` in ESP-stored handlebars templates.
|
|
# Normally, the same custom data is applied to every recipient of a message.
|
|
# * "Recipient variables" are supplied via the `recipient-variables` field, and
|
|
# provide per-recipient data for batch sending. The recipient specific values
|
|
# are available as `%recipient.KEY%` virtually anywhere in the message
|
|
# (including header fields and other parameters).
|
|
#
|
|
# Anymail needs both mechanisms to map its normalized metadata and template
|
|
# merge_data features to Mailgun:
|
|
# (1) Anymail's `metadata` maps directly to Mailgun's custom data, where it can be
|
|
# accessed from webhooks.
|
|
# (2) Anymail's `merge_metadata` (per-recipient metadata for batch sends) maps
|
|
# *indirectly* through recipient-variables to Mailgun's custom data. To avoid
|
|
# conflicts, the recipient-variables mapping prepends 'v:' to merge_metadata
|
|
# keys. (E.g., Mailgun's custom-data "user" is set to "%recipient.v:user",
|
|
# which picks up its per-recipient value from Mailgun's
|
|
# `recipient-variables[to_email]["v:user"]`.)
|
|
# (3) Anymail's `merge_data` (per-recipient template substitutions) maps directly
|
|
# to Mailgun's `recipient-variables`, where it can be referenced in on-the-fly
|
|
# templates.
|
|
# (4) Anymail's `merge_global_data` (global template substitutions) is copied
|
|
# to Mailgun's `recipient-variables` for every recipient, as the default
|
|
# for missing `merge_data` keys.
|
|
# (5) Only if a stored template is used, `merge_data` and `merge_global_data` are
|
|
# *also* mapped *indirectly* through recipient-variables to Mailgun's custom
|
|
# data, where they can be referenced in handlebars {{substitutions}}.
|
|
# (E.g., Mailgun's custom-data "name" is set to "%recipient.name%", which picks
|
|
# up its per-recipient value from Mailgun's
|
|
# `recipient-variables[to_email]["name"]`.)
|
|
# (6) Anymail's `merge_headers` (per-recipient headers) maps to recipient-variables
|
|
# prepended with 'h:'.
|
|
#
|
|
# If Anymail's `merge_data`, `template_id` (stored templates) and `metadata` (or
|
|
# `merge_metadata`) are used together, there's a possibility of conflicting keys
|
|
# in Mailgun's custom data. Anymail treats that conflict as an unsupported feature
|
|
# error.
|
|
|
|
def populate_recipient_variables(self):
|
|
"""
|
|
Populate Mailgun recipient-variables and custom data
|
|
from merge data and metadata
|
|
"""
|
|
# (numbers refer to detailed explanation above)
|
|
# Mailgun parameters to construct:
|
|
recipient_variables = {}
|
|
custom_data = {}
|
|
|
|
# (1) metadata --> Mailgun custom_data
|
|
custom_data.update(self.metadata)
|
|
|
|
# (2) merge_metadata --> Mailgun custom_data via recipient_variables
|
|
if self.merge_metadata:
|
|
|
|
def vkey(key): # 'v:key'
|
|
return "v:{}".format(key)
|
|
|
|
# all keys used in any recipient's merge_metadata:
|
|
merge_metadata_keys = flatset(
|
|
recipient_data.keys() for recipient_data in self.merge_metadata.values()
|
|
)
|
|
# custom_data['key'] = '%recipient.v:key%' indirection:
|
|
custom_data.update(
|
|
{key: "%recipient.{}%".format(vkey(key)) for key in merge_metadata_keys}
|
|
)
|
|
# defaults for each recipient must cover all keys:
|
|
base_recipient_data = {
|
|
vkey(key): self.metadata.get(key, "") for key in merge_metadata_keys
|
|
}
|
|
for email in self.to_emails:
|
|
this_recipient_data = base_recipient_data.copy()
|
|
this_recipient_data.update(
|
|
{
|
|
vkey(key): value
|
|
for key, value in self.merge_metadata.get(email, {}).items()
|
|
}
|
|
)
|
|
recipient_variables.setdefault(email, {}).update(this_recipient_data)
|
|
|
|
# (3) and (4) merge_data, merge_global_data --> Mailgun recipient_variables
|
|
if self.merge_data or self.merge_global_data:
|
|
# all keys used in any recipient's merge_data:
|
|
merge_data_keys = flatset(
|
|
recipient_data.keys() for recipient_data in self.merge_data.values()
|
|
)
|
|
merge_data_keys = merge_data_keys.union(self.merge_global_data.keys())
|
|
# defaults for each recipient must cover all keys:
|
|
base_recipient_data = {
|
|
key: self.merge_global_data.get(key, "") for key in merge_data_keys
|
|
}
|
|
for email in self.to_emails:
|
|
this_recipient_data = base_recipient_data.copy()
|
|
this_recipient_data.update(self.merge_data.get(email, {}))
|
|
recipient_variables.setdefault(email, {}).update(this_recipient_data)
|
|
|
|
# (5) if template, also map Mailgun custom_data to per-recipient_variables
|
|
if self.data.get("template") is not None:
|
|
conflicts = merge_data_keys.intersection(custom_data.keys())
|
|
if conflicts:
|
|
self.unsupported_feature(
|
|
"conflicting merge_data and metadata keys (%s)"
|
|
" when using template_id"
|
|
% ", ".join("'%s'" % key for key in conflicts)
|
|
)
|
|
# custom_data['key'] = '%recipient.key%' indirection:
|
|
custom_data.update(
|
|
{key: "%recipient.{}%".format(key) for key in merge_data_keys}
|
|
)
|
|
|
|
# (6) merge_headers --> Mailgun recipient_variables via 'h:'-prefixed keys
|
|
if self.merge_headers:
|
|
|
|
def hkey(field_name): # 'h:Field-Name'
|
|
return "h:{}".format(field_name.title())
|
|
|
|
merge_header_fields = flatset(
|
|
recipient_headers.keys()
|
|
for recipient_headers in self.merge_headers.values()
|
|
)
|
|
merge_header_defaults = {
|
|
# existing h:Field-Name value (from extra_headers), or empty string
|
|
field: self.data.get(hkey(field), "")
|
|
for field in merge_header_fields
|
|
}
|
|
self.data.update(
|
|
# Set up 'h:Field-Name': '%recipient.h:Field-Name%' indirection
|
|
{
|
|
hvar: f"%recipient.{hvar}%"
|
|
for hvar in [hkey(field) for field in merge_header_fields]
|
|
}
|
|
)
|
|
|
|
for email in self.to_emails:
|
|
# Each recipient's recipient_variables needs _all_ merge header fields
|
|
recipient_headers = merge_header_defaults.copy()
|
|
recipient_headers.update(self.merge_headers.get(email, {}))
|
|
recipient_variables_for_headers = {
|
|
hkey(field): value for field, value in recipient_headers.items()
|
|
}
|
|
recipient_variables.setdefault(email, {}).update(
|
|
recipient_variables_for_headers
|
|
)
|
|
|
|
# populate Mailgun params
|
|
self.data.update({"v:%s" % key: value for key, value in custom_data.items()})
|
|
if recipient_variables or self.is_batch():
|
|
self.data["recipient-variables"] = self.serialize_json(recipient_variables)
|
|
|
|
#
|
|
# Payload construction
|
|
#
|
|
|
|
def init_payload(self):
|
|
self.data = {} # {field: [multiple, values]}
|
|
self.files = [] # [(field, multiple), (field, values)]
|
|
self.headers = {}
|
|
|
|
def set_from_email_list(self, emails):
|
|
# Mailgun supports multiple From email addresses
|
|
self.data["from"] = [email.address for email in emails]
|
|
if self.sender_domain is None and len(emails) > 0:
|
|
# try to intuit sender_domain from first from_email
|
|
self.sender_domain = emails[0].domain or None
|
|
|
|
def set_recipients(self, recipient_type, emails):
|
|
assert recipient_type in ["to", "cc", "bcc"]
|
|
if emails:
|
|
self.data[recipient_type] = [email.address for email in emails]
|
|
# used for backend.parse_recipient_status:
|
|
self.all_recipients += emails
|
|
if recipient_type == "to":
|
|
# used for populate_recipient_variables:
|
|
self.to_emails = [email.addr_spec for email in emails]
|
|
|
|
def set_subject(self, subject):
|
|
self.data["subject"] = subject
|
|
|
|
def set_reply_to(self, emails):
|
|
if emails:
|
|
reply_to = ", ".join([str(email) for email in emails])
|
|
self.data["h:Reply-To"] = reply_to
|
|
|
|
def set_extra_headers(self, headers):
|
|
for field, value in headers.items():
|
|
self.data["h:%s" % field.title()] = value
|
|
|
|
def set_text_body(self, body):
|
|
self.data["text"] = body
|
|
|
|
def set_html_body(self, body):
|
|
if "html" in self.data:
|
|
# second html body could show up through multiple alternatives,
|
|
# or html body + alternative
|
|
self.unsupported_feature("multiple html parts")
|
|
self.data["html"] = body
|
|
|
|
def add_alternative(self, content, mimetype):
|
|
if mimetype.lower() == "text/x-amp-html":
|
|
if "amp-html" in self.data:
|
|
self.unsupported_feature("multiple html parts")
|
|
self.data["amp-html"] = content
|
|
else:
|
|
super().add_alternative(content, mimetype)
|
|
|
|
def add_attachment(self, attachment):
|
|
# http://docs.python-requests.org/en/v2.4.3/user/advanced/#post-multiple-multipart-encoded-files
|
|
if attachment.inline:
|
|
field = "inline"
|
|
name = attachment.cid
|
|
if not name:
|
|
self.unsupported_feature("inline attachments without Content-ID")
|
|
else:
|
|
field = "attachment"
|
|
name = attachment.name
|
|
if not name:
|
|
self.unsupported_feature("attachments without filenames")
|
|
self.files.append((field, (name, attachment.content, attachment.mimetype)))
|
|
|
|
def set_envelope_sender(self, email):
|
|
# Only the domain is used
|
|
self.sender_domain = email.domain
|
|
|
|
def set_metadata(self, metadata):
|
|
self.metadata = metadata # save for handling merge_metadata later
|
|
for key, value in metadata.items():
|
|
self.data["v:%s" % key] = value
|
|
|
|
def set_send_at(self, send_at):
|
|
# Mailgun expects RFC-2822 format dates
|
|
# (BasePayload has converted most date-like values to datetime by now;
|
|
# if the caller passes a string, they'll need to format it themselves.)
|
|
if isinstance(send_at, datetime):
|
|
send_at = rfc2822date(send_at)
|
|
self.data["o:deliverytime"] = send_at
|
|
|
|
def set_tags(self, tags):
|
|
self.data["o:tag"] = tags
|
|
|
|
def set_track_clicks(self, track_clicks):
|
|
# Mailgun also supports an "htmlonly" option, which Anymail doesn't offer
|
|
self.data["o:tracking-clicks"] = "yes" if track_clicks else "no"
|
|
|
|
def set_track_opens(self, track_opens):
|
|
self.data["o:tracking-opens"] = "yes" if track_opens else "no"
|
|
|
|
def set_template_id(self, template_id):
|
|
self.data["template"] = template_id
|
|
|
|
def set_merge_data(self, merge_data):
|
|
# Processed at serialization time (to allow merging global data)
|
|
self.merge_data = merge_data
|
|
|
|
def set_merge_global_data(self, merge_global_data):
|
|
# Processed at serialization time (to allow merging global data)
|
|
self.merge_global_data = merge_global_data
|
|
|
|
def set_merge_metadata(self, merge_metadata):
|
|
# Processed at serialization time (to allow combining with merge_data)
|
|
self.merge_metadata = merge_metadata
|
|
|
|
def set_merge_headers(self, merge_headers):
|
|
self.merge_headers = merge_headers
|
|
|
|
def set_esp_extra(self, extra):
|
|
self.data.update(extra)
|
|
# Allow override of sender_domain via esp_extra
|
|
# (but pop it out of params to send to Mailgun)
|
|
self.sender_domain = self.data.pop("sender_domain", self.sender_domain)
|
|
|
|
|
|
def isascii(s):
|
|
"""Returns True if str s is entirely ASCII characters.
|
|
|
|
(Compare to Python 3.7 `str.isascii()`.)
|
|
"""
|
|
try:
|
|
s.encode("ascii")
|
|
except UnicodeEncodeError:
|
|
return False
|
|
return True
|
|
|
|
|
|
def flatset(iterables):
|
|
"""Return a set of the items in a single-level flattening of iterables
|
|
|
|
>>> flatset([1, 2], [2, 3])
|
|
set(1, 2, 3)
|
|
"""
|
|
return set(item for iterable in iterables for item in iterable)
|