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

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`

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

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

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

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>

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

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

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

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`

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]

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`

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`

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

This documentation is for the SendGrid Web API v2

Thank you for your feedback!

Thanks for your feedback!