Scaleway: new ESP

Add support for Scaleway Transactional Email backend.

(Tracking webhooks will be added separately, later.)

---------

Co-authored-by: Mike Edmunds <[email protected]>

Author: hleroy

CHANGELOG.rst

@@ -33,6 +33,10 @@ vNext
 Features
 ~~~~~~~~
 
+* **Scaleway:** Add support for this ESP.
+  (See `docs <https://anymail.dev/en/latest/esps/scaleway/>`__.
+  Thanks to `@hleroy`_ for the contribution.)
+
 * **SendGrid:** Add optional signature verification for tracking webhooks.
   To support this, Anymail now includes the :pypi:`cryptography` package when
   installed with the ``django-anymail[sendgrid]`` extra.
@@ -1832,6 +1836,7 @@ Features
 .. _@fdemmer: https://github.com/fdemmer
 .. _@Flexonze: https://github.com/Flexonze
 .. _@gdvalderrama: https://github.com/gdvalderrama
+.. _@hleroy: https://github.com/hleroy
 .. _@Honza-m: https://github.com/Honza-m
 .. _@izimobil: https://github.com/izimobil
 .. _@janneThoft: https://github.com/janneThoft

README.rst

@@ -35,6 +35,7 @@ Anymail currently supports these ESPs:
 * **Postal** (self-hosted ESP)
 * **Postmark** (ActiveCampaign transactional email)
 * **Resend**
+* **Scaleway TEM**
 * **SendGrid** (Twilio transactional email; no longer tested)
 * **SparkPost** (Bird transactional email)
 * **Unisender Go**

anymail/backends/scaleway.py

@@ -0,0 +1,170 @@
+from urllib.parse import quote
+
+from ..exceptions import AnymailAPIError
+from ..message import AnymailRecipientStatus
+from ..utils import get_anymail_setting
+from .base_requests import AnymailRequestsBackend, RequestsPayload
+
+
+class EmailBackend(AnymailRequestsBackend):
+    """
+    Scaleway Transactional Email API Backend
+    """
+
+    esp_name = "Scaleway"
+
+    def __init__(self, **kwargs):
+        """Init options from Django settings"""
+        esp_name = self.esp_name
+        self.secret_key = get_anymail_setting(
+            "secret_key", esp_name=esp_name, kwargs=kwargs, allow_bare=True
+        )
+        self.project_id = get_anymail_setting(
+            "project_id", esp_name=esp_name, kwargs=kwargs
+        )
+        region = get_anymail_setting(
+            "region", esp_name=esp_name, kwargs=kwargs, default="fr-par"
+        )
+        api_url_template = get_anymail_setting(
+            "api_url",
+            esp_name=esp_name,
+            kwargs=kwargs,
+            default=(
+                "https://api.scaleway.com/transactional-email/v1alpha1/regions/{region}/"
+            ),
+        )
+        api_url = api_url_template.format(region=quote(region, safe=""))
+        if not api_url.endswith("/"):
+            api_url += "/"
+        super().__init__(api_url, **kwargs)
+
+    def build_message_payload(self, message, defaults):
+        return ScalewayPayload(message, defaults, self)
+
+    _recipient_status_map = {
+        # Scaleway send status -> Anymail status.
+        # (In practice, only "sending" seems to be reported.
+        # Invalid addresses cause an API failure.
+        # Blocked addresses show as "sending" and are rejected later.)
+        "unknown": "unknown",
+        "new": "queued",
+        "sending": "queued",
+        "sent": "sent",
+        "failed": "failed",
+        "canceled": "failed",
+    }
+
+    def parse_recipient_status(self, response, payload, message):
+        parsed_response = self.deserialize_json_response(response, payload, message)
+        statuses = {}
+        try:
+            emails = parsed_response["emails"]
+        except (KeyError, TypeError):
+            raise AnymailAPIError(
+                "Invalid response from Scaleway API",
+                email_message=message,
+                payload=payload,
+                response=response,
+                backend=self,
+            )
+
+        for email_info in emails:
+            recipient = email_info.get("mail_rcpt")
+            message_id = email_info.get("id")
+            status = email_info.get("status")
+            anymail_status = AnymailRecipientStatus(
+                message_id=message_id,
+                status=self._recipient_status_map.get(status, "unknown"),
+            )
+            if recipient:
+                statuses[recipient] = anymail_status
+        return statuses
+
+
+class ScalewayPayload(RequestsPayload):
+    def __init__(self, message, defaults, backend, *args, **kwargs):
+        self.project_id = backend.project_id
+        http_headers = kwargs.pop("headers", {})
+        http_headers["X-Auth-Token"] = backend.secret_key
+        http_headers["Content-Type"] = "application/json"
+        super().__init__(
+            message, defaults, backend, headers=http_headers, *args, **kwargs
+        )
+
+    def get_api_endpoint(self):
+        return "emails"
+
+    def init_payload(self):
+        self.data = {
+            "project_id": self.project_id,
+        }
+
+    def _scaleway_email(self, email):
+        """Expand an Anymail EmailAddress into Scaleway's {"email", "name"} dict"""
+        result = {"email": email.addr_spec}
+        if email.display_name:
+            result["name"] = email.display_name
+        return result
+
+    def set_from_email(self, email):
+        self.data["from"] = self._scaleway_email(email)
+
+    def set_recipients(self, recipient_type, emails):
+        assert recipient_type in {"to", "cc", "bcc"}
+        if emails:
+            self.data[recipient_type] = [
+                self._scaleway_email(email) for email in emails
+            ]
+
+    def set_subject(self, subject):
+        if subject:
+            self.data["subject"] = subject
+
+    def set_text_body(self, body):
+        if body:
+            self.data["text"] = body
+
+    def set_html_body(self, html):
+        if html:
+            self.data["html"] = html
+
+    def add_attachment(self, attachment):
+        if attachment.inline:
+            self.unsupported_feature("inline attachments")
+        self.data.setdefault("attachments", []).append(
+            {
+                "name": attachment.name,
+                "type": attachment.mimetype,
+                "content": attachment.b64content,
+            }
+        )
+
+    def set_extra_headers(self, headers):
+        self.data.setdefault("additional_headers", []).extend(
+            [{"key": key, "value": str(value)} for key, value in headers.items()]
+        )
+
+    def set_reply_to(self, emails):
+        if emails:
+            reply_to_string = ", ".join([str(email) for email in emails])
+            self.data.setdefault("additional_headers", []).append(
+                {"key": "Reply-To", "value": reply_to_string}
+            )
+
+    def set_tags(self, tags):
+        if tags:
+            self.data.setdefault("additional_headers", []).append(
+                {"key": "X-Tags", "value": self.serialize_json(tags)}
+            )
+
+    def set_metadata(self, metadata):
+        if metadata:
+            self.data.setdefault("additional_headers", []).append(
+                {"key": "X-Metadata", "value": self.serialize_json(metadata)}
+            )
+
+    def set_esp_extra(self, extra):
+        self.data.update(extra)
+
+    def serialize_data(self):
+        return self.serialize_json(self.data)

