How To Add Unsubscribe Links To Sendgrid Emails

Posted on Mar 07, 2019


By landing on this article you are most likely a Sendgrid customer that wants to add unsubscribe links to your emails but cannot find out how to do it in the Sendgrid backend or are confused by the documentation they’ve published.

Adding unsubscribe links is an important part of every email you send. In fact, since GDPR it is now a regulation that you have to comply with. If you send emails to users, you need to offer recipients a way to remove themselves from the list - simple. Many things about GDPR are open to interpretation but this is one area that is crystal clear.

As SG Widget is the number one subscription widget for Sendgrid, we know their API and user interface in great detail so we can provide expert advice on how to insert those all-important unsubscribe links and the configuration options you have.

If you want unsubscribe links just like the screenshot below, then read on:



Global vs Group

Firstly, an email can contain more than one type of unsubscribe link so it’s important to understand differences or you could inadvertently allow users to exclude themselves from emails that they really need to see.


A global unsubscribe link is one that allows users to remove themselves from every email you send from your Sendgrid account - no exceptions. If an email address exists in any of your Sendgrid lists and a user clicks a global unsubscribe link, they will be excluded from receiving any future emails from you regardless of the list it targets. This is an extremely powerful option but one that should be used with care. Consider the following scenarios:

1) A blogger with multiple blogs

A blogger could have a Wordpress blog about travelling in Asia and a monthly newsletter that is sent to a list in their Sendgrid account. The blogger may also operate a blog about travelling in Australia with an accompanying newsletter. A recipient could click a global unsubscribe link in the Asia travel newsletter because they’ve just got back from a holiday in that country and have no further interest in exploring it.

However, they would also be opted out of the Australia newsletter and any other email sent from that Sendgrid account. This reduces the blogger's ability to cross-sell and the user's ability to receive an email that they may be interested in.

2) An eCommerce store with a newsletter

A Shopify store that uses Sendgrid to send their transactional emails most likely uses Sendgrid for their marketing emails as well. If a user clicks a global unsubscribe in a promotional email there is a good chance they may not receive transactional emails they really need in the future such as a purchase confirmation or delivery notification.

As you can see, global unsubscribes are powerful but should be used with care. Now let’s look at Group unsubscribe links.


A group unsubscribe link is one that allows users to remove themselves from specific email lists and remain subscribed to others. This gives Sendgrid users and their recipient's much more granularity and control over how marketing preferences are handled. Let consider how global unsubscribes would impact our previous examples:

1) A blogger with multiple blogs

If a blogger has multiple blogs and a user removes themselves from the mailing list of one by clicking a group unsubscribe link, they would still be subscribed to the mailing of the other. This means the blogger could still promote a holiday in Australia even though the user has excluded themselves from the Asia newsletter. The blogger would be happy because they can continue to contact their subscriber and the user would happy because they can still receive information about potential holiday destinations they are interested in.

2) An eCommerce store with a newsletter

If a user clicks a group unsubscribe link in a promotional email from an online store they would be unsubscribed from that list only and would still receive important transactional emails. The store owner would be happy because they can still inform their users about purchases and the customers would be happy because they will receive an email letting them know when their item will be delivered so they can be in the house.

Adding Unsubscribe Links to Sendgrid emails

Now that we know the differences between global and group unsubscribes, let’s see exactly how to insert them in emails sent from your Sendgrid account.

There are two types of emails that can be sent from Sendgrid - Transactional or Marketing, and each of these has different methods for inserting links.

Transactional Templates

Global Unsubscribe

As previously discussed, there are not many reasons to have global unsubscribe links in transactional emails. After all, they are only triggered by user actions like purchasing a product or requesting a password reset so you can be more or less certain that these are emails that a user wants to receive. None the less, if you have a use case that requires global unsubscribe in a transactional email you can do that by using the Sendgrid Subscription tracking feature. In your Sendgrid Account:

  • Go to Settings > Subscription tracking
  • Activate

Final warning
This will give users the ability to opt out of every email you send, whether it is marketing or transactional.

Group Unsubscribe

Group unsubscribe links are the best method for inserting unsubscribe functionality in your emails. Before you do that, you need to have some groups created in your Sendgrid account so if you haven’t got some already, go to:

Groups > Unsubscribe Groups > Create a group

Next, you need to insert specific tags in your email that are populated when you make an API request to send the email. This request will contain the group that users will be removed from and also the groups that will be displayed if they click the unsubscribe preferences link.

In your Sendgrid Account:

  • Go to your template
  • Insert an unsubscribe module in an HTML block
  • Save


This will insert the required tags that are turned into links when the email is sent.

With SG Widget, specifying the groups is easy and requires no coding. In your SG Widget Account:

  • Go to the Edit page of a Widget
  • Scroll to the Double Opt-In or Welcome Email sections
  • Choose an unsubscribe group
  • Choose unsubscribe groups to display
  • Click Update
SG Widget's Custom Email templates are a powerful integration with Sendgrid and allow you to customise your Welcome and Double Opt In emails.

Marketing Templates

Global Unsubscribe

As Sendgrid have an intuitive email builder, adding global unsubscribe links to a marketing template is rather straightforward. In your Sendgrid account:

  • Go to Templates > Marketing
  • Open a template
  • Click Tags
  • Drag the <%asm_global_unsubscribe_raw_url%> tag into your email
  • Save

Group Unsubscribe

Adding a Group Unsubscribe link to a Marketing Template is an identical process, except this time you want to select the <%asm_group_unsubscribe_raw_url%> tag. It couldn’t be easier!


As mentioned, you can give users the ability to alter their subscription preferences from the email by including a preferences tag, which opens a page containing a list of options for users to set on a more granular level.

If you added an unsubscribe module to a template, SG Widget makes it really easy to control what is displayed on the preferences page. In the Unsubscribe Settings section of your widget, just check the groups you want to be displayed. These will be passed to Sendgrid in an API call when someone subscribes to your list.


When a user clicks the Preferences link in an email they will see a Sendgrid hosted page like this:


How to reduce unsubscribes

While it is important to have a clean unsubscribe process, it would be great if it wasn’t used all that much by your users as nobody wants to see a subscriber leaving their list after you've successfully collected the email. Here are a few proven methods to reduce your unsubscribe rate: .


Unsubscribe links need to be in every email you send. This guide shows you exactly how to achieve that with Sendgrid and the options you have when doing so.

Unless you have a valid reason to use global unsubscribes, we strongly recommend that you insert Group unsubscribe links your emails. Both of these options are possible with SG Widget and they can be configured easily so you can meet the GDPR requirements and ensure that every email you send is a compliant one.

Do you have an opinion on global vs group unsubscribes or are you a Sendgrid customer struggling to implement unsubscribe options in your emails? We would love to hear from you so post your thoughts in the comment section below.


Siobhan 07.09.2020

So so helpful. I don't understand why this isn't easier in Sendgrid but this post helped me clarify how to add unsubscribe links. Thank you

Leave a Comment: