Transmissions

A transmission is a collection of messages belonging to the same campaign. It is also known as a mailing. The Transmissions API provides the means to create and manage transmissions - to send messages.

SparkPost generates and sends the messages from your transmissions using a list of recipients and a message template. You can store a recipient list, or you can include recipients “inline” with your transmission request. Similarly, you can store your message template or include it “inline” with your transmission request. SparkPost then sends a unique message to each recipient using the specified template. You may also choose to personalise your messages by including substitution variables in your transmissions. You can learn about templates and substitution here. Finally, you can enable engagement tracking in your transmissions to track message opens and clicks.

For details on how to get the best out of SparkPost Transmission, see this support article.

Using Postman

If you use Postman you can click the following button to import the SparkPost API as a collection:

Run in Postman

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. To send a test message from the sandbox domain, set content.from.email field to localpart@sparkpostbox.com and ensure options.sandbox is set to true.

Note: you can set the 'local part' (the part before the @) to any valid email local part. See below for more details on sending mail.
Note: SparkPost accounts only. SparkPost Enterprise accounts should consider using the SparkPost Sink Server.

Transmission Attributes

Field Type Description Required Notes
id string ID of the transmission no Read only. A unique ID is generated for each transmission on submission.
state string State of the transmission no Read only. Valid responses are submitted, Generating, Success, or Canceled.
options JSON object JSON object in which transmission options are defined no For a full description, see Options Attributes.
recipients JSON array or JSON object Inline recipient objects or object containing stored recipient list ID yes Specify a stored recipient list or specify recipients inline. When using a stored recipient list, specify the list_id as described in Using a Stored Recipient List. Otherwise, provide the recipients inline using the fields described in the Recipient List API documentation for Recipient Attributes.
campaign_id string Name of the campaign no Maximum length - 64 bytes
description string Description of the transmission no Maximum length - 1024 bytes
metadata JSON object Transmission level metadata containing key/value pairs no Metadata is available during events through the Webhooks and is provided to the substitution engine. A maximum of 1000 bytes of merged metadata (transmission level + recipient level) is available with recipient metadata taking precedence over transmission metadata when there are conflicts.
substitution_data JSON object Key/value pairs that are provided to the substitution engine no Recipient substitution data takes precedence over transmission substitution data. Unlike metadata, substitution data is not included in Webhook events.
return_path string Email address to use for envelope FROM no For SparkPost accounts, the domain part 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 servers.

For Enterprise accounts, the return_path may be any valid email address and the localpart in the return_path will not be overwritten by SparkPost servers. To support Variable Envelope Return Path (VERP), this field can also optionally be specified inside each recipient object in order to give the recipients unique envelope MAIL FROM addresses.
content JSON object Content that will be used to construct a message yes Specify a stored template or specify inline template content. When using a stored template, specify the template_id as described in Using a Stored Template. Otherwise, provide the inline content using the fields described in Inline Content Attributes. Maximum size - 20MBs
total_recipients number Computed total recipients no Read only
num_generated number Computed total number of messages generated no Read only
num_failed_generation number Computed total number of failed messages no Read only
num_invalid_recipients number Number of recipients that failed input validation no Read only

Options Attributes

Field Type Description Required Notes
start_time string Delay generation of messages until this datetime. For additional information, see Scheduled Transmissions. no - defaults to immediate generation Format YYYY-MM-DDTHH:MM:SS±HH:MM. Example: 2017-02-11T08:00:00-04:00.
open_tracking boolean Whether open tracking is enabled for this transmission no If not specified, the setting at template level is used, or defaults to true.
click_tracking boolean Whether click tracking is enabled for this transmission no If not specified, the setting at template level is used, or defaults to true.
transactional boolean Whether message is transactional for unsubscribe and suppression purposes
Note no List-Unsubscribe header is included in transactional messages.
no If not specified, the setting at template level is used, or defaults to false.
sandbox boolean Whether to use the sandbox sending domain no Defaults to false. SparkPost accounts may use the sandbox
skip_suppression boolean Whether to ignore customer suppression rules, for this transmission only. no Enterprise Defaults to false.
ip_pool string 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). To explicitly bypass the account’s default dedicated IP pool and instead fallback to the shared pool, specify a value of sp_shared. no SparkPost accounts may use IP pools. For more information on dedicated IPs, see the Support Center
inline_css boolean Whether to perform CSS inlining in HTML content
Note only rules in head > style elements will be inlined
no - Defaults to false

