Following are the apps 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 an App, also called a filter, via SMTPAPI, you are required to define all of the parameters for that App.
  • App enabled status will always default to your settings on the website, unless otherwise defined in your X-SMTPAPI header
  • If you enable a disabled app, our system will not pull your settings for the disabled app. 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 apps, please check out the Apps section.

Some Apps are not listed here, because they cannot be defined on a per-message basis. To update these other Apps, please refer to the Web API Filter Settings commands.

Filter: bcc

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 App
email email email address destination for the bcc message
1
2
3
4
5
6
7
8
9
10
{
  "filters" : {
    "bcc" : {
      "settings" : {
        "enable" : 1,
        "email" : "you@example.com"
      }
    }
  }
}

Filter: bypass_list_management

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 e-mail for delivery.

Parameter Name Parameter Value Parameter Description
enable 0 | 1 Disable or enable this App
1
2
3
4
5
6
7
8
9
{
  "filters" : {
    "bypass_list_management" : {
      "settings" : {
        "enable" : 1
      }
    }
  }
}

Filter: clicktrack

Rewrites links in e-mail 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 App

Example X-SMTPAPI Header Value

1
2
3
4
5
6
7
8
9
{
  "filters" : {
    "clicktrack" : {
      "settings" : {
        "enable" : 1
      }
    }
  }
}

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 e-mail. For more info, check out these details on DKIM.

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

1
2
3
4
5
6
7
8
9
10
{
  "filters" : {
    "dkim" : {
      "settings" : {
        "domain" : "example.com",
        "use_from" : false
      }
    }
  }
}

Filter: domainkeys

Allows you to specify the domain to use to sign messages with Domain Keys. This domain should match the domain in the From address of your e-mail. For more info, check out these details on Domain Keys.

Parameter Name Parameter Value Parameter Description
enable 0 | 1 Disable or enable this App
domain domain The domain to sign messages as
sender 0 | 1 1 - Insert a Sender header if the domain specified does not match the From address. 0 - never insert a Sender header

Example X-SMTPAPI Header Value

1
2
3
4
5
6
7
8
9
10
11
{
  "filters" : {
    "domainkeys" : {
      "settings" : {
        "enable" : 1,
        "domain" : "example.com",
        "sender" : 1
      }
    }
  }
}

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 App
text/html string String containing html body
text/plain string String containing text body

Example X-SMTPAPI Header Value

1
2
3
4
5
6
7
8
9
10
11
{
  "filters" : {
    "footer" : {
      "settings" : {
        "enable" : 1,
        "text/html" : "<p>Thanks,<br />The SendGrid Team<p>",
        "text/plain" : "Thanks,\n The SendGrid Team"
      }
    }
  }
}

Filter: forwardspam

Allows for a copy of spam reports to be forwarded to an email address.

l
Parameter Name Parameter Value Parameter Description
enable 0 | 1 Disable or enable this App
email email email address destination for spam report to go to
1
2
3
4
5
6
7
8
9
10
{
  "filters" : {
    "forwardspam" : {
      "settings" : {
        "enable" : 1,
        "email" : "you@example.com"
      }
    }
  }
}

Filter: ganalytics

Re-writes links to integrate with Google Analytics.

Parameter Name Parameter Value Parameter Description
enable 0 | 1 Disable or enable this App
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

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "filters" : {
    "ganalytics" : {
      "settings" : {
        "enable" : 1,
        "utm_source" : "Transactional Email",
        "utm_medium" : "email",
        "utm_content" : "Reset Your Password",
        "utm_campaign" : "Redesigned Transactional Messaging"
      }
    }
  }
}

Filter: gravatar

Inserts an img tag at the bottom of the html section of an e-mail to display the gravatar associated with the mail sender.

Parameter Name Parameter Value Parameter Description
enable 0 | 1 Disable or enable this App

Example X-SMTPAPI Header Value

1
2
3
4
5
6
7
8
9
{
  "filters" : {
    "gravatar" : {
      "settings" : {
      "enable" : 1
      }
    }
  }
}

Filter: opentrack

Inserts an <img> tag at the bottom of the html section of an e-mail which will be used to track if an e-mail is opened.

Parameter Name Parameter Value Parameter Description
enable 0 | 1 Disable or enable this App

Example X-SMTPAPI Header Value

1
2
3
4
5
6
7
8
9
{
  "filters" : {
    "opentrack" : {
      "settings" : {
        "enable" : 1
      }
    }
  }
}

Filter: spamcheck

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 App
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

1
2
3
4
5
6
7
8
9
10
11
{
  "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 paremeters. 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

1
2
3
4
5
6
7
8
9
10
11
{
    "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 app is our new Template Engine, that supports multiple templates, versioning and more. Previously, we had a Template App, now called the Legacy Template App.

Uses a template created with the Template Engine when sending an email. More information on usage of the Template Engine with the SMTP API may be found in the Template Engine API Reference.

Parameter Name Parameter Value Parameter Description
enable 0 | 1 Disable or enable this App
template_id string The ID of the template to use when sending a message, represented by a string.

Example X-SMTPAPI Header Value

1
2
3
4
5
6
7
8
9
10
{
  "filters": {
    "templates": {
      "settings": {
        "enable": 1,
        "template_id": "5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f"
      }
    }
  }
}

Filter: 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.

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 App
text/html string String containing html content for the template (must contain a <% body %> tag)

Example X-SMTPAPI Header Value

1
2
3
4
5
6
7
8
9
10
{
  "filters" : {
    "template" : {
      "settings" : {
        "enable" : 1,
        "text/html" : "<html><head></head><body bgcolor='pink'><div style='width:200px' bgcolor='#FFF'><% body %></div></body></html>"
      }
    }
  }
}