docs/esps/esp-feature-matrix.csv

@@ -1,21 +1,21 @@
-Email Service Provider,:ref:`amazon-ses-backend`,:ref:`brevo-backend`,:ref:`mailersend-backend`,:ref:`mailgun-backend`,:ref:`mailjet-backend`,:ref:`mandrill-backend`,:ref:`postal-backend`,:ref:`postmark-backend`,:ref:`resend-backend`,:ref:`sendgrid-backend`,:ref:`sparkpost-backend`,:ref:`unisender-go-backend`
-Anymail support status [#support-status]_,Full,Full,Full,Full,Full,Limited,Limited,Full,Full,**Unsupported**,Full,Full
-.. rubric:: :ref:`Anymail send options <anymail-send-options>`,,,,,,,,,,,,
-:attr:`~AnymailMessage.envelope_sender`,Yes,No,No,Domain only,Yes,Domain only,Yes,No,No,No,Yes,No
-:attr:`~AnymailMessage.merge_headers`,Yes [#caveats]_,Yes,No,Yes,Yes,No,No,Yes,Yes,Yes,Yes [#caveats]_,Yes [#caveats]_
-:attr:`~AnymailMessage.metadata`,Yes,Yes,No,Yes,Yes,Yes,No,Yes,Yes,Yes,Yes,Yes
-:attr:`~AnymailMessage.merge_metadata`,Yes [#caveats]_,Yes,No,Yes,Yes,Yes,No,Yes,Yes,Yes,Yes,Yes
-:attr:`~AnymailMessage.send_at`,No,Yes,Yes,Yes,No,Yes,No,No,Yes,Yes,Yes,Yes
-:attr:`~AnymailMessage.tags`,Yes,Yes,Yes,Yes,Max 1 tag,Yes,Max 1 tag,Max 1 tag,Yes,Yes,Max 1 tag,Yes
-:attr:`~AnymailMessage.track_clicks`,No [#nocontrol]_,No [#nocontrol]_,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
-:attr:`~AnymailMessage.track_opens`,No [#nocontrol]_,No [#nocontrol]_,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
-:ref:`amp-email`,Yes,No,No,Yes,No,No,No,No,No,Yes,Yes,Yes
-.. rubric:: :ref:`templates-and-merge`,,,,,,,,,,,,
-:attr:`~AnymailMessage.template_id`,Yes,Yes,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
-:attr:`~AnymailMessage.merge_data`,Yes [#caveats]_,Yes,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
-:attr:`~AnymailMessage.merge_global_data`,Yes [#caveats]_,Yes,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
-.. rubric:: :ref:`Status <esp-send-status>` and :ref:`event tracking <event-tracking>`,,,,,,,,,,,,
-:attr:`~AnymailMessage.anymail_status`,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes
-:class:`~anymail.signals.AnymailTrackingEvent` from webhooks,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes
-.. rubric:: :ref:`Inbound handling <inbound>`,,,,,,,,,,,,
-:class:`~anymail.signals.AnymailInboundEvent` from webhooks,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,No,Yes,Yes,No
+Email Service Provider,:ref:`amazon-ses-backend`,:ref:`brevo-backend`,:ref:`mailersend-backend`,:ref:`mailgun-backend`,:ref:`mailjet-backend`,:ref:`mandrill-backend`,:ref:`postal-backend`,:ref:`postmark-backend`,:ref:`resend-backend`,:ref:`scaleway-backend`,:ref:`sendgrid-backend`,:ref:`sparkpost-backend`,:ref:`unisender-go-backend`
+Anymail support status [#support-status]_,Full,Full,Full,Full,Full,Limited,Limited,Full,Full,Full,**Unsupported**,Full,Full
+.. rubric:: :ref:`Anymail send options <anymail-send-options>`,,,,,,,,,,,,,
+:attr:`~AnymailMessage.envelope_sender`,Yes,No,No,Domain only,Yes,Domain only,Yes,No,No,No,No,Yes,No
+:attr:`~AnymailMessage.merge_headers`,Yes [#caveats]_,Yes,No,Yes,Yes,No,No,Yes,Yes,No,Yes,Yes [#caveats]_,Yes [#caveats]_
+:attr:`~AnymailMessage.metadata`,Yes,Yes,No,Yes,Yes,Yes,No,Yes,Yes,Yes,Yes,Yes,Yes
+:attr:`~AnymailMessage.merge_metadata`,Yes [#caveats]_,Yes,No,Yes,Yes,Yes,No,Yes,Yes,No,Yes,Yes,Yes
+:attr:`~AnymailMessage.send_at`,No,Yes,Yes,Yes,No,Yes,No,No,Yes,No,Yes,Yes,Yes
+:attr:`~AnymailMessage.tags`,Yes,Yes,Yes,Yes,Max 1 tag,Yes,Max 1 tag,Max 1 tag,Yes,Yes,Yes,Max 1 tag,Yes
+:attr:`~AnymailMessage.track_clicks`,No [#nocontrol]_,No [#nocontrol]_,Yes,Yes,Yes,Yes,No,Yes,No,No,Yes,Yes,Yes
+:attr:`~AnymailMessage.track_opens`,No [#nocontrol]_,No [#nocontrol]_,Yes,Yes,Yes,Yes,No,Yes,No,No,Yes,Yes,Yes
+:ref:`amp-email`,Yes,No,No,Yes,No,No,No,No,No,No,Yes,Yes,Yes
+.. rubric:: :ref:`templates-and-merge`,,,,,,,,,,,,,
+:attr:`~AnymailMessage.template_id`,Yes,Yes,Yes,Yes,Yes,Yes,No,Yes,No,No,Yes,Yes,Yes
+:attr:`~AnymailMessage.merge_data`,Yes [#caveats]_,Yes,Yes,Yes,Yes,Yes,No,Yes,No,No,Yes,Yes,Yes
+:attr:`~AnymailMessage.merge_global_data`,Yes [#caveats]_,Yes,Yes,Yes,Yes,Yes,No,Yes,No,No,Yes,Yes,Yes
+.. rubric:: :ref:`Status <esp-send-status>` and :ref:`event tracking <event-tracking>`,,,,,,,,,,,,,
+:attr:`~AnymailMessage.anymail_status`,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes
+:class:`~anymail.signals.AnymailTrackingEvent` from webhooks,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Not yet,Yes,Yes,Yes
+.. rubric:: :ref:`Inbound handling <inbound>`,,,,,,,,,,,,,
+:class:`~anymail.signals.AnymailInboundEvent` from webhooks,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,No,No,Yes,Yes,No

docs/esps/index.rst

@@ -21,6 +21,7 @@ and notes about any quirks or limitations:
    postal
    postmark
    resend
+   scaleway
    sendgrid
    sparkpost
    unisender_go