Setup Unsubscribe with SendGrid API & Dynamic Templates

This tutorial is based on what we were building at LifeMetrics circa 2020

We all want to grow our email lists and make it as easy as possible to subscribe, but it is almost as important to make sure we let people unsubscribe just as easily. Both because we’ve received annoying emails that are difficult to stop before and we don’t want to be annoying and because we don’t want to be reported as spam when a person can’t find how to unsubscribe from our emails.

But for some reason SendGrid documentation makes this somewhat convoluted. So here’s how to do this explained simply.

There are two ways we can handle un-subscriptions when sending emails through SendGrid’s API. You can also use both at the same time.

1. Global Unsubscribe — A single unsubscribe link to never receive any emails from you ever!
2. Unsubscribe Groups — Different groupings of emails so that a person can unsubscribe from some emails (e.g. Marketing), but still receive others (e.g. Updates). Or they can still unsubscribe from all groups.

Global Unsubscribe

This method uses Subscription Tracking. You need to enable this in the SendGrid dashboard under Settings — Tracking.

The Tracking Settings page

We need to enable Subscription Tracking. This is technically enough, but this will simply add a very ugly footer onto the bottom of all our emails.

the very ugly footer

To change this to something nicer we are going to modify the subscription tracking settings. We will create a unique replacement tag. In this case [unsubscribe]. We will use this in our dynamic template as the url for our Unsubscribe button. What this means in practice is that we need to modify an a tag in html to look something like: href="[unsubscribe]" (Thanks to Josh for suggesting this clarification!)

You can also edit the appended footer here, but this still limits how we display this content so I still prefer to use it in a replacement tag; however, if you forget to include the replacement tag in your template this footer will be automatically appended.

When someone clicks on the unsubscribe link now they will be taken to a generic unsubscribed successfully page (you can instead point it to your own page in the Subscription Tracking settings) and added to a global unsubscribe list. Even if you try to send an email to them it will not be received by this person now.

Just some plain html goodness for the default page

Unsubscribe Groups

If you want some more fine-grained controls you can create and manage unsubscribe groups. You can access these through the dashboard by way of Marketing — Unsubscribe Groups.

It’ll look like this at first.

Simply create some groups here for the types of emails you will be sending. A sample of groups might be Transactional, Marketing, and Update. So if a user wants to receive product update emails but doesn't want to be marketed at they have that option.

After you have created some groups we can go to our dynamic templates and use the design editor to add a Unsubscribe module to our template. This unsubscribe module will automatically include the info we need If you don’t want to use the designer editor you can include the replacement tags {{unsubscribe}} and {{unsubscribe_preferences}}.

We must supply the unsubscribe group id in our mail send API request. The group id can be found in the dashboard (Marketing — Unsubscribe Groups). This integer is then supplied in the request body as asm.group_id

Let’s see an example now using the nodejs sendgrid package

This will now make sure that our unsubscribe links work for the proper unsubscribe group when someone clicks on it.

This is what it looks like when you click on unsubscribe now.

Conclusion

There you have it, that’s how you actually set up unsubscription options using SendGrid’s email API. 🚀

In case your wondering how to un-unsubscribe someone (like yourself after you tried it to make sure it works), just head to the SendGrid dashboard Supressions — Global/Group Unsubscribes.

Happy emailing! 👩‍💻