add support for SESv2 under feature flag (django-ses#269)

* add support for SESv2 under feature flag

* update poetry version

* fix send quota

* update docs

* add docstrings

* remove test comment

Co-authored-by: Fergus Dixon <[email protected]>

Author: pcraciunoiu

CHANGES.md

@@ -7,10 +7,10 @@ For a list of releases, see: https://github.com/django-ses/django-ses/releases/
 The following changes are not yet released, but are code complete:
 
 Pulls and Issues:
- - None
+ - https://github.com/django-ses/django-ses/pull/267
 
 Features:
-- None
+- Experimental SESv2 Client under feature flag
 
 Changes:
 - None

README.rst

@@ -79,6 +79,9 @@ Add the following to your settings.py::
     AWS_SES_REGION_NAME = 'us-west-2'
     AWS_SES_REGION_ENDPOINT = 'email.us-west-2.amazonaws.com'
 
+    # If you want to use the SESv2 client
+    USE_SES_V2 = True
+
 Alternatively, instead of `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, you
 can include the following two settings values. This is useful in situations
 where you would like to use a separate access key to send emails via SES than

django_ses/__init__.py

@@ -62,6 +62,7 @@ def __init__(self, fail_silently=False, aws_access_key=None,
                  aws_region_endpoint=None, aws_auto_throttle=None, aws_config=None,
                  dkim_domain=None, dkim_key=None, dkim_selector=None, dkim_headers=None,
                  ses_source_arn=None, ses_from_arn=None, ses_return_path_arn=None,
+                 use_ses_v2=False,
                  **kwargs):
 
         super(SESBackend, self).__init__(fail_silently=fail_silently, **kwargs)
@@ -82,6 +83,8 @@ def __init__(self, fail_silently=False, aws_access_key=None,
         self.ses_from_arn = ses_from_arn or settings.AWS_SES_FROM_ARN
         self.ses_return_path_arn = ses_return_path_arn or settings.AWS_SES_RETURN_PATH_ARN
 
+        self._use_ses_v2 = use_ses_v2 or settings.USE_SES_V2
+
         self.connection = None
 
     def open(self):
@@ -93,7 +96,7 @@ def open(self):
 
         try:
             self.connection = boto3.client(
-                'ses',
+                'sesv2' if self._use_ses_v2 else 'ses',
                 aws_access_key_id=self._access_key_id,
                 aws_secret_access_key=self._access_key,
                 aws_session_token=self._session_token,
@@ -154,66 +157,14 @@ def send_messages(self, email_messages):
             # well below the actual SES throttle.
             # Set the setting to 0 or None to disable throttling.
             if self._throttle:
-                global recent_send_times
-
-                now = datetime.now()
-
-                # Get and cache the current SES max-per-second rate limit
-                # returned by the SES API.
-                rate_limit = self.get_rate_limit()
-                logger.debug("send_messages.throttle rate_limit='{}'".format(rate_limit))
-
-                # Prune from recent_send_times anything more than a few seconds
-                # ago. Even though SES reports a maximum per-second, the way
-                # they enforce the limit may not be on a one-second window.
-                # To be safe, we use a two-second window (but allow 2 times the
-                # rate limit) and then also have a default rate limit factor of
-                # 0.5 so that we really limit the one-second amount in two
-                # seconds.
-                window = 2.0  # seconds
-                window_start = now - timedelta(seconds=window)
-                new_send_times = []
-                for time in recent_send_times:
-                    if time > window_start:
-                        new_send_times.append(time)
-                recent_send_times = new_send_times
-
-                # If the number of recent send times in the last 1/_throttle
-                # seconds exceeds the rate limit, add a delay.
-                # Since I'm not sure how Amazon determines at exactly what
-                # point to throttle, better be safe than sorry and let in, say,
-                # half of the allowed rate.
-                if len(new_send_times) > rate_limit * window * self._throttle:
-                    # Sleep the remainder of the window period.
-                    delta = now - new_send_times[0]
-                    total_seconds = (delta.microseconds + (delta.seconds +
-                                     delta.days * 24 * 3600) * 10**6) / 10**6
-                    delay = window - total_seconds
-                    if delay > 0:
-                        sleep(delay)
-
-                recent_send_times.append(now)
-                # end of throttling
-
-            kwargs = dict(
-                Source=source or message.from_email,
-                Destinations=message.recipients(),
-                # todo attachments?
-                RawMessage={'Data': dkim_sign(message.message().as_string(),
-                                              dkim_key=self.dkim_key,
-                                              dkim_domain=self.dkim_domain,
-                                              dkim_selector=self.dkim_selector,
-                                              dkim_headers=self.dkim_headers)}
-            )
-            if self.ses_source_arn:
-                kwargs['SourceArn'] = self.ses_source_arn
-            if self.ses_from_arn:
-                kwargs['FromArn'] = self.ses_from_arn
-            if self.ses_return_path_arn:
-                kwargs['ReturnPathArn'] = self.ses_return_path_arn
+                self._update_throttling()
+
+            kwargs = self._get_send_email_parameters(message, source)
 
             try:
-                response = self.connection.send_raw_email(**kwargs)
+                response = (self.connection.send_email(**kwargs)
+                            if self._use_ses_v2
+                            else self.connection.send_raw_email(**kwargs))
                 message.extra_headers['status'] = 200
                 message.extra_headers['message_id'] = response['MessageId']
                 message.extra_headers['request_id'] = response['ResponseMetadata']['RequestId']
@@ -250,6 +201,94 @@ def send_messages(self, email_messages):
 
         return num_sent
 
+    def _update_throttling(self):
+        global recent_send_times
+        now = datetime.now()
+        # Get and cache the current SES max-per-second rate limit
+        # returned by the SES API.
+        rate_limit = self.get_rate_limit()
+        logger.debug("send_messages.throttle rate_limit='{}'".format(rate_limit))
+        # Prune from recent_send_times anything more than a few seconds
+        # ago. Even though SES reports a maximum per-second, the way
+        # they enforce the limit may not be on a one-second window.
+        # To be safe, we use a two-second window (but allow 2 times the
+        # rate limit) and then also have a default rate limit factor of
+        # 0.5 so that we really limit the one-second amount in two
+        # seconds.
+        window = 2.0  # seconds
+        window_start = now - timedelta(seconds=window)
+        new_send_times = []
+        for time in recent_send_times:
+            if time > window_start:
+                new_send_times.append(time)
+        recent_send_times = new_send_times
+        # If the number of recent send times in the last 1/_throttle
+        # seconds exceeds the rate limit, add a delay.
+        # Since I'm not sure how Amazon determines at exactly what
+        # point to throttle, better be safe than sorry and let in, say,
+        # half of the allowed rate.
+        if len(new_send_times) > rate_limit * window * self._throttle:
+            # Sleep the remainder of the window period.
+            delta = now - new_send_times[0]
+            total_seconds = (delta.microseconds + (delta.seconds +
+                                                   delta.days * 24 * 3600) * 10 ** 6) / 10 ** 6
+            delay = window - total_seconds
+            if delay > 0:
+                sleep(delay)
+        recent_send_times.append(now)
+        # end of throttling
+
+    def _get_send_email_parameters(self, message, source):
+        return (self._get_v2_parameters(message, source)
+                if self._use_ses_v2
+                else self._get_v1_parameters(message, source))
+
+    def _get_v2_parameters(self, message, source):
+        """V2-Style raw payload for `send_email`.
+
+        https://boto3.amazonaws.com/v1/documentation/api/1.26.31/reference/services/sesv2.html#SESV2.Client.send_email
+        """
+        params = dict(
+            FromEmailAddress=source or message.from_email,
+            Destination={
+                'ToAddresses': message.recipients()
+            },
+            Content={
+                'Raw': {
+                    'Data': dkim_sign(message.message().as_string(),
+                                      dkim_key=self.dkim_key,
+                                      dkim_domain=self.dkim_domain,
+                                      dkim_selector=self.dkim_selector,
+                                      dkim_headers=self.dkim_headers)
+                }
+            }
+        )
+        if self.ses_from_arn or self.ses_source_arn:
+            params['FromEmailAddressIdentityArn'] = self.ses_from_arn or self.ses_source_arn
+        return params
+
+    def _get_v1_parameters(self, message, source):
+        """V1-Style raw payload for `send_raw_email`
+
+        https://boto3.amazonaws.com/v1/documentation/api/1.26.31/reference/services/ses.html#SES.Client.send_raw_email
+        """
+        params = dict(
+            Source=source or message.from_email,
+            Destinations=message.recipients(),
+            RawMessage={'Data': dkim_sign(message.message().as_string(),
+                                          dkim_key=self.dkim_key,
+                                          dkim_domain=self.dkim_domain,
+                                          dkim_selector=self.dkim_selector,
+                                          dkim_headers=self.dkim_headers)}
+        )
+        if self.ses_source_arn:
+            params['SourceArn'] = self.ses_source_arn
+        if self.ses_from_arn:
+            params['FromArn'] = self.ses_from_arn
+        if self.ses_return_path_arn:
+            params['ReturnPathArn'] = self.ses_return_path_arn
+        return params
+
     def get_rate_limit(self):
         if self._access_key_id in cached_rate_limits:
             return cached_rate_limits[self._access_key_id]
@@ -259,11 +298,26 @@ def get_rate_limit(self):
             raise Exception(
                 "No connection is available to check current SES rate limit.")
         try:
-            quota_dict = self.connection.get_send_quota()
-            max_per_second = quota_dict['MaxSendRate']
-            ret = float(max_per_second)
-            cached_rate_limits[self._access_key_id] = ret
-            return ret
+            return self._get_v2_send_quota() if self._use_ses_v2 else self._get_v1_send_quota()
         finally:
             if new_conn_created:
                 self.close()
+
+    def _get_v2_send_quota(self):
+        """This needs to come from the `get_account` endpoint as a nested response in V2.
+
+        https://boto3.amazonaws.com/v1/documentation/api/1.26.31/reference/services/sesv2.html#SESV2.Client.get_account
+        """
+        account_dict = self.connection.get_account()
+        quota_dict = account_dict['SendQuota']
+        max_per_second = quota_dict['MaxSendRate']
+        ret = float(max_per_second)
+        cached_rate_limits[self._access_key_id] = ret
+        return ret
+
+    def _get_v1_send_quota(self):
+        quota_dict = self.connection.get_send_quota()
+        max_per_second = quota_dict['MaxSendRate']
+        ret = float(max_per_second)
+        cached_rate_limits[self._access_key_id] = ret
+        return ret

django_ses/settings.py

@@ -37,6 +37,8 @@
 AWS_SES_FROM_ARN = getattr(settings, 'AWS_SES_FROM_ARN', None)
 AWS_SES_RETURN_PATH_ARN = getattr(settings, 'AWS_SES_RETURN_PATH_ARN', None)
 
+USE_SES_V2 = getattr(settings, 'USE_SES_V2', False)
+
 TIME_ZONE = settings.TIME_ZONE
 
 VERIFY_EVENT_SIGNATURES = getattr(settings, 'AWS_SES_VERIFY_EVENT_SIGNATURES',