Inline Content Attributes

The following attributes are used when specifying inline content in the transmission’s content JSON object.

Note: the following attributes should not be present when using a stored template.
Note: one of html, text, or push is required. Email transmissions have additional required fields.
Field Type Description Required Notes
html string HTML content for the email’s text/html MIME part yes, for email Expected in the UTF-8 charset with no Content-Transfer-Encoding applied. Substitution syntax is supported.
text string Text content for the email’s text/plain MIME part yes, for email Expected in the UTF-8 charset with no Content-Transfer-Encoding applied. Substitution syntax is supported.
push JSON object Content of push notifications yes, for push Enterprise See Push Attributes.
subject string Email subject line yes, for email Expected in the UTF-8 charset without RFC2047 encoding. Substitution syntax is supported.
from string or JSON Address "from" : "deals@company.com" or JSON object composed of the name and email fields "from" : { "name" : "My Company", "email" : "deals@company.com" } used to compose the email’s From header yes, for email Substitution syntax is supported.
reply_to string Email address used to compose the email’s “Reply-To” header no Substitution syntax is supported.
headers JSON JSON dictionary containing headers other than Subject, From, To, and Reply-To no See the Header Notes.
attachments JSON JSON array of attachments. no For a full description, see Attachment Attributes.
inline_images JSON JSON array of inline images. no For a full description, see Inline Image Attributes.

Push Attributes

The following attributes control the contents of push notifications:

SparkPost Enterprise accounts may send push notifications. Contact your TAM for setup assistance.
Field Type Description Required Notes
apns JSON object payload for APNs messages At a minimum, apns or gcm is required Used for any push notifications sent to apns devices (See Multichannel Address attributes). This payload is delivered as is. See Apple’s APNs documentation for details
gcm JSON object payload for GCM messages At a minimum, apns or gcm is required Used for any push notifications sent to gcm devices (See Multichannel Address attributes). This payload is delivered as is. See Google’s Notification Payload Support

Header Notes

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

  • The To header should not be specified here, since it is generated from each recipient’s address.name and address.email.

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

  • Substitution syntax is supported.

email_rfc822 Notes

Alternately, the content JSON object may contain a single email_rfc822 field. email_rfc822 is mutually exclusive with all of the above fields.

Field Type Description Required
email_rfc822 string Pre-built message as specified by the message/rfc822 Content-Type no
  • Substitutions will be applied in the top-level headers and the first non-attachment text/plain and first non-attachment text/html MIME parts only.

  • Lone LFs and lone CRs are allowed. The system will convert line endings to CRLF where necessary.

  • The provided email_rfc822 should NOT be dot stuffed. The system dot stuffs before sending the outgoing message.

  • The provided email_rfc822 should NOT contain the SMTP terminator \r\n.\r\n. The system always adds this terminator.

  • The provided email_rfc822 in MIME format will be rejected if SparkPost cannot parse the contents into a MIME tree.

Attachment Attributes

Sending attachments with malicious content is strictly prohibited by SparkPost. This includes (and is not limited to) files with `bat` and `exe` extensions.

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

Field Type Description Required Notes
type string The MIME type of the attachment; e.g., text/plain, image/jpeg, audio/mp3, video/mp4, application/msword, application/pdf, etc., including the charset parameter (ex: text/html; charset="UTF-8") if needed. The value will apply as-is to the Content-Type header of the generated MIME part for the attachment. yes
name string The filename of the attachment (for example, document.pdf). This is inserted into the filename parameter of the Content-Disposition header. yes Maximum length - 255 bytes
data string The content of the attachment as a Base64 encoded string. The string should not contain \r\n line breaks. The SparkPost systems will add line breaks as necessary to ensure the Base64 encoded lines contain no more than 76 characters each. yes The entirety of transmission content (text + html + attachments + inline images) is limited to 20 MBs

Inline Image Attributes

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

