SMTP API

The SparkPost SMTP API offers an SMTP relay service with extended features available through the X-MSYS-API custom header.

For details on how to get the best out of SMTP delivery through SparkPost, see this article.

Client Configuration

To use SparkPost as an SMTP relay you need to point your SMTP client or local MTA to the following endpoint:

SMTP Security

SparkPost strongly recommends using TLS with SMTP to protect your message content, recipient information and API keys in transmission. This includes API keys and any details such as recipient email addresses and message content.

SparkPost recommends reusing existing connections to inject up to 100 messages each. After injecting 100 messages, the client SHOULD disconnect and establish a new connection. Additionally, SparkPost will automatically disconnect idle connections after 1 minute.

If TLS is not supported by your application, SparkPost recommends using API keys with only the Send via SMTP privilege enabled. It is also good practice to regularly cycle your API keys to limit exposure of keys sent in the clear. API keys should be treated like passwords. As stated in our Terms of Use, you "are solely responsible for all use of [your account]." That includes use of your account with API key compromised on an unsecured connection.

Subaccounts

To inject mail to an SMTP relay endpoint on behalf of a subaccount, modify your SMTP injection username to include the subaccount ID. For example, use:

SMTP_Injection:X-MSYS-SUBACCOUNT=123

to send as a subaccount that has an id of 123. The primary account's API key is still used as the password when sending on behalf of a Subaccount. When sending on behalf of a subaccount, a sending domain assigned to the subaccount must be used.

Using The X-MSYS-API Custom Header

You can use the X-MSYS-API header in your SMTP messages to specify a campaign id, metadata, tags, IP pool, CC, BCC, and archive recipient lists and disable open and/or click tracking.

X-MSYS-API: {
  "campaign_id": "my_campaign",
  "metadata" : {
    "has_pets": true,
    "pet_name": "Spot"
  },
  "cc": [
    { "email": "cc_recip_1@gmail.com", "name": "CC 1" },
    { "email": "cc_recip_2@gmail.com", "name": "CC 2" }
  ],
  "bcc": [
    { "email": "bcc_recip_1@gmail.com", "name": "BCC 1" }
    { "email": "bcc_recip_2@gmail.com", "name": "BCC 2" }
  ],
  "archive": [
    { "email": "archive_recip_1@gmail.com", "name": "Archive 1" }
    { "email": "archive_recip_2@gmail.com", "name": "Archive 2" }
  ],
  "tags": [
    "cat",
    "dog"
  ],
  "options" : {
    "open_tracking": false,
    "click_tracking": false,
    "transactional": false,
    "sandbox": false,
    "skip_suppression": false,
    "ip_pool": "my_ip_pool",
    "inline_css": false
  }
}

The fields supported in the X-MSYS-API header are as follows:

Open And Click Tracking

SMTP click and open tracking are disabled by default. To enable click and open tracking in SMTP messages, add the X-MSYS-API header as follows:

X-MSYS-API: { "options" : { "open_tracking" : true, "click_tracking" : true } }

The Sandbox Domain

The sandbox domain sparkpostbox.com is available to allow each account to send test messages in advance of configuring a real sending domain. Each SparkPost account has a lifetime allowance of 5 sandbox domain messages. That means one may send up to 5 test messages using From: something@sparkpostbox.com. Note that you can set the 'local part' (the part before the @) to any valid email local part.

Sending Messages with cc, bcc, and archive Recipients

When submitting an email via SMTP that includes the X-MSYS-API header, you may specify a JSON array for cc, bcc, and archive lists. For each address in each of these arrays, a message will be generated. Messages will be generated with the following headers:

The following are key points about reporting and tracking for cc, bcc, and archive messages:

What is an archive recipient?

Recipients in the archive list will receive an exact replica of the message that was sent to the RCPT TO address. In particular, any encoded links intended for the RCPT TO recipient will be identical in the archive messages. In contrast, recipients in the bcc list will have links encoded specific to their address. There will be some small differences between the RCPT TO message and the archive message, for example in headers that contain the delivery address like X-MSFBL and List-Unsubscribe.

For example:

X-MSYS-API: {
   "cc" : [ "cc_email1@corp.com", "cc_email2@corp.com" ],
   "bcc" : [ "bcc_email1@corp.com", "bcc_email2@corp.com" ],
   "archive" : [ "archive_email@corp.com" ],
   "options" : {"open_tracking" : false, "click_tracking" : true},
}

You may not specify more than a total of 1000 total recipients in those 3 lists.

You may also specify name and email keys in the cc and bcc JSON arrays in order to produce a friendly Cc or Bcc header. For example:

X-MSYS-API: {
   "cc" : [
    {
    "email" : "cc_recip_1@gmail.com",
    "name" : "CC 1"
    },
    {
    "email" : "cc_recip_2@gmail.com",
    "name" : "CC 2"
    }
  ]

  "bcc" : [
    {
    "email" : "bcc_recip_1@gmail.com",
    "name" : "BCC 1"
    }
  ]
}

Comments on Header Length

SMTP defines a maximum line length of 1000 characters (including CRLF). If the value of the X-MSYS-API JSON string is longer than 998 characters, it will be folded across multiple lines before the message is injected. An example of a folded header that will not have issues due to extra spaces:

X-MSYS-API: {"options" : {"open_tracking" : false, "click_tracking" : true},
   "metadata" : {"has_pets" : true, "pet_name": "Spot" }, "tags" : ["cat",
   "dog"], "campaign_id" : "my_campaign"}

The following example shows how the JSON object in an X-MSYS-API header can be corrupted as a result of folding and unfolding:

X-MSYS-API: {"options" : {"open_tracking" : false }, "campaign_id" : "my_awes
   ome_campaign" }

Will be unfolded as

X-MSYS-API: {"options" : {"open_tracking" : false }, "campaign_id" : "my_awes ome_campaign" }

Note the space that was introduced in the my_awes ome_campaign string.

Non-ASCII characters

If non-ASCII characters are present in the campaign_id, tags, or metadata fields, they must be escaped using the \u Unicode code point format (\n becomes \u000A), or rfc2047-encoded.

Invalid JSON

If the X-MSYS-API header contains invalid JSON, the SMTP message will be rejected with one of the following codes:

SMTP MAIL FROM

In many cases the SMTP MAIL FROM (or "envelope from") address may be any email address. The address will be overwritten with a SparkPost specific email address before the email is delivered. If you would like SparkPost to deliver the email with a custom MAIL FROM domain then the domain specified in the MAIL FROM address must be set up ahead of time as a CNAME-verified sending domain.

Note: SparkPost will not overwrite the MAIL FROM address for Enterprise accounts.

AMPHTML Email

AMPHTML Email content may be provided in a text/x-amp-html MIME part. text/x-amp-html must be a descendant of multipart/alternative, alongside at least one other text/html or text/plain MIME part.