SparkPost logodev

Transmissions

Run in Postman
Import the SparkPost API as a Postman collection

The Transmissions endpoint lets you send email. Each transmission can send an email to a single recipient or thousands. SparkPost generates and sends messages using the options you've defined, a list of recipients, and the content given in transmissions call.

When creating a transmission, the options allow you to configure engagement tracking, sending optimization, global substitution data, and more to control how your emails are sent.

To set the recipients you can include all recipients in the request or use a stored recipient list. For each recipient, you can specify metadata and substitution data to personalize each email. You can also set the transmission to treat certain recipients as CC'd or BCC'd.

The content of the messages can be set in 4 different ways: inline content, a stored template, an A/B test, or raw RFC822 content. Each method has different use cases they are best suited for. All of these types of content can use the substitution data and metadata to create a unique message for each recipient.

Learn about how to optimize your sending with SparkPost.

The Sandbox Domain

The sandbox domain allows you to send your first email without setting up a sending domain. You can send up to 5 sandbox messages over the lifetime of your account. To send a message from the sandbox domain, set the options.sandbox to true, and set content.template_id to my-first-email. The from address in the template my-first-email should be support@sparkpostbox.com. You can only use the sandbox domain with the my-first-email template.

For more extensive testing with your own sending domain, use the SparkPost Sink Server.

Sending Limits

Your account has a sandbox, daily, and monthly sending limit based on your current plan level. You can view your current limits on your dashboard (EU). If a transmission will push you over the sandbox, daily, or monthly sending limit, an error with the status code 420 is returned, along with a message detailing which limit you will exceed. If this happens, no messages are sent, regardless of the number of messages in the transmission that will push you past your limit.

Learn more about these limits and what counts towards usage.

{
  "errors": [
    {
      "message": "Exceed Sending Limit (hourly)",
      "code": "2101"
    }
  ]
}

Create a Transmission

You can create a transmission in a number of ways. In all cases, you can use the num_rcpt_errors parameter to limit the number of recipient errors returned.

Parameters

num_rcpt_errors number

Maximum number of recipient errors that this call can return, otherwise all validation errors are returned.

Request Body

Example

{
  "options": {
    "click_tracking": false,
    "transactional": true,
    "ip_pool": "my_ip_pool",
    "inline_css": true
  },
  "description": "Christmas Campaign Email",
  "campaign_id": "christmas_campaign",
  "metadata": {
    "user_type": "students",
    "education_level": "college"
  },
  "substitution_data": {
    "sender": "Big Store Team",
    "holiday_name": "Christmas"
  },
  "recipients": [
    {
      "address": {
        "email": "wilma@flintstone.com",
        "name": "Wilma Flintstone"
      },
      "tags": [
        "prehistoric"
      ],
      "metadata": {
        "age": "24",
        "place": "Bedrock"
      },
      "substitution_data": {
        "customer_type": "Platinum",
        "year": "Freshman"
      }
    }
  ],
  "content": { ... }
}

Request Body

options object

Object containing transmission options. If an option is not set, the template-level option is used.

recipients array or object required

Array of recipient objects or a single object containing a stored recipient list.

content object required

Content used to generate the messages. The content can be set in 4 different ways: inline content, stored template, A/B test, or RFC822 content.

campaign_id string

Name of the campaign. Maximum length - 64 bytes

description string

Description of the transmission. Maximum length - 1024 bytes

metadata object

Transmission level metadata. Metadata is available in Webhook events and can also be used in the template language. Recipient metadata takes precedence over transmission metadata. Maximum length - 10KB.

substitution_data object

Object of data passed to the template language in the content. Recipient substitution data takes precedence over transmission substitution data. Maximum length - 100KB

return_path string

Email address to use for envelope FROM. The domain of the return_path address must be a CNAME-verified sending domain. The local part of the return_path address will be overwritten by SparkPost.

For Enterprise accounts, the return_path may be any valid email address and the local part in the return_path will not be overwritten by SparkPost. To support Variable Envelope Return Path (VERP), this field can be specified in each recipient object in order to give the recipients unique envelope MAIL FROM addresses.




Stored Recipient List

The following recipients attributes should be set in the recipients object when using a stored recipient list:

Example

{
  "recipients": {
    "list_id": "christmas_sales_2013"
  },
  "content": {
    "from": {
      "name": "Our Store",
      "email": "deals@example.com"
    },
    "subject": "Big Christmas savings!",
    "text": "Hi {{name}} \nSave big this Christmas in your area {{place}}! \nClick http://www.mysite.com and get huge discount\n Hurry, this offer is only to {{user_type}}\n {{sender}}",
    "html": "<p>Hi {{name}} \nSave big this Christmas in your area {{place}}! \nClick http://www.mysite.com and get huge discount\n</p><p>Hurry, this offer is only to {{user_type}}\n</p><p>{{sender}}</p>"
  },
  ...
}

