Menu

Expand

This documentation is for the SendGrid Web API v2

To access all the latest features and upcoming developments, please see our v3 API.

Rate this page:

Filter Settings

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.

Address Whitelist

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

Call

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

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=addresswhitelist&list[]=support@example.com&list[]=sales@example.com

Response

<result>
   <message>success</message>
</result>

BCC "Blind Carbon Copy"

Name - bcc

URI Parameter Required Requirements Description
name yes bcc The name of the setting.
email yes An email address to be the BCC recipient. email@example.com

Call

POST https://api.sendgrid.com/api/filter.setup.json
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=bcc&email=email@example.com

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=bcc&email=email@example.com

Response

<result>
   <message>success</message>
</result>

Click Tracking

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

Call

POST https://api.sendgrid.com/api/filter.setup.json
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=clicktrack&enable_text=1

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=clicktrack&enable_text=1

Response

<result>
   <message>success</message>
</result>

DKIM

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

Call

POST https://api.sendgrid.com/api/filter.setup.json
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=dkim&domain=example.com&use_from=1

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=dkim&domain=example.com&use_from=1

Response

<result>
   <message>success</message>
</result>

Legacy Email Templates

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>

Call

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

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
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

Response

<result>
   <message>success</message>
</result>

Event Notification

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

Call

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

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&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

Response

<result>
   <message>success</message>
</result>

Footer

Name - footer

You must provide either text/html or text/plain, or both, to avoid receiving a "missing parameters" error.

URI Parameter Required Requirements Description
name Yes footer The setting.
text/html No String that holds the html body <html>Content</html>
text/plain No String that holds the text body Content

Call

POST https://api.sendgrid.com/api/filter.setup.json
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=footer&text/html=%3Cp%3EThanks!%3Cbr%2F%3ESendGrid%3C%2Fp%3E&text/plain=Thanks!%0ASendGrid

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=footer&text/html=%3Cp%3EThanks!%3Cbr%2F%3ESendGrid%3C%2Fp%3E&text/plain=Thanks!%0ASendGrid

Response

<result>
   <message>success</message>
</result>

Google Analytics

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 email
utm_campaign No Name of the campaign Redesigned Transaction
utm_term No Identify paid keywords Health
utm_content No Use to differentiate ads PageB

Call

POST https://api.sendgrid.com/api/filter.setup.json
POST Data api_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

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=ganalytics&utm_source=Transactional Email&utm_medium=email&utm_content=Reset Your Password&utm_campaign=Redesigned Transactional Messaging

Response

<result>
   <message>success</message>
</result>

SPAM Filter Checker

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

Call

POST https://api.sendgrid.com/api/filter.setup.json
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=spamcheck&max_score=1.2&url=https://www.example.com/spamcheck.php

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=spamcheck&max_score=1.2&url=https://www.example.com/spamcheck.php

Response

<result>
   <message>success</message>
</result>

Subscription Tracking

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 e-mail body If you would like to unsubscribe and stop receiving these emails <% click here %>
text/plain No String for the plain text e-mail 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]

Call

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

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
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

Response

<result>
   <message>success</message>
</result>

SendGrid for New Relic

Name - newrelic

URI Parameter Required Requirements Description
name Yes newrelic The setting.
license_key Yes Can be found in New Relic Settings page
enable_subusers Yes false to disable, true to enable

Call

POST https://api.sendgrid.com/api/filter.setup.json
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=newrelic&license_key=1234567&enable_subusers=true

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=newrelic&license_key=1234567&enable_subusers=true

Response

<message>success</message>

Sendwithus

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

Call

POST https://api.sendgrid.com/api/filter.setup.json
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=sendwithus&license_key=1234567

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/filter.setup.xml
POST Data api_user=apikey&api_key=your_sendgrid_api_key&name=sendwithus&license_key=1234567

Response

<message>success</message>
Rate this page:
        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more