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

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

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 Description Example
enable_text Enable click tracking in plain text emails. 1

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 Description Example
domain The domain to sign messages as example.com
sender 1 to insert a sender header if the domain specified does not match the from address 0 to never insert a Sender header 1

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 Description Example
domain The domain you would like your DKIM certification signed with example.com
use_from If enabled, the domain in the From: header of the email will be used to sign your DKIM 1

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 Description Example
text_html 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://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 Description Example
processed Notify when email is processed 0
dropped Notify when email is dropped 1
deferred Notify when email is deferred 1
delivered Notify when email is delivered 1
bounce Notify when email is bounced 1
click Notify when email is clicked 1
open Notify when email is opened 1
unsubscribe Notify when email is unsubscribed 1
spamreport Notify when email is marked as spam 1
url The post notification url to post these event messages to https://notificationurl.example.com/event
version The version of the Event API you wish to use. (1-3) 3

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

Parameter Description Example
text/html String that holds the html body <html>Content</html>
text/plain String that holds the text body Content

Google Analytics

API App Name - ganalytics

Parameter Description Example
utm_source Name of the referrer source Transactional Email
utm_medium Name of the marketing medium email
utm_campaign Name of the campaign Redesigned Transaction
utm_term Identify paid keywords Health
utm_content Use to differentiate ads PageB

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

Parameter Description Example
None N/A N/A

Open Tracking

API App Name - opentrack

Parameter Description Example
None N/A N/A

SPAM Filter Checker

API App Name - spamcheck

Parameter Description Example
maxscore 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 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://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 Description Example
text/html String for the HTML e-mail body If you would like to unsubscribe and stop receiving these emails <% click here %>
text/plain String for the plain text e-mail body If you would like to unsubscribe and stop receiving these emails click here: <% %>.
url a URL the customer will be redirected to on clicking the subscription management link http://www.example.com/UnsubscribeLandingPage
landing HTML content for a landing page that will be displayed by SendGrid <html>Content</html>
replace 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://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

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>