SMTP Filters
Following are the settings that can be specified in the filters section of the X-SMTPAPI header. All filters and setting names must be lowercase.
- If you're enabling a Setting, also called a filter, via SMTPAPI, you are required to define all of the parameters for that Setting.
- If you enable a disabled setting, our system will not pull your settings for the disabled setting. You will need to define the settings in your X-SMTPAPI header Example: If you have a footer designed but disabled, you can't just enable it via the API; you need to define the footer in the API call itself.
- All filter names and setting names must be lowercase.
For more information on the utility of these settings, please check out the Settings section.
Some Settings are not listed here because they cannot be defined on a per-message basis. To update these other Settings, please refer to the Web API Filter Settings commands.
Due to low usage, this setting has been removed. Click here for more information.
Sends a BCC copy of the email created in this transaction to the address specified.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| enable | 0 | 1 |
Disable or enable this Setting |
email |
email address destination for the bcc message |
{
"filters": {
"bcc": {
"settings": {
"enable": 1,
"email": "example@example.com"
}
}
}
}
Filter: bypass_list_management
This setting is very powerful, and can only be used on a per-message basis. Use with extreme caution. To learn more about the more granular bypass settings available in the v3 Mail Send API, see our Suppressions Overview documentation.
Some emails are too important to do normal list management checks, such as password resets or critical alerts. Enabling this filter will bypass the normal unsubscribe / bounce / spam report checks and queue the email for delivery.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| enable | 0 | 1 |
Disable or enable this Setting |
{
"filters": {
"bypass_list_management": {
"settings": {
"enable": 1
}
}
}
}
Filter: clicktrack
Rewrites links in email text and html bodies to go through our webservers, allowing for tracking when a link is clicked on.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| enable | 0 | 1 |
Disable or enable this Setting |
| enable_text | true | false |
Enable or Disable click-tracking links in the Plain-Text portion of the message. |
Example X-SMTPAPI Header Value
{
"filters": {
"clicktrack": {
"settings": {
"enable": 1,
"enable_text": true
}
}
}
}
Filter: dkim
Allows you to specify the domain to use to sign messages with DKIM certification. This domain should match the domain in the From address of your email.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| domain | domain |
The domain you would like your DKIM certification signed with |
| use_from | 0 | 1 |
If enabled, the domain in the From: header of the email will be used to sign your DKIM |
Example X-SMTPAPI Header Value
{
"filters": {
"dkim": {
"settings": {
"domain": "example.com",
"use_from": false
}
}
}
}
Filter: footer
Inserts a footer at the bottom of the text and HTML bodies.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| enable | 0 | 1 |
Disable or enable this Setting |
| text/html | string |
String containing html body |
| text/plain | string |
String containing text body |
Example X-SMTPAPI Header Value
{
"filters": {
"footer": {
"settings": {
"enable": 1,
"text/html": "<p>Thanks,<br />The SendGrid Team<p>",
"text/plain": "Thanks,\n The SendGrid Team"
}
}
}
}
Filter: ganalytics
Re-writes links to integrate with Google Analytics.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| enable | 0 | 1 |
Disable or enable this Setting |
| utm_source | string |
Value for the utm_source field |
| utm_medium | string |
Value for the utm_medium field |
| utm_term | string |
Value for the utm_term field |
| utm_content | string |
Value for the utm_content field |
| utm_campaign | string |
Value for the utm_campaign field |
Example X-SMTPAPI Header Value
{
"filters": {
"ganalytics": {
"settings": {
"enable": 1,
"utm_source": "Transactional Email",
"utm_medium": "email",
"utm_content": "Reset Your Password",
"utm_campaign": "Redesigned Transactional Messaging"
}
}
}
}
Filter: opentrack
If you don't use 'replace' this will insert an <img> tag at the bottom of the html section of an email which will be used to track if an email is opened. If you choose to use 'replace', you can put the tracking pixel wherever you would like in the email and SendGrid will replace it at send time.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| enable | 0 | 1 |
Disable or enable this Setting |
| replace | string |
A string to be replaced by SendGrid with the tracking image at send time. |
Example X-SMTPAPI Header Value
{
"filters": {
"opentrack": {
"settings": {
"enable": 1,
"replace": "%opentrack%"
}
}
}
}
Filter: spamcheck
Due to low usage, this setting has been removed. Click here for more information.
Tests message with SpamAssassin to determine if it is spam, and drop it if it is.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| enable | 0 | 1 |
Disable or enable this Setting |
| maxscore | 1 to 10.0 |
Score after which the message will be dropped (default is 5.0, higher scores indicate higher likelihood of spam) |
| url | url |
an optional url to POST the email and a copy of the report to. Refer to the Spam Checker documentation for POST details. |
Example X-SMTPAPI Header Value
{
"filters": {
"spamcheck": {
"settings": {
"enable": 1,
"maxscore": 3.5,
"url": "http://example.com/compliance"
}
}
}
}
Filter: subscriptiontrack
Inserts a subscription management link at the bottom of the text and html bodies or insert the link anywhere in the email.
If you wish to append an unsubscription link, use the text/html and text/plain parameters. However, if you wish to have the link replace a tag (such as [unsubscribe]), use the replace parameter.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| enable | 0 | 1 |
Disable or enable this App |
| text/html | string |
HTML to be appended to the email, with the subscription tracking link. You may control where the link is by using a tag like so: <% link text %> |
| text/plain | string |
Text to be appended to the email, with the subscription tracking link. You may control where the link is by using a tag like so: <% %> |
| replace | string |
A tag that will be replaced with the unsubscribe URL (e.g. [unsubscribe_url]). If this parameter is included, it will override text/html and text/plain The URL of the link will be placed at the replace tag's location, with no html or other formatting. |
The landing argument cannot be used in SMTPAPI. It can only be setup via the UI or WebAPI, as an account-level setting.
Example X-SMTPAPI Header Value
{
"filters": {
"subscriptiontrack": {
"settings": {
"text/html": "If you would like to unsubscribe and stop receiving these emails <% click here %>.",
"text/plain": "If you would like to unsubscribe and stop receiving these emails click here: <% %>.",
"enable": 1
}
}
}
}
Filter: templates
This setting refers to SendGrid's transactional templates. SendGrid supports versioning, and the ability to create multiple transactional templates. Previously, we had a Template App, which is now referred to as the Legacy Template App.
Uses a transactional template when sending an email.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| enable | 0 | 1 |
Disable or enable this Setting |
| template_id | string |
The ID of the template to use when sending a message, represented by a string. |
Example X-SMTPAPI Header Value
{
"filters": {
"templates": {
"settings": {
"enable": 1,
"template_id": "5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f"
}
}
}
}
Filter: template
This setting refers to our original Email Template app. We now support more fully featured transactional templates. You may create multiple transactional templates that allow for versioning, in addition to several other features.
Wraps a template around your email content. Useful for sending out marketing email and other nicely formatted messages.
| Parameter Name | Parameter Value | Parameter Description |
|---|---|---|
| enable | 0 | 1 |
Disable or enable this Setting |
| text/html | string |
String containing html content for the template (must contain a <% body %> tag) |
Example X-SMTPAPI Header Value
{
"filters": {
"template": {
"settings": {
"enable": 1,
"text/html": "<html><head></head><body bgcolor='pink'><div style='width:200px' bgcolor='#FFF'><% body %></div></body></html>"
}
}
}
}
Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.
