How can I add unsubscribe links to my emails when sending via sendgrid/mail

The best approach is to use Group Unsubscribes.

  1. First create a group in Sendgrid:
  • Groups > Unsubscribe Groups > Create a group
  1. Next, insert a module into the Sendgrid template that creates specific tags in your email, which are populated when you make an API request
  • Go to your template
  • Insert an unsubscribe module in an HTML block
  • Save

Adding unsubscribe module

  1. Finally make an API request and specify the group created in step 1:
     "asm":{
        "group_id":544,
        "groups_to_display": [544, 788],
     }
  1. These will be inserted into the module mentioned in step 2 when the email is sent.

Unfortunately Sendgrid unsubscribe links are not as straightforward as they could be. They are explained in more detail here


Since you're sending using code, it's a "transactional" type of message. You'll want to either turn on the Subscription Tracking filter at the account level (via [UI](subscription tracking setting) or API), or turn it on as you send the message, as part of the mail/send API call, under tracking_settings.

It's important to note that you can't mix those. If you define anything in the mail/send API call, you'll need to define everything for Subscription Tracking in that call. SendGrid won't look at some settings at the mail level, and some at the account level.

Most users will just set it at the account level. There, you can customize the HTML & Text of the Unsubscribe footer, customize the HTML of the landing page, or redirect landing to a URL of your choosing, which will send the recipient there with [email protected] in the URL string for your system to catch. You can also define the "replacement tag" like [%unsubscribe%], so that you can place the URL wherever you want within your HTML.


  1. https://app.sendgrid.com/ > Suppressions > Unsubscribe Groups > Create New Group

  2. Note down group_id/ids. e.g 123 (Only number !Not string) enter image description here

  3. Send email using node.js


const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(SENDGRID_API_KEY);


const tags = { invitedBy : Alex }
const msg = {
            to: email,
            from: { "email": SENDER_EMAIL, 
                    "name": SENDER_NAME 
                  },
            templateId: TEMPLATE_ID,
            dynamic_template_data: {
                Sender_Name: name,
                ...tags
            },
            asm: {
                group_id: 123,
                groups_to_display: [
                    123
                ],
            },
        };


await sgMail.send(msg); 


One tip that would have saved me an hour or two is that:

It's possible to send the following in the api json along with other stuff:

  "asm":{
    "group_id":123,
    "groups_to_display": [123],
    }

then the following variables become available to use within the template:

<%asm_group_unsubscribe_raw_url%>
<%asm_preferences_raw_url%>

If you want to keep things simple don't include the following variable as it fiddles with too many things (this wasn't obvious from the documentation so obviously I did so and wasted time :( ):

  "tracking_settings": {
    "subscription_tracking": {
      "enable": true,
      "substitution_tag": "[unsubscribe_url]"
    }
  }

Just use them in their raw format and you shall be fine.