Recipients Attributes

list_id string required

ID of the stored recipient list to use.

Create a transmission using a stored recipients list by specifying the list_id in the recipients attribute.




Request

POST /api/v1/transmissions/{?num_rcpt_errors}
  {
      "options": {
          "open_tracking": true,
          "click_tracking": true
      },
      "metadata": {
          "user_type": "students",
          "education_level": "college"
      },
      "substitution_data": {
          "discount": "25"
      },
      "recipients": [
          {
              "address": {
                  "email": "wilma@flintstone.com",
                  "name": "Wilma Flintstone"
              },
              "substitution_data": {
                  "customer_type": "Platinum",
              }
          }
      ],
      "content": {
          "from": {
              "name": "Fred Flintstone",
              "email": "fred@flintstone.com"
          },
          "subject": "Big Christmas savings!",
          "reply_to": "Christmas Sales <sales@flintstone.com>",
          "headers": {
              "X-Customer-Campaign-ID": "christmas_campaign"
          },
          "html": "<p>Hi {{address.name}} \nSave big this Christmas in your area {{place}}! \nClick http://www.mysite.com and get a {{discount}}% discount\n</p><p>Hurry, this offer is only to {{user_type}}\n</p>"
      }
  }

Response

{
  "results": {
    "total_rejected_recipients": 0,
    "total_accepted_recipients": 1,
    "id": "11668787484950529"
  }
}

{
  "errors": [
    {
      "description": "Unconfigured or unverified sending domain.",
      "code": "7001",
      "message": "Invalid domain"
    }
  ]
}

Send Inline Content

POST/api/v1/transmissions/{?num_rcpt_errors}

The template language is supported in from, subject, text, html, amp_html, reply_to, and headers. The following attributes are used when specifying inline content in the transmission's content object:

Content Attributes

from string or object required

Email address used to compose the email's From header. The domain must be a verified sending domain. Can be a string with a valid email address or an object with the following attributes:

subject string required

Email subject line. Expected in the UTF-8 charset without RFC2047 encoding.

html string

HTML content for the email's text/html MIME part. At a minimum, html or text is required. Expected in the UTF-8 charset with no Content-Transfer-Encoding applied.

text string

Text content for the email's text/plain MIME part. At a minimum, html or text is required. Expected in the UTF-8 charset with no Content-Transfer-Encoding applied.

amp_html string

AMPHTML Email content for the email's text/x-amp-html MIME part. At least one of content.html or content.text must also be provided. Expected in the UTF-8 charset with no Content-Transfer-Encoding applied.

reply_to string

Email address used to compose the email's "Reply-To" header.

headers object

Object containing headers other than Subject, From, To, and Reply-To . See the Header Notes.

attachments array of objects

Array of attachments. For a full description, see Attachment Object.

inline_images array of objects

Array of inline images For a full description, see Inline Image Object.

Header Notes

  • Headers such as Content-Type and Content-Transfer-Encoding are not allowed, as they are auto-generated upon construction of the email.

  • The To header should not be specified, since it is generated from each recipient's address field.

  • Each header value is expected in the UTF-8 charset without RFC2047 encoding.

  • The template language is supported in headers.

Attachment Object

Attachments for a transmission are specified in the content.attachments array where each object in the array is described by the following attributes:

Example

{
  "name": "billing.pdf",
  "type": "application/pdf",
  "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
}

Attributes

name string required

The filename of the attachment. This is inserted into the filename parameter of the Content-Disposition header. Maximum length - 255 bytes

type string required

The MIME type of the attachment. The value will apply as-is to the Content-Type header of the generated MIME part for the attachment.
Include the charset parameter, if needed (e.g. text/html; charset="UTF-8")

data string required

The content of the attachment as a Base64 encoded string. The string should not contain \r\n line breaks. SparkPost will add line breaks as necessary to ensure the Base64 encoded lines contain no more than 76 characters each.

Inline Image Object

Insert inline images into your HTML using <img src="cid:NAME" />, where NAME is the value you set in the name attribute.

Inline images for a transmission are specified in the content.inline_images array where each object in the array is described by the following attributes:

Example

{
  "name": "my_image.jpeg",
  "type": "image/jpeg",
  "data": "VGhpcyBkb2Vzbid0IGxvb2sgbGlrZSBhIGpwZWcgdG8gbWUh"
}

