[firestore-send-email] Add Support for List-Unsubscribe and List-Unsubscribe-Post Headers

[ognjenvucko]

[READ] Step 1: Are you in the right place?

Issues filed here should be about a feature request for a specific extension in this repository. To file a feature request that affects multiple extensions or the Firebase Extensions platform, please reach out to Firebase support directly.

[REQUIRED] Step 2: Extension name

This feature request is for extension: firestore-send-email

What feature would you like to see?

I’d like the firestore-send-email extension to support the addition of List-Unsubscribe and List-Unsubscribe-Post headers in emails sent through the extension. These headers would allow email clients like Gmail to display a prominent "Unsubscribe" button at the top of emails, improving user experience and ensuring compliance with Gmail’s 2024 bulk sender guidelines (applicable to senders of 5,000+ emails/day to Gmail addresses).

Specifically, the extension should:

1. Accept optional fields in the Firestore document written to the mail collection, such as listUnsubscribe.mailto (for an email-based unsubscribe), listUnsubscribe.http (for a URL-based unsubscribe), and listUnsubscribe.oneClick (to enable one-click unsubscribe via the List-Unsubscribe-Post header).
2. Translate these fields into the appropriate email headers when sending the email via the configured SMTP provider (e.g., Nodemailer under the hood).

For example, a user could write a document like this:

admin.firestore().collection('mail').add({
  to: '[email protected]',
  message: {
    subject: 'Newsletter Subscription',
    html: '<p>Here’s your latest update!</p>',
  },
  listUnsubscribe: {
    mailto: '[email protected]',
    http: 'https://example.com/unsubscribe?user=unique_id',
    oneClick: true,
  },
});

The extension would then generate an email with headers like:

List-Unsubscribe: <mailto:[email protected]>, <https://example.com/unsubscribe?user=unique_id>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

This change would:

• Enable Gmail’s one-click unsubscribe functionality, where clicking the button sends a POST request to the provided http URL, instantly unsubscribing the user without additional steps.
• Support the traditional mailto unsubscribe method for broader compatibility across email clients.
• Reduce spam complaints by offering an easy opt-out, improving sender reputation and deliverability.

How would you use it?

In my SaaS app, I’d use this feature to streamline email notifications and marketing campaigns sent to users, ensuring they can easily unsubscribe while maintaining compliance with Gmail’s bulk sender requirements. My app relies on Firebase for backend services, including Firestore to trigger emails like onboarding sequences, feature updates, and promotional offers via the firestore-send-email extension.

[Nushio]

This feature existed prior to https://github.com/firebase/extensions/commit/d9e485752cb25628e99ce7e06c5b3f51b9773210

We used it by setting the Headers property as such:

 createdAt: FieldValue.serverTimestamp(),
      to: [email],
      template: {
        name: templateName,
        data: { ...data, toEmail: email },
      },
      headers: {
        'X-PM-Tag': templateName,
        'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
        'List-Unsubscribe': `<mailto:[email protected]?subject=Unsubscribe>, <https://us-central1-project.cloudfunctions.net/unsubscribe?email=${email}>`,
      },
    },

However, when Sendgrid support was added, headers were accidentally (I hope?) removed from the code. We use the X-PM-Tag to figure out which Template/Tag we used on Postmark, and as a result of updating the extension, we lost this tracking/feature.

[Nushio]

Sent a PR to handle this: https://github.com/firebase/extensions/pull/2440

It's a really simple fix.

[CorieW]

Closing as should be possible with headers in version 0.2.4 (releasing today).

Thanks for reporting this issue! If you continue to experience this problem, or have any further problems, feel free to open a new issue!