Field Type Description Required Notes
type string The MIME type of the image; e.g., image/jpeg. The value will apply as-is to the Content-Type header of the generated MIME part for the image. yes
name string The name of the inline image, which will be inserted into the Content-ID header. The image should be referenced in your HTML content using <img src="cid:THIS_NAME" />. The name must be unique within the content.inline_images array. yes Maximum length - 255 bytes
data string The content of the image as a Base64 encoded string. The string should not contain \r\n line breaks. The SparkPost systems will add line breaks as necessary to ensure the Base64 encoded lines contain no more than 76 characters each. yes The entirety of transmission content (text + html + attachments + inline images) is limited to 20 MBs

Using a Stored Template

The following attributes are used when specifying a stored template in the transmission’s content JSON object. Note that these attributes should not be present when using inline content.

Field Type Description Required Notes
template_id string ID of the stored template to use yes Specify this field when using a stored template. Maximum length – 64 bytes
use_draft_template boolean Whether to use a draft template no - defaults to false If this field is set to true and no draft template exists, the transmission will fail.

Using a Stored Recipient List

The following recipients attribute is used when specifying a stored recipient list in the transmission. Note that this attribute should not be present when specifying recipients inline.

Field Type Description Required Notes
list_id string Identifier of the stored recipient list to use yes Specify this field when using a stored recipient list.

Scheduled Transmissions

Use the options.start_time attribute to delay generation of messages. The scheduled time cannot be greater than 31 days from the time of submission. If the scheduled time does not pass validation, the transmission is not accepted. Transmissions with a scheduled time in the past are accepted and undergo immediate generation.

Create

Create a Transmission

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

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

Example: 3

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.

Note: Sending limits apply to SparkPost accounts only. When a transmission is created, the number of messages in the transmission is compared to the sending limit of your account. If the transmission will cause you to exceed your sending limit, the entire transmission results in an error and no messages are sent. Note that no messages will be sent for the given transmission, regardless of the number of messages that caused you to exceed your sending limit. In this case, the Transmission API will return an HTTP 420 error code with an error detailing whether you would exceed your hourly, daily, or sandbox sending limit.

Using Inline Email Part Content

Create a transmission using inline email part content.

Using Inline RFC822 Content

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

Using a Stored Recipients List

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

Using a Stored Template

Create a transmission using a stored template by specifying the template_id in the content attribute. The use_draft_template field is optional and indicates whether to use a draft version or the published version of the template when generating messages.

Scheduling Transmissions

Create a scheduled transmission to be generated and sent at a future time by specifying start_time in the options attribute.

Scheduling a transmission that specifies a stored template will use the LATEST version of the template available at the time of scheduled generation. The use of published versus draft versions follows the same logic in all transmission requests, whether scheduled or immediate generation. When use_draft_template is not specified (or set to false), the latest published version of the specified stored template is used. If use_draft_template is set to true, the latest draft version is used in the transmission instead.

Once message generation has been initiated, all messages in the transmission will use the template selected 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 selected at the start of the generation.

Examples

Request: Create Transmission using Inline Email Part Content

POST /api/v1/transmissions?num_rcpt_errors=3

{
  "options": {
    "open_tracking": true,
    "click_tracking": true,
    "transactional": false,
    "sandbox": false,
    "ip_pool": "sp_shared",
    "inline_css": false
  },
  "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": [
        "greeting",
        "prehistoric",
        "fred",
        "flintstone"
      ],
      "metadata": {
        "age": "24",
        "place": "Bedrock"
      },
      "substitution_data": {
        "customer_type": "Platinum",
        "year": "Freshman"
      }
    }
  ],
  "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"
    },
    "text": "Hi  \nSave big this Christmas in your area ! \nClick http://www.mysite.com and get huge discount\n Hurry, this offer is only to \n ",
    "html": "<p>Hi  \nSave big this Christmas in your area ! \nClick http://www.mysite.com and get huge discount\n</p><p>Hurry, this offer is only to \n</p><p></p>"
  }
}

Response (HTTP status code: 200)

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

Response (HTTP status code: 400)

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

Request: Create Transmission with Inline RFC822 Content

POST /api/v1/transmissions?num_rcpt_errors=3

