Add custom headers support to SES sendBulkTemplatedEmail

[chrisc0]

Describe the feature

I need to be able to add custom email headers while sending out hundreds (potentially thousands) of emails at a time using the SES sendBulkTemplatedEmail command but it doesn't currently seem possible.

Use Case

I need to be able to add custom email headers while sending out hundreds (potentially thousands) of emails at a time using the SES sendBulkTemplatedEmail command but it doesn't currently seem possible.

Proposed Solution

No response

Other Information

No response

Acknowledgements

• [ ] I may be able to implement this feature request
• [ ] This feature might incur a breaking change

SDK version used

latest

Environment details (Version of PHP (php -v)? OS name and version, etc.)

php 8.1.2, Ubuntu 22.04

[nicodemuz]

Below quotes are from the recent AWS article:

"In a move to safeguard user inboxes, Gmail and Yahoo Mail announced a new set of requirements for senders effective from February 2024."

2. Set up an easy unsubscribe for email recipients Bulk senders are expected to include a mechanism to unsubscribe by adding an easy to find link within the message. The February 2024 mailbox provider rules will require senders to additionally add one-click unsubscribe headers as defined by RFC 2369 and RFC 8058. These headers make it easier for recipients to unsubscribe, which reduces the rate at which recipients will complain by marking messages as spam.

To set up one-click unsubscribe without using the SES subscription management feature, include both of these headers in outgoing messages:

List-Unsubscribe-Post: List-Unsubscribe=One-Click List-Unsubscribe: https://example.com/unsubscribe/example

How can we use sendBulkTemplatedEmail API to add List-Unsubscribe-Post and List-Unsubscribe headers? With a quick look at the API documentation, I don't see any ways to add these headers. We do not wish to use SES subscription management feature as we already have our subscription management page where the user can unsubscribe.

Going forward, this seems like an essential feature that needs to be supported.

[DevKishan]

Going forward, this seems like an essential feature that needs to be supported.

Yes, this is indeed a necessary feature when sending emails to subscribers in bulk. Without this, we are forced to send emails one subscriber at a time since it is not possible to add the List-Unsubscribe custom header through API_SendBulkTemplatedEmail API. This point in this SES doc further confirms it.

Other competitor ESPs like Sendgrid, Mailgun do provide the option to add List-Unsubscribe and List-Unsubscribe-Post headers in bulk mode as well.

[HashimHaider]

Any update on this? Given the recent bulk sender changes at Yahoo/Gmail (dated February, 2024), we need the List-Unsubscribe header more than ever. https://aws.amazon.com/blogs/messaging-and-targeting/an-overview-of-bulk-sender-changes-at-yahoo-gmail/

[gileri]

In a support ticket related to this bulk sender policy changes, the AWS representative said that something was cooking internally in order to support adding List-Unsubscribe headers in bulk-sending SES API calls. No specifics or planned release date as usual.

[kaaaaaaaaaaai]

same response

[serbanveres]

+1

[TomWaterz]

Any update on this?

[yenfryherrerafeliz]

Internal ticket: V1467804965

[yenfryherrerafeliz]

Hi @chrisc0, @nicodemuz, @DevKishan, @HashimHaider, @gileri, @kaaaaaaaaaaai, @serbanveres, @TomWaterz, sorry for the delay on answering here. Since this is a limitation from the service itself there is nothing we can do from an SDK perspective, however, I have opened a ticket with them and I have forward your pain points and why this is needed based on your sentiments.

I will be awaiting a response from the service and I will make sure to place further updates here.

Thanks!

[yenfryherrerafeliz]

Hi @chrisc0, @nicodemuz, @DevKishan, @HashimHaider, @gileri, @kaaaaaaaaaaai, @serbanveres, @TomWaterz!

I just got back from the service and it looks like this functionality is already present in the V2 API of SES. Please use the SESV2Client instead of SESClient and you should be able to provide custom headers.

Here is the doc: https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendBulkEmail.html

Please let me know if that helps or if you have any comments or questions.

Thanks.

[github-actions[bot]]

This issue has not received a response in a while. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.

[boehs]

I'm calling https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendBulkEmail.html#API_SendBulkEmail_RequestSyntax, to it I passed the following:

{
"FromEmailAddress": "\"xxx Notifications\" <mailer@xxx.org>",
"DefaultContent": {
  "Template": {
    "TemplateName": "xxx",
  }
},
"BulkEmailEntries": [
  {
    "Destination": {
      "ToAddresses": [
        "<email>"
      ]
    },
    "ReplacementEmailContent": {
      "RepacementTemplate": {
        "ReplacementTemplateData": "{\"uuid\":\"939e7050936b4e41b8be5ac2752d1b74\"}"
      }
    },
    "ReplacementHeaders": [
      {
        "Name": "List-Unsubscribe",
        "Value": "<https://xxx.org/api/unsubscribe/939e7050936b4e41b8be5ac2752d1b74>"
      },
      {
        "Name": "List-Unsubscribe-Post",
        "Value": "List-Unsubscribe=One-Click"
      }
    ]
  }
]
}

however, I was getting template rendering errors, so I tried

DefaultContent: {
  Template: {
    TemplateName: template,
    TemplateData: JSON.stringify({
      uuid: "0",
    }),
  },
},

And this fixed the render errors, but UUID was set to "0" in the emails that were sent.

I've checked about a million times to ensure I'm following the docs and it all looks good, but it just won't work. The only other complaint I could find was here and its unresolved.

Any ideas?

[ashishdhingra]

@boehs Per TemplateData, it is An object that defines the values to use for message variables in the template. This object is a set of key-value pairs. Each key defines a message variable in the template. The corresponding value defines the value to use for that variable.. It replaces the message variable in template, not the headers.

You could try using ReplacementHeaders for your scenario to replace headers in the individual BulkEmailEntry objects.

Thanks, Ashish

[boehs]

@ashishdhingra I'm not trying to replace headers, well I'm trying to do that too, but I believe there's a bug in this API where ReplacementTemplateData does not work, so in order to replace headers per-email, I still need to be sending emails individually because another feature I need doesn't appear to be working as intended. See the re:post thread I linked above.