send

The send call is intended for sending triggered messages using a specified template to a specified user. You can also retrieve information on a sent or scheduled transactional.

For campaign (mass-message) sending, you should exclusively use the blast API instead, or the blast_repeat API for recurring campaigns. This will ensure proper deliverability and efficiency, and enable campaign-specific features. Note that triggered sends can also be sent as a result of Purchase API calls (for example, purchase receipts or abandoned cart reminders) or via triggers that are set in response to user actions on previous triggered sends. 

Endpoint URL: https://api.sailthru.com/send

GET Triggered Send

Retrieve all information about a specific triggered send.

Get by send_id

Example Call:
{
  "send_id" : "WBo2fryq0sw9qI93"
}

Response

Example Response:
{   
  "status" : "delivered",
  "send_key" : null,
  "view_url" : "http://cb.sailthru.com/view/WBokwLyq0jgtqI94/2404d754",
  "text_url" : "http://cb.sailthru.com/textview/WBokwLyq0jgtqI94/8a8d8e60",
  "send_id" : "WBokwLyq0jgtqI94",
  "template" : "Confirmed Opt-In",
  "send_time" : "Wed, 02 Nov 2016 13:39:12 -0400",
  "email" : "user@example.com"
}

Required Parameters

Parameter Description Example
send_id The unique identifier of the send TE8EZ3-LmosnAgAA

Response Parameters

Field Description Example
send_id The unique identifier of the send TE8EZ3-LmosnAgAA
email The destination email address example@example.com
template The name of the template used in the send test-template
status The delivery status of the send - either unknownscheduledsoftbouncehardbounce, or delivered delivered
data_feed_url Data feed used in the campaign https://blog.sailthru.com/
send_time The time the message was sent. Present only if the message was sent. Tue, 27 Jul 2010 12:12:21 -0400
schedule_time The time the message was scheduled. Present only if the message was scheduled in advance. Tue, 27 Jul 2010 12:10:00 -0400
open_time The time the message was opened with images turned on. Present only if it was actually opened. Tue, 27 Jul 2010 13:15:59 -0400
click_time The time the message was clicked. Present only if it was actually clicked. Tue, 27 Jul 2010 13:16:17 -0400
To export a CSV of all triggered sends scheduled for the future, please see the API job call's "export_scheduled_sends". To export a CSV of all sent triggered emails, please visit the Triggered Sends Log in the user interface.

POST to Send, Schedule or Update

Send a triggered email, schedule one for the near future, or update the parameters of a scheduled triggered email.

Basic Send

Example Call (with minimum parameters, email address and template):
{
  "template" : "Product Alert",
  "email" : "user@example.com"
}
Example Response:
{
  "email" : "user@example.com",
  "send_id" : "WGrLf25K3Fwzi4ry",
  "template" : "Product Alert",
  "status" : "unknown",
  "send_key" : null
}

Advanced Send

Example Call:
{
  "template" : "Product Alert",
  "email" : "doug@example.com",
  "options":{"headers":{"Cc":"bob@example.com"}},
  "schedule_time" : "2017-01-01 00:00:00",
  "vars": {"FirstName":"Douglas","LastName":"Crockford"},
  "data_feed_url" : "https://feed.sailthru.com/ws/feed?id=908ec3891aa312f74f8b4573"
}
Example Response:
{
  "email" : "user@example.com",
  "send_id" : "WGrLf25K3Fwzi4ry",
  "template" : "Product Alert",
  "status" : "scheduled",
  "schedule_time" : "Sun, 01 Jan 2017 00:00:00 -0500",
  "send_key" : null
}

SMS Send

Send a transactional SMS using the same POST method as you use for a transactional email send. If the profile related to the email address has an SMS number as a profile key, the message should send the same way as a regular transactional message. 
{
"template":"SMS_Test",
"email":"example@sailthru.com"
}
Note: Create an SMS template after there is an SMS number assigned to your client account. That way the from_sms field will pull in the SMS number properly.

Required Parameters

Parameter Description Example
template the name of the template to send my-template
email the email address to send to example@example.com

Optional Parameters

Parameter Description Example
schedule_time To send the email at some point in the future, otherwise it will send immediately. Any date recognized by PHP's strtotime function is valid, but be sure to specify timezone or use a UTC time to avoid confusion. You may also use a relative time, for example, 'tomorrow 09:30 UTC'. "2013-09-08 20:00:00" or "now"
vars a key/value hash of var names and their values to use in the send. Each var may be referenced as {varname} within the template itself. {"varname":"value","name":"Joe Smith"}
options[headers[Cc]] include an email address on copy. Cc must be capitalized. If including multiple addresses, separate them with commas. "options":{"headers":{"Cc":"robert@example.com,alicia@example.com"}}
options[headers[Bcc]] include an email address on blind copy. Bcc must be capitalized. Note that BCC should be used carefully as some email domains guard against it in spam filters. If including multiple addresses, separate them with commas. "options":{"headers":{"Bcc":"bob@example.com,alice@example.com"}}
options[replyto] customize the Reply-To header "options":{"replyto":"mynewreplyto@example.com"}
options[test] set to 1 to denote the email as a test 1
data_feed_url Data feed used in the campaign https://blog.sailthru.com/
options[behalf_email] Use the Sender/From headers to send the email on behalf of a third party. Note that this should be used sparingly as it will impact deliverability. Headers will show: From: MyBehalfName <my-behalf-email@example.com>, Sender: myfromemail@example.com user@example.com

