{"componentChunkName":"component---src-templates-api-js","path":"/api/smtp/","result":{"data":{"allApiBlueprint":{"edges":[{"node":{"meta":{"title":"A/B Testing API","label":"New"},"fields":{"path":"/api/ab-testing/","file":"ab-testing.apib"}}},{"node":{"meta":{"title":"Data Privacy API","label":"New"},"fields":{"path":"/api/data-privacy/","file":"data-privacy.apib"}}},{"node":{"meta":{"title":"Events API","label":null},"fields":{"path":"/api/events/","file":"events.apib"}}},{"node":{"meta":{"title":"Ingest API","label":"Private Access"},"fields":{"path":"/api/events-ingest/","file":"events-ingest.apib"}}},{"node":{"meta":{"title":"Inbound Domains API","label":null},"fields":{"path":"/api/inbound-domains/","file":"inbound-domains.apib"}}},{"node":{"meta":{"title":"Account API","label":null},"fields":{"path":"/api/account/","file":"account.apib"}}},{"node":{"meta":{"title":"API Overview","label":null},"fields":{"path":"/api/","file":"index.apib"}}},{"node":{"meta":{"title":"Automatic Inline Seeding","label":"Deliverability"},"fields":{"path":"/api/inline-seeds/","file":"inline-seeds.apib"}}},{"node":{"meta":{"title":"Labs APIs","label":null},"fields":{"path":"/api/labs/","file":"labs.apib"}}},{"node":{"meta":{"title":"Message Events API","label":null},"fields":{"path":"/api/message-events/","file":"message-events.apib"}}},{"node":{"meta":{"title":"Recipient Validation API","label":"New"},"fields":{"path":"/api/recipient-validation/","file":"recipient-validation.apib"}}},{"node":{"meta":{"title":"IP Pools API","label":null},"fields":{"path":"/api/ip-pools/","file":"ip-pools.apib"}}},{"node":{"meta":{"title":"Seed List API","label":"Deliverability"},"fields":{"path":"/api/seed-list/","file":"seed-list.apib"}}},{"node":{"meta":{"title":"Bounce Domains API","label":null},"fields":{"path":"/api/bounce-domains/","file":"bounce-domains.apib"}}},{"node":{"meta":{"title":"Recipient Lists API","label":null},"fields":{"path":"/api/recipient-lists/","file":"recipient-lists.apib"}}},{"node":{"meta":{"title":"Sending IPs API","label":null},"fields":{"path":"/api/sending-ips/","file":"sending-ips.apib"}}},{"node":{"meta":{"title":"Relay Webhooks API","label":null},"fields":{"path":"/api/relay-webhooks/","file":"relay-webhooks.apib"}}},{"node":{"meta":{"title":"SMTP API","label":null},"fields":{"path":"/api/smtp/","file":"smtp.apib"}}},{"node":{"meta":{"title":"Snippets API","label":"New"},"fields":{"path":"/api/snippets/","file":"snippets.apib"}}},{"node":{"meta":{"title":"Subaccounts API","label":null},"fields":{"path":"/api/subaccounts/","file":"subaccounts.apib"}}},{"node":{"meta":{"title":"Sending Domains API","label":null},"fields":{"path":"/api/sending-domains/","file":"sending-domains.apib"}}},{"node":{"meta":{"title":"Suppression List API","label":null},"fields":{"path":"/api/suppression-list/","file":"suppression-list.apib"}}},{"node":{"meta":{"title":"Template Language","label":null},"fields":{"path":"/api/template-language/","file":"template-language.apib"}}},{"node":{"meta":{"title":"Tracking Domains API","label":null},"fields":{"path":"/api/tracking-domains/","file":"tracking-domains.apib"}}},{"node":{"meta":{"title":"Templates API","label":null},"fields":{"path":"/api/templates/","file":"templates.apib"}}},{"node":{"meta":{"title":"Transmissions API","label":null},"fields":{"path":"/api/transmissions/","file":"transmissions.apib"}}},{"node":{"meta":{"title":"Event Webhooks API","label":null},"fields":{"path":"/api/webhooks/","file":"webhooks.apib"}}},{"node":{"meta":{"title":"Usage API","label":null},"fields":{"path":"/api/usage/","file":"usage.apib"}}},{"node":{"meta":{"title":"Metrics API","label":null},"fields":{"path":"/api/metrics/","file":"metrics.apib"}}}]},"apiBlueprint":{"ast":{"element":"parseResult","content":[{"element":"category","meta":{"classes":{"element":"array","content":[{"element":"string","content":"api"}]},"title":{"element":"string","content":""}},"attributes":{"meta":{"element":"array","content":[{"element":"member","meta":{"classes":{"element":"array","content":[{"element":"string","content":"user"}]}},"content":{"key":{"element":"string","content":"FORMAT"},"value":{"element":"string","content":"1A"}}},{"element":"member","meta":{"classes":{"element":"array","content":[{"element":"string","content":"user"}]}},"content":{"key":{"element":"string","content":"title"},"value":{"element":"string","content":"SMTP API"}}},{"element":"member","meta":{"classes":{"element":"array","content":[{"element":"string","content":"user"}]}},"content":{"key":{"element":"string","content":"description"},"value":{"element":"string","content":"Use the X-MSYS-API header to customize options for messages sent via SMTP."}}},{"element":"member","meta":{"classes":{"element":"array","content":[{"element":"string","content":"user"}]}},"content":{"key":{"element":"string","content":"full"},"value":{"element":"string","content":"true"}}}]}},"content":[{"element":"category","meta":{"classes":{"element":"array","content":[{"element":"string","content":"resourceGroup"}]},"title":{"element":"string","content":"SMTP API"}},"content":[{"element":"copy","content":"The SparkPost SMTP API offers an SMTP relay service with extended features available through the `X-MSYS-API` custom header.\n\nFor details on how to get the best out of SMTP delivery through SparkPost, see [this article](https://www.sparkpost.com/docs/tech-resources/smtp-rest-api-performance/).\n\n## Client Configuration\n\nTo use SparkPost as an SMTP relay you need to point your SMTP client or local MTA to the following endpoint:\n\n| Name                | Value                                                                    | Notes                                                                                                                                                     |\n| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Host                | `smtp.sparkpostmail.com`<br>`smtp.eu.sparkpostmail.com` for SparkPost EU |                                                                                                                                                           |\n| Port                | `587` or `2525`                                                          | Port 2525 is provided as an alternate port for cases where port 587<br>is blocked (such as a Google Compute Engine environment).                          |\n| Encryption          | `STARTTLS`                                                               |                                                                                                                                                           |\n| Authentication      | `AUTH LOGIN`                                                             |                                                                                                                                                           |\n| User                | `SMTP_Injection`                                                         |                                                                                                                                                           |\n| Password            | An API key with \"Send via SMTP\" permission                               | You can create and manage your API Keys from the [app](https://app.sparkpost.com/account/api-keys) ([EU](https://app.eu.sparkpost.com/account/api-keys)). |\n| Per-command Timeout | Minimum 60 seconds                                                       | See [RFC-5321](https://tools.ietf.org/html/rfc5321#section-4.5.3.2) for RFC recommended values.                                                           |\n\n<Banner status=\"info\">Enterprise accounts should contact their Technical Account Manager for SMTP details.</Banner>\n\n## SMTP Security\n\n<Banner status=\"danger\">Disabling TLS will cause all data sent through SparkPost to be sent over the public internet unencrypted.</Banner>\n\nSparkPost 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.\n\nSparkPost 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.\n\nIf TLS is not supported by your application, SparkPost recommends using API keys with _only_ the `Send via SMTP` privilege enabled.\nIt is also good practice to regularly cycle your API keys to limit exposure of keys sent in the clear.\nAPI keys should be treated like passwords. As stated in our <a href=\"https://www.sparkpost.com/policies/tou/\">Terms of Use</a>,\nyou \"are solely responsible for all use of [your account].\"\nThat includes use of your account with API key compromised on an unsecured connection.\n\n## Subaccounts\n\nTo 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:\n\n`SMTP_Injection:X-MSYS-SUBACCOUNT=123`\n\nto 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.\nWhen sending on behalf of a subaccount, a sending domain assigned to the subaccount must be used.\n\n## Using The X-MSYS-API Custom Header\n\nYou 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.\n\n<Banner status=\"info\">To use this option you should be familiar with how to encode options as JSON strings, as the value of the header field is a JSON object that specifies the relevant options</Banner>\n\n```\nX-MSYS-API: {\n  \"campaign_id\": \"my_campaign\",\n  \"metadata\" : {\n    \"has_pets\": true,\n    \"pet_name\": \"Spot\"\n  },\n  \"cc\": [\n    { \"email\": \"cc_recip_1@gmail.com\", \"name\": \"CC 1\" },\n    { \"email\": \"cc_recip_2@gmail.com\", \"name\": \"CC 2\" }\n  ],\n  \"bcc\": [\n    { \"email\": \"bcc_recip_1@gmail.com\", \"name\": \"BCC 1\" }\n    { \"email\": \"bcc_recip_2@gmail.com\", \"name\": \"BCC 2\" }\n  ],\n  \"archive\": [\n    { \"email\": \"archive_recip_1@gmail.com\", \"name\": \"Archive 1\" }\n    { \"email\": \"archive_recip_2@gmail.com\", \"name\": \"Archive 2\" }\n  ],\n  \"tags\": [\n    \"cat\",\n    \"dog\"\n  ],\n  \"options\" : {\n    \"open_tracking\": false,\n    \"click_tracking\": false,\n    \"transactional\": false,\n    \"skip_suppression\": false,\n    \"ip_pool\": \"my_ip_pool\",\n    \"inline_css\": false,\n    \"dkim_key\": \"marketing\"\n  }\n}\n```\n\n<Banner status=\"info\">The <a href=\"/api/template-language/\">template language</a> is not supported in SMTP API. Any `substitution_data` field provided in the X-MSYS-API header will be ignored.</Banner>\n\nThe fields supported in the X-MSYS-API header are as follows:\n\n<DataStructure id=\"e3187e84a0e8290d97f7cff03043ae30\"  title=\"X-MSYS-API Attributes\" ></DataStructure>\n\n### Open And Click Tracking\n\n<Banner status=\"info\"><strong><a href=\"https://www.sparkpost.com/enterprise-email/\">Enterprise accounts</a>:</strong> SMTP click and open tracking are <strong>enabled</strong> by default. Please check with your TAM if you are unsure of the setting in your own environment.</Banner>\n\nSMTP click and open tracking are <strong>disabled</strong> by default. To enable click and open tracking in SMTP messages, add the X-MSYS-API header as follows:\n\n```\nX-MSYS-API: { \"options\" : { \"open_tracking\" : true, \"click_tracking\" : true } }\n```\n\n<Banner status=\"info\"><strong>SparkPost customers:</strong> the <code>open_tracking</code> and <code>click_tracking</code> variables may also be set account-wide in your <a href=\"https://app.sparkpost.com/account/smtp\">SMTP relay account settings</a> (<a href=\"https://app.eu.sparkpost.com/account/smtp\">EU</a>).</Banner>\n\n## Sending Messages with cc, bcc, and archive Recipients\n\nWhen 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:\n\n-   It is the responsibility of the user to include their own `To` header in the body of the message.\n\n-   All messages will display the `Cc` header and the value of that header will include all addresses listed in the `cc` array.\n\n-   The `bcc` recipients will each receive a message with the `To` and `Cc` headers described above and, additionally, will see a `Bcc` header with ONLY their own recipient address as the value of the header.\n\n-   The `archive` recipients will each receive a message with the `To` and `Cc` headers described above however, they will not have a `Bcc` header.\n\nThe following are key points about reporting and tracking for cc, bcc, and archive messages:\n\n-   Each recipient (To, Cc, Bcc, and archive) is counted as a targeted message.\n\n-   A `rcpt_type` field is available during events through the Webhooks, which designates if the message was a Cc, Bcc, or archive copy.\n\n-   A `transmission_id` field is available during events through the Webhooks, which can be used to correlate the Cc, Bcc, and archive versions of the messages to one another.\n\n<Banner status=\"info\">Each recipient will only receive a single instance of each message, even if they appear on more than one of the CC, BCC or archive recipient lists.</Banner>\n\n#### What is an archive recipient?\n\nRecipients 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`.\n\nFor example:\n\n```\nX-MSYS-API: {\n   \"cc\" : [ \"cc_email1@corp.com\", \"cc_email2@corp.com\" ],\n   \"bcc\" : [ \"bcc_email1@corp.com\", \"bcc_email2@corp.com\" ],\n   \"archive\" : [ \"archive_email@corp.com\" ],\n   \"options\" : {\"open_tracking\" : false, \"click_tracking\" : true},\n}\n```\n\nYou may not specify more than a total of 1000 total recipients in those 3 lists.\n\nYou 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:\n\n```\nX-MSYS-API: {\n   \"cc\" : [\n    {\n    \"email\" : \"cc_recip_1@gmail.com\",\n    \"name\" : \"CC 1\"\n    },\n    {\n    \"email\" : \"cc_recip_2@gmail.com\",\n    \"name\" : \"CC 2\"\n    }\n  ]\n\n  \"bcc\" : [\n    {\n    \"email\" : \"bcc_recip_1@gmail.com\",\n    \"name\" : \"BCC 1\"\n    }\n  ]\n}\n```\n\n## Comments on Header Length\n\nSMTP defines a maximum line length of 1000 characters (including CRLF).  If the value of the `X-MSYS-API` JSON string is\nlonger than 998 characters, it will be folded across multiple lines before the message is injected.  An example\nof a folded header that will not have issues due to extra spaces:\n\n```\nX-MSYS-API: {\"options\" : {\"open_tracking\" : false, \"click_tracking\" : true},\n   \"metadata\" : {\"has_pets\" : true, \"pet_name\": \"Spot\" }, \"tags\" : [\"cat\",\n   \"dog\"], \"campaign_id\" : \"my_campaign\"}\n```\n\n<Banner status=\"warning\">When the <code>X-MSYS-API</code> header is unfolded on the receiving system, as per <a href=\"http://www.rfcreader.com/#rfc2822_line324\">RFC2822</a>, a single space will be added between each line of the header.</Banner>\n\nThe following example shows how the JSON object in an `X-MSYS-API` header can be corrupted as a result of folding and unfolding:\n\n```\nX-MSYS-API: {\"options\" : {\"open_tracking\" : false }, \"campaign_id\" : \"my_awes\n   ome_campaign\" }\n```\n\nWill be unfolded as\n\n```\nX-MSYS-API: {\"options\" : {\"open_tracking\" : false }, \"campaign_id\" : \"my_awes ome_campaign\" }\n```\n\nNote the space that was introduced in the `my_awes ome_campaign` string.\n\n## Non-ASCII characters\n\nIf 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 <a href=\"http://www.rfcreader.com/#rfc2047\">rfc2047</a>-encoded.\n\n## Invalid JSON\n\nIf the `X-MSYS-API` header contains invalid JSON, the SMTP message will be rejected with one of the following codes:\n\n| Code | Example                                                                                                                    |\n| ---- | -------------------------------------------------------------------------------------------------------------------------- |\n| 550  | `5.6.0 X-MSYS-API 'metadata' must be of type 'json object'`<br/>`5.6.0 smtpapi_campaign_id context is limited to 64 bytes` |\n| 421  | `4.3.3 [internal] smtpapi unable to generate unique transmission id`                                                       |\n\n## SMTP MAIL FROM\n\nIn 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.\nIf 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](/api/sending-domains/#sending-domains-post-verify-a-sending-domain).\n\n**Note:** SparkPost will **not** overwrite the MAIL FROM address for <a href=\"https://www.sparkpost.com/enterprise-email/\"><span class=\"label label-warning\"><strong>Enterprise</strong></span></a> accounts.\n\n## AMPHTML Email\n\nAMPHTML 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."}]},{"element":"category","meta":{"classes":{"element":"array","content":[{"element":"string","content":"dataStructures"}]}},"content":[{"element":"dataStructure","content":{"element":"object","meta":{"id":{"element":"string","content":"e3187e84a0e8290d97f7cff03043ae30"}},"content":[{"element":"member","meta":{"description":{"element":"string","content":"Name of the campaign to associate with the SMTP message <br /> Maximum length: 64 bytes"}},"content":{"key":{"element":"string","content":"campaign_id"},"value":{"element":"string"}}},{"element":"member","meta":{"description":{"element":"string","content":"JSON key value pairs associated with the SMTP message <br /> A maximum of 1000 bytes of metadata is available in click/open events."}},"content":{"key":{"element":"string","content":"metadata"},"value":{"element":"object"}}},{"element":"member","meta":{"description":{"element":"string","content":"Array of recipient addresses that will be included in the \"Cc\" header. A unique message with a unique tracking URL will be generated for each recipient in this list."}},"content":{"key":{"element":"string","content":"cc"},"value":{"element":"array"}}},{"element":"member","meta":{"description":{"element":"string","content":"Array of recipient addresses that will be hidden from all other recipients. A unique message with a unique tracking URL will be generated for each recipient in this list."}},"content":{"key":{"element":"string","content":"bcc"},"value":{"element":"array"}}},{"element":"member","meta":{"description":{"element":"string","content":"Array of recipient addresses that will be hidden from all other recipients. A unique message will be generated for each recipient in this list. The archive copy of the message contains tracking URLs identical to the recipient. For a full description, see [What is an archive recipient?](#header-what-is-an-archive-recipient?) section."}},"content":{"key":{"element":"string","content":"archive"},"value":{"element":"array"}}},{"element":"member","meta":{"description":{"element":"string","content":"Array of text labels associated with the SMTP message. Tags are available in click/open events. Maximum number of tags is 10 per recipient, 100 system wide."}},"content":{"key":{"element":"string","content":"tags"},"value":{"element":"array"}}},{"element":"member","meta":{"description":{"element":"string","content":"Object in which SMTP API options are defined."}},"content":{"key":{"element":"string","content":"options"},"value":{"element":"object","content":[{"element":"member","meta":{"description":{"element":"string","content":"Whether open tracking is enabled for this SMTP message [See notes](#header-open-and-click-tracking) for defaults."}},"content":{"key":{"element":"string","content":"open_tracking"},"value":{"element":"boolean"}}},{"element":"member","meta":{"description":{"element":"string","content":"Whether click tracking is enabled for this SMTP message. [See notes](#header-open-and-click-tracking) for defaults."}},"content":{"key":{"element":"string","content":"click_tracking"},"value":{"element":"boolean"}}},{"element":"member","meta":{"description":{"element":"string","content":"Whether message is [transactional](https://www.sparkpost.com/resources/infographics/email-difference-transactional-vs-commercial-emails/), for unsubscribe and suppression purposes<br/><span class=\"label label-info\"><strong>Note</strong></span> no List-Unsubscribe header is included in transactional messages."}},"content":{"key":{"element":"string","content":"transactional"},"value":{"element":"boolean","attributes":{"default":{"element":"boolean","content":false}}}}},{"element":"member","meta":{"description":{"element":"string","content":"Whether to ignore customer suppression rules, for this SMTP message only. <br /> <a href=\"https://www.sparkpost.com/enterprise-email/\"><span class=\"label label-warning\"><strong>Enterprise</strong></span></a> Defaults to false."}},"content":{"key":{"element":"string","content":"skip_suppression"},"value":{"element":"boolean"}}},{"element":"member","meta":{"description":{"element":"string","content":"The ID of a dedicated IP pool associated with your account. If this field is not provided, the account's default dedicated IP pool is used (if there are IPs assigned to it). <br /><span class=\"label label-primary\"><strong>SparkPost</strong></span> For more information on dedicated IPs, see the [Support Center](https://www.sparkpost.com/docs/deliverability/dedicated-ip-pools).<br /><a href=\"https://www.sparkpost.com/enterprise-email/\"><span class=\"label label-warning\"><strong>Enterprise</strong></span></a> accounts, contact your TAM for support details."}},"content":{"key":{"element":"string","content":"ip_pool"},"value":{"element":"string"}}},{"element":"member","meta":{"description":{"element":"string","content":"Whether to inline the CSS in `<style>` tags in the `<head>` in the HTML content.  Not performed on AMPHTML Email content."}},"content":{"key":{"element":"string","content":"inline_css"},"value":{"element":"boolean","attributes":{"default":{"element":"boolean","content":false}}}}},{"element":"member","meta":{"description":{"element":"string","content":"  Select which [DKIM key](/api/sending-domains/#sending-domains-get-list-dkim-keys) to sign the message with. Only keys with a verified DNS record can be used. When not set, the sending domain's default key is used. Specifying a non-existent or unverified key will result in a 400 error."}},"content":{"key":{"element":"string","content":"dkim_key"},"value":{"element":"string"}}}]}}}]}}]}]}]},"TableOfContents":[{"anchor":"#smtp-api","title":"SMTP API","children":[{"anchor":"#header-client-configuration","title":"Client Configuration"},{"anchor":"#header-smtp-security","title":"SMTP Security"},{"anchor":"#header-subaccounts","title":"Subaccounts"},{"anchor":"#header-using-the-x-msys-api-custom-header","title":"Using The X-MSYS-API Custom Header"},{"anchor":"#header-open-and-click-tracking","title":"Open And Click Tracking"},{"anchor":"#header-sending-messages-with-cc,-bcc,-and-archive-recipients","title":"Sending Messages with cc, bcc, and archive Recipients"},{"anchor":"#header-what-is-an-archive-recipient?","title":"What is an archive recipient?"},{"anchor":"#header-comments-on-header-length","title":"Comments on Header Length"},{"anchor":"#header-non-ascii-characters","title":"Non-ASCII characters"},{"anchor":"#header-invalid-json","title":"Invalid JSON"},{"anchor":"#header-smtp-mail-from","title":"SMTP MAIL FROM"},{"anchor":"#header-amphtml-email","title":"AMPHTML Email"}]}],"meta":{"title":"SMTP API","description":"Use the X-MSYS-API header to customize options for messages sent via SMTP.","full":true},"fields":{"path":"/api/smtp/"}}},"pageContext":{"file":"smtp.apib"}},"staticQueryHashes":["1319884646","1428769721","3859448388"]}