send

Overview

Send a transactional email, check on the status of a send, or cancel a future send before it goes out.

See also Transactional Overview. Please also see Abandoned Shopping Carts (for use with the purchase api call).

Base URL

https://api.sailthru.com/send

GET Mode

Get information on a transactional email

Required Parameters
Parameter Description Example
send_id The unique identifier of the send TE8EZ3-LmosnAgAA
Client Invocation
getSend(send_id)
Return Value
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 unknown, scheduled, softbounce, hardbounce, or delivered delivered
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 transactionals scheduled for the future, please see the api JOB call's "export_scheduled_sends". Alternately, to export a CSV of all sent transactionals, please visit the Transactional Log in the user interface. 

POST Mode

Send a transactional email, or schedule one for the near future

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 relative time; see Examples below. "2013-09-08 20:00:00" or "now"
schedule_time['start_time'] Set a start_time when using Personalized Send Time. 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 relative time; see Examples below. "2013-09-08 20:00:00" or "now"
schedule_time['end_time'] Set an end_time when using Personalized Send Time. 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 relative time; see Examples below. "2013-09-08 20:00:00" or "now"
vars a key/value hash of the replacement vars 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. "options":{"headers":{"Cc":"joe@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. "options":{"headers":{"Bcc":"joe@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
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
limit["name"] Specify an arbitrary name that this limit will be tied to.  When another send is attempted with the same limit name AND template, it will either prevent the old send that was scheduled, or the new send (see limit["conflict"]) welcome
limit["within_time"] Specify a time frame for the limit +30 days
limit["conflict"] Tell Sailthru how to handle a conflict (update the old send with the new values or fail the new attempted send), either "update" or "fail" update
Client Invocation
send(template, email[, vars, options, schedule_time])
Return Value

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, template and schedule_time to update existing parameters. Parameters not resubmitted will remain as originally submitted.

Multiple Send

You are allowed to send the same template to multiple email addresses at once (up to 100 per API call). If you are doing this on a large scale, you may want to consider sending it as a mass mail campaign instead.

To multi-send, simply comma-separate the email addresses you wish to multiple-send to. You may also use the following optional parameters:

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

The return value will be slightly different for a multi-send and will return:

Field Description Example
template The name of the template my-template
sent_count The number of messages that were sent  
send_ids An array of the unique identifiers for each message ["TE8EZ3-LmosnAgAA","TE8EZ3-LmosnAgAB"]

Combining schedule_time with multiple send is not currently supported.

 

DELETE Mode

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 has not been scheduled.

Required Parameters
Parameter Description Example
send_id The unique identifier of the send TE8EZ3-LmosnAgAA
Client Invocation
cancelSend(send_id)
Return Value
Field Description Example
send_id The unique identifier of the send TE8EZ3-LmosnAgAA
ok true or 1 1

Examples

GET: Get the status of an in-progress or pending transactional email.

$sailthru_client->getSend('TE8EZ3-LmosnAgAA');

POST: Send a transactional email to a user, tomorrow morning, supplying the user's name and gender to customize the email content.

$sailthru_client->send('my-nextmorning-template','example@example.com',array('name' => 'Joe Schmoe', 'gender' => 'M'),'tomorrow 09:30 UTC');

POST: for an event that happens on Sept 14, you can automatically send a reminder two days before that by using the schedule_timeparameter with a relative time value.

In JSON:

{"template":"2 days until event reminder","email":"support@sailthru.com","schedule_time":"Saturday, September 14, 2012 9:00pm EST -2 days"}

DELETE: Delete an in-progress or pending transactional email.

$sailthru_client->cancelSend('TE8EZ3-LmosnAgAA');