{
  "options": {
    "open_tracking": true,
    "click_tracking": true,
    "transactional": false,
    "sandbox": false,
    "ip_pool": "",
    "inline_css": false
  },
  "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": [
        "greeting",
        "prehistoric",
        "fred",
        "flintstone"
      ],
      "metadata": {
        "age": "24",
        "place": "Bedrock"
      },
      "substitution_data": {
        "first_name": "Wilma",
        "customer_type": "Platinum",
        "year": "Freshman"
      }
    },
    {
      "address": {
        "email": "abc@flintstone.com",
        "name": "Fred Flintstone"
      },
      "tags": [
        "greeting",
        "prehistoric",
        "fred",
        "flintstone"
      ],
      "metadata": {
        "age": "33",
        "place": "NY"
      },
      "substitution_data": {
        "first_name": "Fred",
        "customer_type": "Sliver",
        "year": "Senior"
      }
    }
  ],
  "content": {
    "email_rfc822": "Content-Type: text/plain\r\nTo: \"\" <>\r\n\r\n Hi  \nSave big this Christmas in your area ! \nClick http://www.mysite.com and get huge discount\n Hurry, this offer is only to \n \r\n"
  }
}

Response (HTTP status code: 200)

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

Response (HTTP status code: 400)

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

Request: Create Transmission Using CC Header

POST /api/v1/transmissions?num_rcpt_errors=3

{
  "options": {
    "open_tracking": true,
    "click_tracking": true,
    "transactional": false,
    "sandbox": false,
    "ip_pool": "sp_shared",
    "inline_css": false
  },
  "description": "Christmas Campaign Email",
  "campaign_id": "christmas_campaign",
  "recipients": [
    {
      "address": {
        "email": "wilma@flintstone.com"
      }
    },
    {
      "address": {
        "email": "pebbles@flintstone.com",
        "header_to": "wilma@flintstone.com"
      }
    }
  ],
  "content": {
    "from": {
      "name": "Fred Flintstone",
      "email": "fred@flintstone.com"
    },
    "subject": "Big Christmas savings!",
    "reply_to": "Christmas Sales <sales@flintstone.com>",
    "headers": {
      "CC": "pebbles@flintstone.com"
    },
    "text": "Hi, \nSave big this Christmas in your area! \nClick http://www.mysite.com and get huge discount!"
  }
}

Response (HTTP status code: 200)

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

Response (HTTP status code: 400)

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

Request: Create Transmission with Stored Recipient List

POST /api/v1/transmissions?num_rcpt_errors=3

{
  "campaign_id": "christmas_campaign",
  "recipients": {
    "list_id": "christmas_sales_2013"
  },
  "content": {
    "from": {
      "name": "Fred Flintstone",
      "email": "fred@flintstone.com"
    },
    "subject": "Big Christmas savings!",
    "text": "Hi  \nSave big this Christmas in your area ! \nClick http://www.mysite.com and get huge discount\n Hurry, this offer is only to \n ",
    "html": "<p>Hi  \nSave big this Christmas in your area ! \nClick http://www.mysite.com and get huge discount\n</p><p>Hurry, this offer is only to \n</p><p></p>"
  }
}

Response (HTTP status code: 200)

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

Response (HTTP status code: 404)

{
  "errors": [
    {
      "message": "resource not found",
      "description": "List 'christmas_sales_2013' does not exist",
      "code": "1600"
    }
  ]
}

Request: Create Transmission with Stored Template

POST /api/v1/transmissions?num_rcpt_errors=3

{
  "options": {
    "open_tracking": true,
    "click_tracking": true
  },
  "campaign_id": "thanksgiving_campaign",
  "content": {
    "template_id": "christmas_offer",
    "use_draft_template": false
  },
  "metadata": {
    "user_type": "students",
    "age_group": "18-35"
  },
  "substitution_data": {
    "status": "shopping",
    "holiday": "Thanksgiving"
  },
  "recipients": [
    {
      "address": {
        "email": "wilma@flintstone.com",
        "name": "Wilma Flintstone"
      },
      "tags": [
        "greeting",
        "prehistoric",
        "fred",
        "flintstone"
      ],
      "metadata": {
        "age": "24",
        "place": "Bedrock"
      },
      "substitution_data": {
        "first_name": "Wilma",
        "last_name": "Flintstone"
      }
    },
    {
      "address": {
        "email": "abc@flintstone.com"
      },
      "tags": [
        "greeting",
        "prehistoric",
        "fred",
        "flintstone"
      ],
      "metadata": {
        "age": "33",
        "place": "MD"
      }
    }
  ]
}