Attributes

name string required

The name of the image, which will be inserted into the Content-ID header. The name must be unique within the content.inline_images array. Maximum length - 255 bytes

type string required

The MIME type of the image. The value will apply as-is to the Content-Type header of the generated MIME part for the image.

data string required

The content of the image as a Base64 encoded string. The string should not contain \r\n line breaks. SparkPost will add line breaks as necessary to ensure the Base64 encoded lines contain no more than 76 characters each.

Request

POST /api/v1/transmissions/{?num_rcpt_errors}
{
  "content": {
    "template_id": "black_friday",
    "use_draft_template": true
  },
  "substitution_data": {
    "discount": "25%"
  },
  "recipients": [
    {
      "address": {
        "email": "wilma@flintstone.com",
        "name": "Wilma Flintstone"
      },
      "substitution_data": {
        "first_name": "Wilma",
        "last_name": "Flintstone"
      }
    }
  ]
}

Response

{
  "errors": [
    {
      "message": "transmission created, but with validation errors",
      "code": "2000"
    }
  ],
  "results": {
    "rcpt_to_errors": [
      {
        "message": "required field is missing",
        "description": "address.email is required for each recipient",
        "code": "1400"
      }
    ],
    "total_rejected_recipients": 1,
    "total_accepted_recipients": 1,
    "id": "11668787484950530"
  }
}

{
  "errors": [
    {
      "message": "Subresource not found",
      "description": "template 'christmas_offer' does not exist",
      "code": "1603"
    }
  ]
}

Send a Template

POST/api/v1/transmissions/{?num_rcpt_errors}

The following attributes should be set in the content object when using a template as the transmission's content:

Content Attributes

template_id string required

ID of the template to use.

use_draft_template boolean, default is false

Whether to use the draft version. If this is set to true and no draft exists, the transmission will fail.

Request

POST /api/v1/transmissions/{?num_rcpt_errors}
{
  "content": {
    "ab_test_id": "password_reset"
  },
  "recipients": [
    {
      "address": {
        "email": "wilma@flintstone.com",
        "name": "Wilma Flintstone"
      },
      "substitution_data": {
        "first_name": "Wilma",
        "last_name": "Flintstone"
      }
    }
  ]
}

Response

{
  "results": {
    "total_rejected_recipients": 0,
    "total_accepted_recipients": 1,
    "id": "11668787493850529"
  }
}

{
  "errors": [
    {
      "message": "Subresource not found",
      "description": "ab_test_id 'password_reset' does not exist",
      "code": "1603"
    }
  ]
}

Send an A/B Test

POST/api/v1/transmissions/{?num_rcpt_errors}

The following attribute should be set in the content object when sending an A/B test as the transmission's content:

Content Attributes

ab_test_id string required

ID of the A/B test to use.

When using substitution data with A/B tests, data for all possible templates must be provided. We recommend that all templates that make up an A/B test should use the same substitution data fields.

Request

POST /api/v1/transmissions/{?num_rcpt_errors}
{
  "description": "Christmas Campaign Email",
  "recipients": [
    {
      "address": {
        "email": "wilma@flintstone.com",
        "name": "Wilma Flintstone"
      },
      "substitution_data": {
        "first_name": "Wilma",
        "customer_type": "Platinum",
        "year": "Freshman"
      }
    }
  ],
  "content": {
    "email_rfc822": "Content-Type: text/plain\r\nTo: \"{{address.name}}\" <{{address.email}}>\r\n\r\n Hi {{first_name}} \nSave big this Christmas in your area {{place}}! \nClick http://www.mysite.com and get huge discount\n Hurry, this offer is only to {{customer_type}}\n {{sender}}\r\n"
  }
}

Response

{
  "results": {
    "total_rejected_recipients": 0,
    "total_accepted_recipients": 2,
    "id": "11668787484950529"
  }
}

{
  "errors": [
    {
      "description": "Unconfigured or unverified sending domain.",
      "code": "7001",
      "message": "Invalid domain"
    }
  ]
}

Send RFC822 Content

POST/api/v1/transmissions/{?num_rcpt_errors}

The following attribute should be set in the content object when sending RFC822 content as the transmission's content:

RFC 822 Content

email_rfc822 string

