Settings (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.

For more information on the utility of these settings, please check out the Settings section.

Filter: bcc

Sends a BCC copy of the email created in this transaction to the address specified.

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 email for delivery.

1
2
3
4
5
6
7
8
9

{
  "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.

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 email.

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

Inserts a footer at the bottom of the text and HTML bodies.

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

Re-writes links to integrate with Google Analytics.

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

Example X-SMTPAPI Header Value

1
2
3
4
5
6
7
8
9
10

{
  "filters" : {
    "opentrack" : {
      "settings" : {
        "enable" : 1,
        "replace" : "%opentrack%"
      }
    }
  }
}

Filter: spamcheck

Tests message with SpamAssassin to determine if it is spam, and drop it if it is.

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 parameters. However, if you wish to have the link replace a tag (such as [unsubscribe]), use the replace parameter.

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

Uses a transactional template when sending an email. More information on using transactional templates with the SMTP API may be found in the transactional templates API Reference.

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

Wraps a template around your email content. Useful for sending out marketing email and other nicely formatted messages.

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>"
      }
    }
  }
}