Response (HTTP status code: 200)

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

Response (HTTP status code: 404)

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

Request: Number of Messages Exceeds Sending Limit

POST /api/v1/transmissions?num_rcpt_errors=3

{
  "campaign_id": "christmas_campaign",
  "recipients": {
    "list_id": "list_exceeds_sending_limit"
  },
  "content": {
    "from": {
      "name": "Fred Flintstone",
      "email": "fred@flintstone.com"
    },
    "subject": "Big Christmas savings!",
    "text": "Hi  \nSave big this Christmas in your area ! \nClick http://www.mysite.com and get huge discount\n Hurry, this offer is only to \n ",
    "html": "<p>Hi  \nSave big this Christmas in your area ! \nClick http://www.mysite.com and get huge discount\n</p><p>Hurry, this offer is only to \n</p><p></p>"
  }
}

Response (HTTP status code: 420)

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

Response (HTTP status code: 420)

{
  "errors": [
    {
      "message": "Exceed Sending Limit (daily)",
      "code": "2102"
    }
  ]
}

Response (HTTP status code: 420)

{
  "errors": [
    {
      "message": "Exceed Sending Limit (sandbox)",
      "code": "2103"
    }
  ]
}

Request: Create Scheduled Transmission

POST /api/v1/transmissions?num_rcpt_errors=3

{
  "name": "Fall Sale",
  "campaign_id": "fall",
  "options": {
    "start_time": "2017-02-11T08:00:00-04:00",
    "open_tracking": true,
    "click_tracking": true
  },
  "recipients": {
    "list_id": "all_subscribers"
  },
  "content": {
    "template_id": "fall_deals"
  }
}

Response (HTTP status code: 200)

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

Request: Create Transmission with attachments

POST /api/v1/transmissions?num_rcpt_errors=3

{
  "campaign_id": "attachment_example",
  "recipients": [
    {
      "address": "wilma@flintstone.com"
    }
  ],
  "content": {
    "from": {
      "email": "billing@company.example",
      "name": "Example Company"
    },
    "subject": "Billing statement",
    "html": "<b>Please see your attached billing statement</b>",
    "attachments": [
      {
        "type": "application/pdf",
        "name": "billing.pdf",
        "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
      },
      {
        "type": "text/plain; charset=UTF-8",
        "name": "explanation.txt",
        "data": "TW92ZSBhbG9uZy4gIE5vdGhpbmcgdG8gc2VlIGhlcmUu"
      }
    ]
  }
}

Response (HTTP status code: 200)

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

Request: Create Transmission with inline images

POST /api/v1/transmissions?num_rcpt_errors=3

{
  "campaign_id": "inline_image_example",
  "recipients": [
    {
      "address": "wilma@flintstone.com"
    }
  ],
  "content": {
    "from": {
      "email": "marketing@company.example",
      "name": "Example Company"
    },
    "subject": "Inline image example",
    "html": "<html><body>Here is your inline image!<br> <img src=\"cid:my_image.jpeg\"></body></html>",
    "inline_images": [
      {
        "type": "image/jpeg",
        "name": "my_image.jpeg",
        "data": "VGhpcyBkb2Vzbid0IGxvb2sgbGlrZSBhIGpwZWcgdG8gbWUh"
      }
    ]
  }
}

Response (HTTP status code: 200)

{
  "results": {
    "total_rejected_recipients": 0,
    "total_accepted_recipients": 1,
    "id": "11668787484950529"
  }
}
Note: The following request is valid for SparkPost Enterprise accounts only.

Request: Create Transmission for Mobile Push Using Inline Content

POST /api/v1/transmissions?num_rcpt_errors=3

