The Differences In Sending Email Actions Between SES Version 1 and Version 2 APIs
Tags: ses, aws, amazon
Published: 2023-08-07 03:05:28

If you have been using Amazon SES service for a while, it might not be new to you that Amazon SES is having two versions of API actions available at the moment, [API Reference (version 1)](https://docs.aws.amazon.com/ses/latest/APIReference/index.html) and [API v2 Reference](https://docs.aws.amazon.com/ses/latest/APIReference-V2/index.html). I tried to find the announcement of the API v2 in [What's New with AWS?](https://aws.amazon.com/new/?whats-new-content-all.sort-by=item.additionalFields.postDateTime&whats-new-content-all.sort-order=desc&awsf.whats-new-categories=*all&whats-new-content-all.q=ses&whats-new-content-all.q_operator=AND&awsm.page-whats-new-content-all=3) page but I did not have the luck. 

Amazon SES service API calls can be separated into two types:
 - Management API actions, which can be recorded in [CloudTrail Event History](https://docs.aws.amazon.com/ses/latest/dg/logging-using-cloudtrail.html#service-name-info-in-cloudtrail)
 - Sending API actions, which are not recorded in [CloudTrail Event History](https://docs.aws.amazon.com/ses/latest/dg/logging-using-cloudtrail.html#service-name-info-in-cloudtrail)

In this article, you will read about how I took a peek at the sending API actions in Amazon SES API v1 and v2.

1. What are these API actions?

I can find the API action names in SES API documents. But I find that I can also get the list of API calls by creating an example IAM policy from IAM console. 

Here is the list of actions I got when I was creating an IAM policy with service name 'SES' and 'SES v2' from IAM console.

- v1 IAM actions
> "Action": [
                "ses:SendBounce",
                "ses:SendBulkTemplatedEmail",
                "ses:SendCustomVerificationEmail",
                "ses:SendEmail",
                "ses:SendRawEmail",
                "ses:SendTemplatedEmail"
            ]

- v2 IAM actions
>"Action": [
                "ses:SendBulkEmail",
                "ses:SendCustomVerificationEmail",
                "ses:SendEmail"
            ]

2. What are the differences?

I used SES SDK Boto3 Document in the following comparison.

- To use Amazon SES v2 APIs, the service client must be ```boto3.client('sesv2')```

- SES v2 API ["SendEmail"](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sesv2/client/send_email.html) provides the same functions in v1 APIs ["SendEmail"](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ses/client/send_email.html), ["SendRawEmail"](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ses/client/send_raw_email.html) and ["SendTemplatedEmail"](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ses/client/send_templated_email.html). But only the API ["SendEmail"](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sesv2/client/send_email.html) in SES v2 supports the feature ["list management"](https://docs.aws.amazon.com/ses/latest/dg/sending-email-list-management.html). List Management can help to reduce the chance of get complaints or even hard bounces by sending emails to recipients who have opted out of their previous subscriptions to some email services, e.g. newsletter email.

- SES v2 API ["SendBulkEmail"](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sesv2/client/send_bulk_email.html) has different names of parameters in sending requests with SES v1 ["SendBulkTemplatedEmail"](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ses/client/send_bulk_templated_email.html). But values of those parameters should be no difference. 

- SES v2 API action ["SendCustomVerificationEmail"](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sesv2/client/send_custom_verification_email.html) has no difference with the [action](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ses/client/send_custom_verification_email.html) in SES v1 API.

- SES v2 API actions do not have a definition of action "SendBounce". The action ["SendBounce"](https://docs.aws.amazon.com/ses/latest/APIReference/API_SendBounce.html) is used to generate and send a bounce message to the sender of an email which I received through Amazon SES. There is a restriction that we can only use this API action on an email up to 24 hours after receiving it.

3. How do I restrict usage in SES API v1 and v2? 

SES public document has given an example about ["Allowing Access to only SES API version 2"](https://docs.aws.amazon.com/ses/latest/dg/control-user-access.html#iam-and-ses-examples-access-specific-ses-api-version). Relatively, I could modify the condition forcing to use SES API v1. 

Why would I want to do that? One thing in the same document could provide an answer: ```The SES SMTP interface uses SES API version 2 of ses:SendRawEmail.```

As an IAM user can [convert AWS credentials into SMTP username and password](https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html#smtp-credentials-convert), I can use the trick to restrict the IAM user to use or not use SMTP client to send emails through Amazon SES.

4. One more difference is the [message size](https://docs.aws.amazon.com/ses/latest/dg/quotas.html#quotas-message) between using SES API v1 and v2. While size of message (after base64 encoding and including attachments) is 10 MB using SES API v1, the size is 40MB in SES API v2.