Response Parameters

Will be identical to the return value of GET mode. This includes the send_id which you can use to reference the message later. Because the email has just sent, the status of a send will always be unknown at the moment it has sent. This is expected behavior. If you do a GET call a little later, you can retrieve the delivery status.

Update Scheduled Send

By logging the send_id of a scheduled send, you can later update that send by submitting a new POST mode call using the send_id parameter. You can additionally submit email, vars, and template to update existing parameters. Parameters not resubmitted will remain as originally submitted.

Send to Multiple Recipients

You can send the same template to multiple email addresses at once (up to 5 per API call). If you are doing this on a large scale, you may want to consider sending it as a campaign instead, using the blast API. Simply use multiple, comma-separated email addresses as the email parameter value. You may also include the following parameter if you wish to include unique var values per recipient:
Parameter Description Example
evars Key-value hash where each key is an email address, and each value is a key/value hash of variables for that particular email address evars[example@example.com][myvar]=value
For example:
{
  "template" : "Example Template Name",
  "email" : "user1@example.com,user2@example.com,user3@example.com",
  "evars": {
    "user1@example.com": {
      "greeting" : "Hello", "signoff" : "Bye!"
    },
    "user2@example.com": {
      "greeting" : "Bonjour", "signoff" : "Ciao"
    },
    "user3@example.com": {
      "greeting" : "Greetings!", "signoff" : "Ta-ra!"
    }
  }
}
The return value will be slightly different for a multi-send and will return:
Field Description Example
template The name of the template Example Template Name
sent_count The number of messages that were sent. If a message is sent to the same address more than once, only one send will be recorded in the send_count. 4
send_ids The unique identifiers for each message
["user1@sailthru.com" : "WFw4hukyi7E8i060",
"user2@sailthru.com" : "WFw4hukyi7E8i061",
"user3@sailthru.com" : "WFw4hukyi7E8i062"]
Note: Combining schedule_time with a multi-user send is not supported.

A/B Test Sends

For templates that have A/B test versions, upon each send to the template, the system will pick randomly between the different A/B versions. After a period of time, you will be able to compare the results and determine which is the most effective template.

Note: A user's placement in the A or B grouping will persist for all future triggered test sends.

DELETE a scheduled send

Delete Send

Example Call:
{
  "send_id" : "WGrLf25K3Fwzi4ry"
}
Example Response:
{
  "send_id" : "WGrLf25K3Fwzi4ry"
  "ok" : true,
  "send_key" : null
}
Cancels an email that you had previously scheduled for future sending with the schedule_time parameter. It is not possible to cancel an email that was sent immediately, without a future schedule.

Required Parameters

Parameter Description Example
send_id The unique identifier of the send TE8EZ3LmosnAgAA

Response Parameters

Field Description Example
send_id The unique identifier of the send TE8EZ3LmosnAgAA
ok true or 1 true
 

Error Codes

GET

HTTP Status Code Error Code Error Message
400 99 Invalid value for parameter limit_name provided
404 99 Unable to load profile
404 99 Unable to find a message with limit {limit_name} for {email}
404 12 Unknown send_id: {id}
400 2 Missing required parameter: {param}
400 2 Invalid parameter type: {param}

POST

HTTP Status Code Error Code Error Message Notes
400 2 Missing required parameter: key or email
400 99 A send_key must be a string
404 99 Invalid send_key {key} sid,profile_id,device_id
400 2 Missing required parameter: id
400 99 The device_id cannot be more than 200 characters
400 99 The device_id cannot contain special characters {device_id}
400 99 The sid must be a string
400 99 Invalid sid: {profile_id}
404 99 The side {profile_id} does not match any known profile
404 14 Unknown template: {template}
404 14 {template} is not an active template
404 99 Unknown template: {template} {revision_id}
404 99 Unknown template: {template} and/or revision ID: {revision_id}
404 14 Unknown template: " {template}
400 99 Missing required parameter app_id
401 22 You must be approved; email support@sailthru.com
401 21 You must be an approved client to email {email{}
400 99 Invalid value for parameter limit[name] provided
400 99 Invalid value for parameter limit[within_time] provided, must be a relative, negative time
400 18 Invalid time: {time}
200 18 Invalid start_time
200 18 Invalid end_time
400 18 Invalid time, end_time must be greater than start_time
400 18 Invalid time, end_time must be within 24 hours of start_time.
400 18 Invalid time, method must be on of the following: {method} Email, site, mobile
404 99 No profile with {send_key} {id}
200 11 Invalid email
404 12 Unknown client_id {client_id}
403 41 Unable to edit, already sent
404 14 Unknown template: {template}
200 99 Unable to set send limit successfully, this message with not send
400 99 Replacement vars size too large The json representation of the vars hash table must be no larger than 1000000 characters.
403 99 You may not email more than 200 emails at once
400 99 Invalid JSON provided
 

DELETE

HTTP Status Code Error Code Error Message
403 41 Unable to cancel, already sent
400 99 Invalid value for parameter limit_name provided
404 99 Unable to load profile
404 99 Unable to find a message with limit {limit_name} for {email}
404 12 Unknown send_id: {id}
400 2 Missing required parameter: {param}
400 2 Invalid parameter type: {param}

Contact us

Top