Suppressions

Give your recipients the option to unsubscribe.

Managing unsubscribes helps maximize email delivery. Without an unsubscribe option to stop getting your email messages, recipients have only one option: report your email as spam. To maintain your reputation, give recipients an unsubscribe option.

Twilio SendGrid enables and manages unsubscribes in two ways: Advanced Suppression Management (ASM) and Subscription Tracking. ASM provides greater control over managing unsubscriptions. To contain the number and granularity of unsubscriptions, use this feature instead of Subscription Tracking.

Advanced Suppression Management (ASM) offers you and your recipients more choices. Your email message displays one or more links that allows recipients to unsubscribe from some email messages or all email messages.

• Every email template you create with the Code Editor includes the Unsubscribe and Unsubscribe Preferences links.
• You can add the unsubscribe links to your email in the Design Editor. To add an unsubscription block, add a Unsubscribe module to your template.

Through ASM, your recipients can manage their subscriptions in three ways:

• Unsubscribe to certain email messages. Twilio SendGrid collects these selective Group Unsubscribes in an Unsubscribe Group.
• Unsubscribe to all email messages. Twilio SendGrid collects these total unsubscribes in a separate Global Unsubscribe Unsubscribe Group.
• Select which email messages they want to keep through a Recipient Subscription Preferences page. Twilio SendGrid hosts this page.

Subscription tracking provides the following capabilities:

• Adds an unsubscribe link to the footer of your email messages.
  • You can customize the text of the unsubscribe link.
  • You can move the unsubscribe link elsewhere in the email message using a substitution tag.
• Adds the list-unsubscribe header to your email messages.

When you turn on Subscription Tracking, Twilio SendGrid adds an unsubscribe option to the footer of every email message. When a recipient clicks that unsubscribe link, Twilio adds them to your Global Unsubscribe group. Twilio suppresses any future attempts to send email messages to that recipient.

You can add and remove email addresses from the Global Unsubscribe group using the UI or the API.

To maintain your reputation, Twilio SendGrid might suppress your email messages for one of the following reasons.

A bypass filter lets you ignore unsubscribe groups and suppressions as you send an email message.

Both the X-SMTPAPI header and the v3 Mail Send API support bypassing all suppression lists.

How these APIs support list bypass differs. Each API requires that you add a key-value pair to their JSON payload. To bypass all suppression lists, add the following parameters and values according to the API standards:

If you don't provide this key and value, X-SMTPAPI sets the value as 0 and the v3 Mail Send API sets the value to false.

1
{
2
    "personalizations": [
3
        {
4
            "to": [
5
                {
6
                    "email": "alex@example.com",
7
                    "name": "Alex"
8
                },
9
                {
10
                    "email": "bola@example.com",
11
                    "name": "Bola"
12
                }
13
            ],
14
            "cc": [
15
                {
16
                    "email": "charlie@example.com",
17
                    "name": "Charlie"
18
                }
19
            ],
20
            "bcc": [
21
                {
22
                    "email": "dana@example.com",
23
                    "name": "Dana"
24
                }
25
            ]
26
        },
27
        {
28
            "from": {
29
                "email": "sales@example.com",
30
                "name": "Example Sales Team"
31
            },
32
            "to": [
33
                {
34
                    "email": "ira@example.com",
35
                    "name": "Ira"
36
                }
37
            ],
38
            "bcc": [
39
                {
40
                    "email": "lee@example.com",
41
                    "name": "Lee"
42
                }
43
            ]
44
        }
45
    ],
46
    "from": {
47
        "email": "orders@example.com",
48
        "name": "Example Order Confirmation"
49
    },
50
    "reply_to": {
51
        "email": "customer_service@example.com",
52
        "name": "Example Customer Service Team"
53
    },
54
    "subject": "Your Example Order Confirmation",
55
    "content": [
56
        {
57
            "type": "text/html",
58
            "value": "<p>Hello from Twilio SendGrid!</p><p>Sending with the email service trusted by developers and marketers for <strong>time-savings</strong>, <strong>scalability</strong>, and <strong>delivery expertise</strong>.</p><p>%open-track%</p>"
59
        }
60
    ],
61
    "attachments": [
62
        {
63
            "content": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==",
64
            "filename": "index.html",
65
            "type": "text/html",
66
            "disposition": "attachment"
67
        }
68
    ],
69
    "categories": [
70
        "cake",
71
        "pie",
72
        "baking"
73
    ],
74
    "send_at": 1617260400,
75
    "batch_id": "AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl",
76
    "asm": {
77
        "group_id": 12345,
78
        "groups_to_display": [
79
            12345
80
        ]
81
    },
82
    "ip_pool_name": "transactional email",
83
    "mail_settings": {
84
        "bypass_list_management": {
85
            "enable": false
86
        },
87
        "footer": {
88
            "enable": false
89
        },
90
        "sandbox_mode": {
91
            "enable": false
92
        }
93
    },
94
    "tracking_settings": {
95
        "click_tracking": {
96
            "enable": true,
97
            "enable_text": false
98
        },
99
        "open_tracking": {
100
            "enable": true,
101
            "substitution_tag": "%open-track%"
102
        },
103
        "subscription_tracking": {
104
            "enable": false
105
        }
106
    }
107
}

In addition to bypass_list_management, the v3 Mail Send API provides three finer-grained bypass filters. To bypass a single list, use one of these filters. You can add multiple bypass filters except in combination with the bypass_list_management filter. You can't combine this list with other bypass lists.

To apply these bypass filters, add them to the mail_settings parameter with the attribute enable. When you set a filter to true, Twilio SendGrid disregards the unsubscribe or suppression status of the addresses in the list and delivers the message to the recipients.

Twilio SendGrid doesn't require any bypass filters in the payload. By default, Twilio disables all bypass parameters. If you don't need the filter, don't set it. To filter out a specific suppression, choose the parameter from the following table:

To understand how what each filter includes or excludes, see the following table:

To review examples, see the v3 Mail Send API reference.

• Unsubscribe Groups
• Create and Manage Unsubscribe Groups
• [Manage bounced messages][bounces-how]
• [Manage blocked messages][blocks-how]