Pre-built message with the format as described by the message/rfc822 Content-Type.

  • Substitutions will be applied in the top-level headers and the first non-attachment text/plain, text/html, and text/x-amp-html MIME parts only.

  • If text/x-amp-html is used, it must be a descendant of multipart/alternative, alongside at least one other text/html or text/plain MIME part.

  • Lone LFs and lone CRs are allowed. SparkPost converts line endings to CRLF where necessary.

  • It should NOT be dot stuffed. SparkPost dot stuffs before sending the email.

  • It should NOT contain the SMTP terminator \r\n.\r\n. SparkPost adds this terminator. The provided email_rfc822 in MIME format will be rejected if SparkPost cannot parse the contents into a MIME tree.

Content headers are not generated for transmissions providing RFC822 content. They are expected to be provided as headers contained in the RFC822 content.

Scheduled Transmissions

Request

POST /api/v1/transmissions/
{
  "name": "Fall Sale",
  "campaign_id": "fall",
  "options": {
    "start_time": "2018-09-11T08:00:00-04:00"
  },
  "recipients": {
    "list_id": "all_subscribers"
  },
  "content": {
    "template_id": "fall_deals"
  }
}

Response

{
  "results": {
    "total_rejected_recipients": 1000,
    "total_accepted_recipients": 0,
    "id": "11668787484950529"
  }
}

Schedule a Transmission

POST/api/v1/transmissions/

Create a scheduled transmission to be generated and sent at a future time by specifying start_time in the options attribute. The scheduled start time cannot be more than 3 days in the future.

Templates in Scheduled Transmissions

Transmissions scheduled with a template will use the version of the template available at the scheduled time of generation. This means updates to the template made between scheduling the transmission and time of generation will be reflected in the transmission. Once message generation has been initiated, all emails in the transmission will be generated using the template version available at the start of the generation. If a template update is made during the generation of a transmission that uses that template, the template update will succeed, but the transmission will continue to use the version that was available at the start of the generation.

Request

GET /api/v1/transmissions/11714265276872

Response

{
  "results": {
    "transmission": {
      "id": "11750520427380741",
      "description": "",
      "state": "Success",
      "campaign_id": "white_christmas",
      "content": {
        "template_id": "Bob's template",
        "use_draft_template": false
      },
      "rcpt_list_chunk_size": 100,
      "rcpt_list_total_chunks": 1,
      "num_rcpts": 10,
      "num_generated": 10,
      "num_failed_gen": 0,
      "generation_start_time": "2014-05-22T15:12:59+00:00",
      "generation_end_time": "2014-05-22T15:13:00+00:00",
      "substitution_data": "",
      "metadata": {
        "is_snowing": "yes"
      },
      "options": {
        "open_tracking": "",
        "click_tracking": ""
      }
    }
  }
}

{
  "errors": [
    {
      "message": "resource not found",
      "description": "Resource not found:transmission id 123",
      "code": "1600"
    }
  ]
}

Retrieve a Scheduled Transmission

GET/api/v1/transmissions/{id}

Parameters

id number required

Returns details about a scheduled transmission. The response for a transmission using an inline content will include "template_id":"inline". Inline content cannot be specifically queried.

Request

DELETE /api/v1/transmissions/11714265276872

Response

// Empty response body

{
  "errors": [
    {
      "message": "resource not found",
      "code": "1600",
      "description": "Resource not found:transmission id 999999999"
    }
  ]
}

{
  "errors": [
    {
      "message": "too close to generation time to delete transmission",
      "code": "2003",
      "description": "Deletion time window (660 seconds) doesn't permit transmission deletion"
    }
  ]
}

{
  "errors": [
    {
      "message": "transmission database record is in an invalid state for deletion",
      "code": "2006",
      "description": "Unable to delete a transmission that is in progress (state=Generating)"
    }
  ]
}

Delete a Scheduled Transmission

DELETE/api/v1/transmissions/{id}

Parameters

id number required

Only transmissions which are scheduled for future generation may be deleted.

Request

DELETE /api/v1/transmissions?campaign_id=white-christmas

Response

// Empty response body

Delete Scheduled Transmissions By Campaign ID

DELETE/api/v1/transmissions{?campaign_id}

Parameters

campaign_id string required

Delete all transmissions in a campaign.

Please note that this endpoint immediately returns a 204 response and the deletion process happens in the background. When a message is deleted, you will receive a bounce event with a reason of "554 5.7.1 [internal] Campaign cancelled". You can consume these events via the Events API and Event Webhooks. You can also view statistics about these events via the Metrics API.

Please also note that if you wish to cancel a transmission scheduled by a subaccount, you must make the request as the subaccount, i.e., by specifying the subaccount ID in the X-MSYS-SUBACCOUNT header as the primary account or by using an API key associated with the subaccount.