{
  "recipients": [
    {
      "multichannel_addresses": [
        {
          "channel": "apns",
          "token": "02c7830aae68d008a0616aed81a6bec40b5acf53fbca1ae46c734527ee0e885f",
          "app_id": "flintstone.apns.domain"
        }
      ]
    },
    {
      "multichannel_addresses": [
        {
          "channel": "gcm",
          "token": "kNd8dnekej:KDSNDdnedik3n3kFDJfjwJDKndkd39MNiKnd9-Dk4NbkwnyMisosowb_GixnesleE38c1nglc9dTIXL56Djdhsn90nZjkDleEixlndiHk_Sntks54g1sZdnssY2s15f_SnektTkjwse",
          "app_id": "flintstone.gcm.domain"
        }
      ]
    }
  ],
  "content": {
    "push": {
      "apns": {
        "aps": {
          "alert": {
            "title": "Badge adjust alert message",
            "body": "Hello John. I am resetting your badge to zero"
          },
          "badge": 0
        }
      },
      "gcm": {
        "notification": {
          "title": "You have Android deals",
          "body": "Open your Android app to check out these awesome new deals",
          "color": "#fa6423",
          "icon": "myicon"
        }
      }
    }
  }
}

Response (HTTP status code: 200)

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

Retrieve and Delete

Retrieve a Scheduled Transmission

GET/api/v1/transmissions/{id}
URI Parameters
id(required)  

ID of the transmission

Example: 11714265276872

Retrieve the details about a scheduled transmission by specifying its ID in the URI path.

The response for a transmission using an inline template will include "template_id":"inline". Inline templates cannot be specifically queried.

Note: Only multi-recipient transmissions that have been submitted or completed within the last 24 hours are returned.
Note: Only scheduled transmissions are returned by this endpoint. Immediate transmissions cannot be retrieved.

Examples

Request

GET /api/v1/transmissions/11714265276872

Response (HTTP status code: 200)

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

Response (HTTP status code: 404)

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

Delete a Transmission

DELETE/api/v1/transmissions/{id}
URI Parameters
id(required)  

ID of the transmission

Example: 11714265276872

Delete a transmission by specifying its ID in the URI path.

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

Scheduled transmissions cannot be deleted if the transmission is within 10 minutes of the scheduled generation time.

Examples

Request

DELETE /api/v1/transmissions/11714265276872

Response (HTTP status code: 204)

Empty response body

Response (HTTP status code: 404)

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

Response (HTTP status code: 409)

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

Response (HTTP status code: 409)

{
  "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)"
    }
  ]
}

Response (HTTP status code: 409)

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

 Delete Transmissions By Campaign

Note: SparkPost Enterprise only, account-specific configuration option.

Delete all transmissions of a campaign by specifying Campaign ID in the URI path.

Delete By Campaign ID

DELETE/api/v1/transmissions?campaign_id={campaign_id}
URI Parameters
campaign_id(required)  Example: white-christmas

Examples

Request: Delete all transmissions for a campaign

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

Response (HTTP status code: 204)

Empty response body

List

List All Scheduled Transmissions

GET/api/v1/transmissions{?campaign_id,template_id}
URI Parameters
campaign_id

ID of the campaign used by the transmissions

Example: thanksgiving
template_id

ID of the template used by the transmissions

Example: thanksgiving-template

List an array of live transmission summary objects. A transmission summary object contains id, state, template_id, campaign_id and description fields.

By default, the list includes transmissions for all campaigns and templates. Use the template_id parameter to filter by template and campaign_id to filter by campaign. The summary for transmissions using an inline template will include "template_id": "inline". Transmissions using inline templates cannot be filtered with template_id.

Note: Only multi-recipient transmissions that have been submitted or completed within the last 24 hours are returned.
Note: Only scheduled transmissions are returned by this endpoint. Immediate transmissions cannot be retrieved.

Examples

Request

GET /api/v1/transmissions?campaign_id=thanksgiving&template_id=thanksgiving-template

Response (HTTP status code: 200)

{
  "results": [
    {
      "content": {
        "template_id": "winter_sale"
      },
      "id": "11713562166689858",
      "campaign_id": "thanksgiving",
      "description": "",
      "state": "submitted"
    },
    {
      "content": {
        "template_id": "inline"
      },
      "id": "11713562166689979",
      "campaign_id": "thanksgiving",
      "description": "",
      "state": "submitted"
    },
    {
      "content": {
        "template_id": "thanksgiving-template"
      },
      "id": "11713048079237202",
      "campaign_id": "thanksgiving",
      "description": "",
      "state": "submitted"
    }
  ]
}