The X-SMTPAPI header is a JSON-encoded associative array consisting of several sections, below are examples of JSON strings using each section.

    • To: An array of addresses to send the message to.
{"to": ["ben@sendgrid.com", "joe@sendgrid.com"]}
    • Substitution: An associative array of substitution tags, where each tag is associated with a list of replacement text for the tag in the body text. Each Substitution value corresponds to an email in the “To” section of the JSON string.
{"sub":{"%name%": ["Ben", "Joe"], "%role%": ["%sellerSection%", "%buyerSection%"]}}
    • Section: Sections can be used to simplify substitution values that are common to many recipients. This is an associative array of sections that can be used in substitution values.
{"section":{"%sellerSection%": "Seller information for: %name%", "%buyerSection%": "Buyer information for: %name%"}}
    • Category: Associates the category of email this should be logged as. You may insert up to 10 categories as an array, these categories are not predefined.
{"category": [“category1”,”category2”]}
    • Unique Arguments: An associative array of arguments and their values to be applied to all emails sent in this SMTP API transaction.
{"unique_args": {"orderNumber": "12345", "eventID": "6789"}}
    • Apps: An associative array of filters and their settings, used to override filter settings already setup for your account. Settings are an associative array of the setting names and their values.
{"filters": {"footer": {"settings": {"enable":1,"text/plain": "Thank you for
your business"}}}}

All of the above examples can then be combined into one larger JSON string placed in a header named X-SMTPAPI, and would look like this:

X-SMTPAPI: {
    "to": [
        "ben@sendgrid.com",
        "joe@sendgrid.com"
    ],
    "sub": {
        "%name%": [
            "Ben",
            "Joe"
        ],
        "%role%": [
            "%sellerSection%",
            "%buyerSection%"
        ]
    },
    "section": {
        "%sellerSection%": "Seller information for: %name%",
        "%buyerSection%": "Buyer information for: %name%"
    },
    "category": "Orders",
    "unique_args": {
        "orderNumber": "12345",
        "eventID": "6789"
    },
    "filters": {
        "footer": {
            "settings": {
                "enable": 1,
                "text/plain": "Thank you for your business"
            }
        }
    }
}

The above header is line broken at each JSON section for readability, please note that headers must be “folded” to keep the line length under 72. By RFC 821 no line can be longer than 1,000, so if you are going to generate this string yourself it is a good idea to make sure that you “fold” it.

Here is a full example of generating the above JSON header in a Perl script:

#!/usr/bin/perl
use strict;
use JSON;

my $header = { to => ['ben@sendgrid.com', 'joe@sendgrid.com],
sub => { '%name%' => [ 'Ben', 'Joe' ], '%role%' =>; [ 'sellerSection', 'buyerSection' ] },
section => { '%sellerSection%' =>; 'Seller information for: %name%', '%buyerSection%' => 'Buyer information for: %name%' },
category => 'Orders',
unique_args => { 'orderNumber' => '12345', 'eventID' => '6789' },
filters => { 'footer' => {'settings' => {'text/plain' => "Thank you for your business"}}}};

my $json = JSON->new;
$json->space_before(1);
$json->space_after(1);
my $js = $json->encode($header);
# This regex breaks the string up at whitespaces to keep the line length short
$js =~ s/(.{1,72})(\s)/$1\n   /g;
my $hdr = "X-SMTPAPI: $js";
print "$hdr\n";