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 no A list of email addresses or domains. list[]=support@example.com&list[]=sales@example.com
Parameter Value Requirements Description

Call

POST https://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://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
4
5
<?xml version="1.0" encoding="ISO-8859-1"?>

<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.
bcc yes An email address to be the BCC recipient. email@example.com
Parameter Value Requirements Description

Call

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

Response

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

Call

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

Response

1
2
3
4
5
<?xml version="1.0" encoding="ISO-8859-1"?>

<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://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://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>

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://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://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>

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://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://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>

Email Templates

API App Name - template

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://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://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? Description Example
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
spamreport Yes Notify when email is marked as spam 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://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://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


Google Analytics

API App Name - ganalytics

Parameter Required? Description Example
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://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://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>

Gravatar

API App Name - gravatar


Open Tracking

API App Name - opentrack


SPAM Filter Checker

API App Name - spamcheck

Parameter Required? Description Example
maxscore 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://sendgrid.com/api/filter.setup.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=eventnotify&maxscore=1.2&url=https://www.example.com/spamcheck.php

Response

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

Call

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

Response

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

Subscription Tracking

API App Name - subscriptiontrack

Parameter Required? Description Example
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://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://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 Description
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
2
3
<?xml version="1.0" encoding="ISO-8859-1"?>

<message>success</message>