These API requests are Account Wide settings, unlike the SMTP API which will change the status at the individual email message level.

For a more detailed description of each of the Apps below, please visit the Apps page.

All calls to change filter settings are made to the filter.setup endpoint.

Address Whitelist

API App Name - addresswhitelist

When using this call, you must define all emails & domains here. Using this call will overwrite any current settings for this filter. This would also be how you remove an entry, by excluding if from the call.

Parameter Required Requirements Description
name yes addresswhitelist The name of the app for which to apply settings.
list yes A list of email addresses or domains. list[]=support@example.com&list[]=sales@example.com
Parameter Value Requirements Description

Call

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

Response

1
2
3
{
  "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=addresswhitelist&list[]=support@example.com&list[]=sales@example.com

Response

1
2
3
<result>
   <message>success</message>
</result>

BCC “Blind Carbon Copy”

API App Name - bcc

Parameter Required Requirements Description
name yes bcc The name of the app for which to apply settings.
email yes An email address to be the BCC recipient. email@example.com
Parameter Value Requirements Description

Call

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

Response

1
2
3
{
  "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=bcc&email=email@example.com

Response

1
2
3
<result>
   <message>success</message>
</result>

Click Tracking

API App Name - clicktrack

Parameter Required Requirements Description
name yes clicktrack The name of the app for which to apply settings.
enable_text yes Enable click tracking in plain text emails. 0 or 1
Parameter Value Requirements Description

Call

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

Response

1
2
3
{
  "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=clicktrack&enable_text=1

Response

1
2
3
<result>
   <message>success</message>
</result>

DKIM

API App Name - dkim

Parameter Required Requirements Description
name yes dkim The name of the app for which to apply settings.
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
Parameter Value Requirements Description

Call

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

Response

1
2
3
{
  "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=dkim&domain=example.com&use_from=1

Response

1
2
3
<result>
   <message>success</message>
</result>

Domain Keys

API App Name - domainkeys

Parameter Required Requirements Description
name yes domainkeys The name of the app for which to apply settings.
domain yes The domain to sign messages as. example.com
sender no 1 to insert a sender header if the domain specified does not match the from address; 0 to never insert a Sender header. 0 or 1
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/filter.setup.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=domainkeys&sender=1

Response

1
2
3
{
  "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=domainkeys&sender=1

Response

1
2
3
<result>
   <message>success</message>
</result>

Legacy Email Templates

API App Name - template

This app is our original Email Template app, today we have a more full featured Template Engine, which supports multiple templates, versioning and more. Its settings, however, are controlled using a separate API.

Parameter Required Requirements Description
name yes template The name of the app for which to apply settings.
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>
Parameter Value Requirements Description

Call

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

1
2
3
{
  "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=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

1
2
3
<result>
   <message>success</message>
</result>

Event Notification

API App Name - eventnotify

All fields except version are required for each call.

Parameter Required Requirements Description
name Yes eventnotify The app for which to set or retrieve settings.
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 ASM Group 1
group_resubscribe Yes Notify when email resubscribes to an ASM 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
Parameter Value Requirements Description

Call

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

1
2
3
{
  "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

1
2
3
<result>
   <message>success</message>
</result>

Footer

API App Name - footer

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


Google Analytics

API App Name - ganalytics

At least one of the optional parameters needs to be passed to avoid a “missing parameters” error.

Parameter Required Requirements Description
name Yes ganalytics The app for which to set or retrieve settings.
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
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/filter.setup.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=ganalytics&utm_source=Transactional

Response

1
2
3
{
  "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

Response

1
2
3
<result>
   <message>success</message>
</result>

SPAM Filter Checker

API App Name - spamcheck

Parameter Required Requirements Description
name Yes spamcheck The app for which to set or retrieve settings.
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
Parameter Value Requirements Description

Call

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

Response

1
2
3
{
  "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=spamcheck&max_score=1.2&url=https://www.example.com/spamcheck.php

Response

1
2
3
<result>
   <message>success</message>
</result>

Subscription Tracking

API App Name - subscriptiontrack

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

Parameter Required Requirements Description
name Yes subscriptiontrack The app for which to set or retrieve settings.
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 on 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]
Parameter Value Requirements Description

Call

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

1
2
3
{
  "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=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

1
2
3
<result>
   <message>success</message>
</result>

SendGrid for New Relic

API App Name - newrelic

Parameter Required Requirements Description
name Yes newrelic The app for which to set or retrieve settings.
license_key Yes Can be found in New Relic Settings page
enable_subusers Yes false to disable, true to enable
Parameter Value Requirements Description

Call

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

Response

1
2
3
{
  "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=newrelic&license_key=1234567&enable_subusers=true

Response

1
<message>success</message>

Sendwithus

API App Name - sendwithus

Parameter Required Requirements Description
name Yes sendwithus The app for which to set or retrieve settings.
license_key Yes Can be found in Sendwithus Settings page
Parameter Value Requirements Description

Call

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

Response

1
2
3
{
  "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=sendwithus&license_key=1234567

Response

1
<message>success</message>