New feature: per-recipient merge_headers

Question

New feature: per-recipient merge_headers

medmunds opened this issue 2 months ago · comments

Several ESPs' batch send APIs allow specifying different email headers for individual recipients. Anymail should add a new merge_headers message option providing normalized support for this feature:

message = AnymailMessage(
    to=["alice@example.com", "Bob <bob@example.com>"],
    ...,
    # Common headers for all recipients:
    headers={
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
    },
    # Recipient-specific headers:
    merge_headers={
        "alice@example.com": {
            "List-Unsubscribe": "<https://example.com/unsubscribe/98765abc>",
        },
        "bob@example.com": {
            "List-Unsubscribe": "<https://example.com/unsubscribe/12345xyz>", 
        },
    },
)

As the example shows, this is particularly useful for List-Unsubscribe headers that include a token identifying the recipient. The new merge_headers property is meant to parallel Anymail's existing merge_metadata and merge_data.

[Edit: updated info on supported ESPs]

Can support merge_headers:

Amazon SES (only works with template API)
Brevo
Mailgun (using recipient-variables substitutions)
Mailjet
Postmark
Resend
SendGrid
SparkPost (using substitutions)
Unisender Go (using substitutions, for List-Unsubscribe header only)

Cannot support merge_headers:

MailerSend (substitutions from "personalizations" don't apply to headers, based on testing)
Mandrill ("Merge tags can't be included in custom … headers")
Postal (no batch send support)

In addition to providing the idea, @carrerasrodrigo has already implemented the base and Amazon SES support in #371. (Thanks!)