We will deprecate this version on February 10, 2025. To access all the latest features and upcoming developments, please see our v3 API. For assistance with transitioning, refer to our migration guide.
Filter Settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid's v2 Web API.
The following API requests are account-wide filter settings. These settings are unlike the SMTP API, which will change the status at the individual email message level.
For a more detailed description of each of the Filters below, please visit the Settings page.
All calls to change filter settings are made to the filter.setup endpoint.
The Address Whitelist setting allows a specified email address or domain for which mail should never be suppressed.
Name - addresswhitelist
Please note that the Address Whitelist feature has been updated to Address Allow List in the SendGrid App.
When using the addresswhitelist call, you must define all emails and domains in the list parameter. Using this call will overwrite any current settings for the addresswhitelist filter. Because this call overwrites current settings, you can use it to delete an entry—excluding an entry from the call will delete the entry.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| name | yes | addresswhitelist | The name of the setting. |
| list | yes | A list of email addresses or domains. | list[]=support@example.com&list[]=sales@example.com |
POST | https://api.sendgrid.com/api/filter.setup.json |
|---|---|
POST Data | api_user=apikey&api_key=your_sendgrid_api_key&name=addresswhitelist&list[]=support@example.com&list[]=sales@example.com |
1{2"message": "success"3}
Name - bcc
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| name | yes | bcc | The name of the setting. |
| yes | An email address to be the BCC recipient. | email@example.com |
Name - clicktrack
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| name | yes | clicktrack | The name of the setting. |
| enable_text | yes | Enable click tracking in plain text emails. | 0 or 1 |
Name - dkim
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| name | yes | dkim | The name of the setting. |
| domain | yes | The domain to sign messages as. | example.com |
| use_from | no | If enabled, the domain in the From: header of the email will be used to sign your DKIM. | 0 or 1 |
Name - template
This setting is our original Email Template app. Today, we have more full featured transactional templates with support for multiple templates, versioning, and many other helpful features. However, transactional templates are controlled using a separate API.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| name | yes | template | The name of the setting. |
| text/html | yes | A string that holds the template html body. | \<html>\<head>\</head>\<body bgcolor='pink'>\<div style='width:200px' bgcolor='#FFF'>\<% body %>\</div>\</body>\</html> |
POST | https://api.sendgrid.com/api/filter.setup.json |
|---|---|
POST Data | api_user=apikey&api_key=your_sendgrid_api_key&name=template&text/html=%3Chtml%3E%3Chead%3E%3C%2Fhead%3E%3Cbody%20bgcolor%3D%27pink%27%3E%3Cdiv%20style%3D%27width%3A200px%27%20bgcolor%3D%27%23FFF%27%3E%3C%25%20body%20%25%3E%3C%2Fdiv%3E%3C%2Fbody%3E%3C%2Fhtml%3E |
1{2"message": "success"3}
Name - eventnotify
All fields except version are required for each call.
Using the v2 Web API's eventnotify API call will overwrite any previously configured Event Webhook notification settings, including OAuth 2.0. If your OAuth 2.0 settings are overwitten, please configure them again using either the Mail Settings page or the SendGrid v3 API
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| name | Yes | eventnotify | The setting. |
| processed | Yes | Notify when email is processed | 0 |
| dropped | Yes | Notify when email is dropped | 1 |
| deferred | Yes | Notify when email is deferred | 1 |
| delivered | Yes | Notify when email is delivered | 1 |
| bounce | Yes | Notify when email is bounced | 1 |
| click | Yes | Notify when email is clicked | 1 |
| open | Yes | Notify when email is opened | 1 |
| unsubscribe | Yes | Notify when email is unsubscribed | 1 |
| group_unsubscribe | Yes | Notify when recipient unsubscribes from group | 1 |
| group_resubscribe | Yes | Notify when recipient resubscribes to group | 1 |
| spamreport | Yes | Notify when email is marked as spam | 1 |
| group_unsubscribe | Yes | Notify when email unsubscribes from an Unsubscribe Group | 1 |
| group_resubscribe | Yes | Notify when email resubscribes to an Unsubscribe Group | 1 |
| url | Yes | The post notification url to post these event messages to | https://notificationurl.example.com/event |
| version | No | The version of the Event API you wish to use. (1-3) | 3 |
POST | https://api.sendgrid.com/api/filter.setup.json |
|---|---|
POST Data | api_user=apikey&api_key=your_sendgrid_api_key&name=eventnotify&processed=0&dropped=1&deferred=1&delivered=1&bounce=1&click=1&unsubscribe=1&spamreport=1&url=https://notificationurl.example.com/event&version=3 |
1{2"message": "success"3}
Name - ganalytics
At least one of the optional parameters needs to be passed to avoid a "missing parameters" error.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| name | Yes | ganalytics | The setting. |
| utm_source | No | Name of the referrer source | Transactional Email |
| utm_medium | No | Name of the marketing medium | |
| utm_campaign | No | Name of the campaign | Redesigned Transaction |
| utm_term | No | Identify paid keywords | Health |
| utm_content | No | Use to differentiate ads | PageB |
Name - spamcheck
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| name | Yes | spamcheck | The setting. |
| max_score | Yes | Emails with a spam score over this value will be considered spam and will not be delivered to the recipient. The default spam threshold is 5.0, but you can set this to any value you wish. We use SpamAssassin to process the spam checks for this filter, so you can base your maxscore setting on values typically used with SpamAssassin | 1.2 |
| url | Yes | URL to post the email and a copy of the detailed SpamAssassin report describing why the email was designated as spam | https://www.example.com/spamcheck.php |
Name - subscriptiontrack
You must pass at least one of the optional params in order to avoid the "missing parameter" error.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| name | Yes | subscriptiontrack | The setting. |
| text/html | No | String for the HTML email body | If you would like to unsubscribe and stop receiving these emails <% click here %> |
| text/plain | No | String for the plain text email body | If you would like to unsubscribe and stop receiving these emails click here: <% %>. |
| url | No | a URL the customer will be redirected to upon clicking the subscription management link | http://www.example.com/UnsubscribeLandingPage |
| landing | No | HTML content for a landing page that will be displayed by SendGrid | <html>Content</html> |
| replace | No | a tag that can be added to the content that will be replaced by SendGrid with the subscription management link | [unsubscribe_tag] |
POST | https://api.sendgrid.com/api/filter.setup.json |
|---|---|
POST Data | api_user=apikey&api_key=your_sendgrid_api_key&name=subscriptiontrack&text/html=%3Cp%3EIf%20you%20would%20like%20to%20unsubscribe%20and%20stop%20receiving%20these%20emails%20%3C%25%20click%20here%20%25%3E%3C%2Fp%3E&text/plain=If%20you%20would%20like%20to%20unsubscribe%20and%20stop%20receiving%20these%20emails%20click%20here%3A%20%3C%25%20%25%3E.&url=http://www.example.com/UnsubscribeLandingPage&replace=%5Bunsubscribe_tag%5D |
1{2"message": "success"3}
Name - sendwithus
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| name | Yes | sendwithus | The setting for which to set or retrieve settings. |
| license_key | Yes | Can be found in Sendwithus Settings page |