Skip to contentSkip to navigationSkip to topbar
On this page

Filter Settings


(warning)

This documentation is for the SendGrid Web API v2

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.

(warning)

Warning

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.


Address Whitelist

address-whitelist page anchor

The Address Whitelist setting allows a specified email address or domain for which mail should never be suppressed.

Name - addresswhitelist

(information)

Info

Please note that the Address Whitelist feature has been updated to Address Allow List in the SendGrid App.

(warning)

Warning

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 ParameterRequiredRequirementsDescription
nameyesaddresswhitelistThe name of the setting.
listyesA list of email addresses or domains.list[]=support@example.com&list[]=sales@example.com
JSONXML

Call

POSThttps://api.sendgrid.com/api/filter.setup.json
POST Dataapi_user=apikey&api_key=your_sendgrid_api_key&name=addresswhitelist&list[]=support@example.com&list[]=sales@example.com

Response

1
{
2
"message": "success"
3
}

BCC "Blind Carbon Copy"

bcc-blind-carbon-copy page anchor

Name - bcc

URI ParameterRequiredRequirementsDescription
nameyesbccThe name of the setting.
emailyesAn email address to be the BCC recipient.email@example.com
JSONXML
POSThttps://api.sendgrid.com/api/filter.setup.json
POST Dataapi_user=apikey&api_key=your_sendgrid_api_key&name=bcc&email=email@example.com
1
{
2
"message": "success"
3
}

Name - clicktrack

URI ParameterRequiredRequirementsDescription
nameyesclicktrackThe name of the setting.
enable_textyesEnable click tracking in plain text emails.0 or 1
JSONXML
POSThttps://api.sendgrid.com/api/filter.setup.json
POST Dataapi_user=apikey&api_key=your_sendgrid_api_key&name=clicktrack&enable_text=1
1
{
2
"message": "success"
3
}

Name - dkim

URI ParameterRequiredRequirementsDescription
nameyesdkimThe name of the setting.
domainyesThe domain to sign messages as.example.com
use_fromnoIf enabled, the domain in the From: header of the email will be used to sign your DKIM.0 or 1
JSONXML
POSThttps://api.sendgrid.com/api/filter.setup.json
POST Dataapi_user=apikey&api_key=your_sendgrid_api_key&name=dkim&domain=example.com&use_from=1
1
{
2
"message": "success"
3
}

Name - template

(warning)

Warning

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 ParameterRequiredRequirementsDescription
nameyestemplateThe name of the setting.
text/htmlyesA string that holds the template html body.\<html>\<head>\</head>\<body bgcolor='pink'>\<div style='width:200px' bgcolor='#FFF'>\<% body %>\</div>\</body>\</html>
JSONXML
POSThttps://api.sendgrid.com/api/filter.setup.json
POST Dataapi_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

(information)

Info

All fields except version are required for each call.

(error)

Danger

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(link takes you to an external page) page or the SendGrid v3 API

URI ParameterRequiredRequirementsDescription
nameYeseventnotifyThe setting.
processedYesNotify when email is processed0
droppedYesNotify when email is dropped1
deferredYesNotify when email is deferred1
deliveredYesNotify when email is delivered1
bounceYesNotify when email is bounced1
clickYesNotify when email is clicked1
openYesNotify when email is opened1
unsubscribeYesNotify when email is unsubscribed1
group_unsubscribeYesNotify when recipient unsubscribes from group1
group_resubscribeYesNotify when recipient resubscribes to group1
spamreportYesNotify when email is marked as spam1
group_unsubscribeYesNotify when email unsubscribes from an Unsubscribe Group1
group_resubscribeYesNotify when email resubscribes to an Unsubscribe Group1
urlYesThe post notification url to post these event messages tohttps://notificationurl.example.com/event
versionNoThe version of the Event API you wish to use. (1-3)3
JSONXML
POSThttps://api.sendgrid.com/api/filter.setup.json
POST Dataapi_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 ParameterRequiredRequirementsDescription
nameYesganalyticsThe setting.
utm_sourceNoName of the referrer sourceTransactional Email
utm_mediumNoName of the marketing mediumemail
utm_campaignNoName of the campaignRedesigned Transaction
utm_termNoIdentify paid keywordsHealth
utm_contentNoUse to differentiate adsPageB
JSONXML
POSThttps://api.sendgrid.com/api/filter.setup.json
POST Dataapi_user=apikey&api_key=your_sendgrid_api_key&name=ganalytics&utm_source=Transactional Email&utm_medium=email&utm_content=Reset Your Password&utm_campaign=Redesigned Transactional Messaging
1
{
2
"message": "success"
3
}

Name - spamcheck

URI ParameterRequiredRequirementsDescription
nameYesspamcheckThe setting.
max_scoreYesEmails 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 SpamAssassin1.2
urlYesURL to post the email and a copy of the detailed SpamAssassin report describing why the email was designated as spamhttps://www.example.com/spamcheck.php
JSONXML
POSThttps://api.sendgrid.com/api/filter.setup.json
POST Dataapi_user=apikey&api_key=your_sendgrid_api_key&name=spamcheck&max_score=1.2&url=https://www.example.com/spamcheck.php
1
{
2
"message": "success"
3
}

Name - subscriptiontrack

You must pass at least one of the optional params in order to avoid the "missing parameter" error.

URI ParameterRequiredRequirementsDescription
nameYessubscriptiontrackThe setting.
text/htmlNoString for the HTML email bodyIf you would like to unsubscribe and stop receiving these emails <% click here %>
text/plainNoString for the plain text email bodyIf you would like to unsubscribe and stop receiving these emails click here: <% %>.
urlNoa URL the customer will be redirected to upon clicking the subscription management linkhttp://www.example.com/UnsubscribeLandingPage
landingNoHTML content for a landing page that will be displayed by SendGrid<html>Content</html>
replaceNoa tag that can be added to the content that will be replaced by SendGrid with the subscription management link[unsubscribe_tag]
JSONXML
POSThttps://api.sendgrid.com/api/filter.setup.json
POST Dataapi_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 ParameterRequiredRequirementsDescription
nameYessendwithusThe setting for which to set or retrieve settings.
license_keyYesCan be found in Sendwithus Settings page
JSONXML
POSThttps://api.sendgrid.com/api/filter.setup.json
POST Dataapi_user=apikey&api_key=your_sendgrid_api_key&name=sendwithus&license_key=1234567
1
{
2
"message": "success"
3
}

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.