PHP5 Library

A client library for accessing the Sailthru REST API.

Installation

Composer

If using composer, you can install the library from CLI:

composer require sailthru/sailthru-php5-client

GitHub

For other installations, the library can be found on github.

Basic Usage

NOTE: For scheduling actions, dates in the past will be scheduled for immediate delivery. Any English textual datetime format known to PHP’s strtotime function is acceptable, such as 2009-03-18 23:57:22 UTC, now (immediate delivery), +3 hours (3 hours from now), or February 14, 9:30 EST. Be sure to specify a timezone if you use an exact time.

Constructor

$apiKey = '<apiKey>';
$apiSecret = '<secret>';
$sailthruClient = new Sailthru_Client($api_key, $api_secret);

API Requests

You can also access the APIs directly via GET, POST, and DELETE. All requests return an array representation of the JSON response.

$client->apiGet(string $action, [array $data, string $method, array $options])

string $action	The API endpoint to hit (user, lists, job, etc.)
array $data	Arguments to pass to endpoint as defined in API Docs
string $method	Overridable HTTP method
array $options	Array of request options

$client->apiPost(string $action, array $data, [array $binary_data_param, array $options])

string $action	The API endpoint to hit (user, lists, job, etc.)
array $data	Arguments to pass to endpoint as defined in API Docs
array $binary_data_param	Flag for sending binary data
array $options	array of request options

$client->apiDelete(string $action, array $data, [array $options])

string $action	The API endpoint to hit (user, lists, job, etc.)
array $data	Arguments to pass to endpoint as defined in API Docs
array $options	array of request options

Example Call

try {
        $response = $sailthruClient->apiGet('user', ['id'=>'docs@sailthru.com']);
        if ( !isset($response['error']) ) {
                // everything OK
                // do something here
        } else {
                // handle API error
        }
} catch (Sailthru_Client_Exception $e) {
        // deal with exceptions
}

Helpers

Headers / Configuration

int getConnectTimeout()

Get client setting for connection timeout.

int getTimeout()

Get client setting for timeout.

bool setHttpHeaders(array $headers)

Add headers for Sailthru Client to use.

headers: array of headers to add to client calls

array|null getLastResponseInfo()

array|null getLastRateLimitInfo($action, $method)

Get rate limit information for last API call

action: API endpoint
method: Http method, GET, POST or DELETE

Send (for Transactionals)

send(string $template, string $email, [array $vars, array $options, string $schedule_time])

Remotely send a transactional to a single email address.

template: a string representing a pre-existing Sailthru template
emails: comma-delimited string of email addresses where to send the transactional
vars : array of key/value vars to be used in the template
options: optional dictionary to include replyto and/or test keys
schedule_time : do not send the email immediately, but at some point in the future.

multisend(string $template_name, string $emails, [array $vars, array $evars, array $options])

Remotely send a transactional to multiple email addresses.

template: a string representing a pre-existing Sailthru template
emails: comma-delimited string of email addresses where to send the transactional
vars : array of key/value vars to be used in the template
evars: vars to be set by specific email address
options: optional dictionary to include replyto and/or test keys

getSend(string $send_id)

Get info on a send based on its ID.

cancelSend(string $send_id)

Cancel the delivery of a send based on its ID.

Blasts (for Campaigns)

scheduleBlast(string $name, string $list, string $schedule_time, string $from_name, string $from_email, string $subject, string $content_html, string $content_text, [array $options])

Schedule a mass email blast

name: string name to give to this new blast
list: the name of the Sailthru list to whose users the blast will be sent to.
schedule_time: when the blast should send.
from_name: name appearing for the “from” email address
from_email: Sailthru-verified email address to use as the “from” email address
subject: subject line of the email
content_html: HTML format version of the email
content_text: Text format version of the email
options: optional parameters dictionary

scheduleBlastFromTemplate(string $template, string $list, string $schedule_time, [array $options])

Schedule a mass email blast by template

template: the Sailthru template to be used
list: the name of the Sailthru list to whose users the blast will be sent to.
schedule_time: when the blast should send.
options: optional parameters dictionary

scheduleBlastFromBlast(string $blast_id, string $schedule_time, [array $options])

Schedule a mass mail blast from a previous blast

blast_id: string ID of the prior blast the new blast will be based on.
schedule_time: when the blast should send.
options: optional parameters dictionary

updateBlast(string $blast_id, [string $name, string $list, string $schedule_time, string $from_name, string $from_email, string $subject, string $content_html, string $content_text, array $options)

Update an already-created blast

blast_id: string ID for the blast to update
name: (optional) string name to give to this new blast
list: (optional) the name of the Sailthru list to whose users the blast will be sent to.
schedule_time: (optional) when the blast should send.
from_name: (optional) name appearing for the “from” email address
from_email: (optional) Sailthru-verified email address to use as the “from” email address
subject: (optional) subject line of the email
content_html: (optional) HTML format version of the email
content_text: (optional) Text format version of the email
options: (optional) optional parameters dictionary

getBlast(string $blast_id)

Get the status of a blast by its ID.

getBlasts(array $options)

Get all blasts by options criteria.

Options:
- start_date
- end-date
- status

deleteBlast(string $blast_id)

Delete a blast by its ID.

cancelBlast(string $blast_id)

Cancel a blast by its ID.

Templates

getTemplate(string $template_name, [array $options])

Get a Sailthru template by name, with additional options available.

getTemplates()

Get all Sailthru templates

getTemplateFromRevision(string $revision_id)

Get template by revision id

saveTemplate(string $template_name, [array $template_fields])

Update template by Sailthru template name, and updated fields.

saveTemplateFromRevision(string $template_name, string $revision_id)

Update template by Sailthru template name and revision id

deleteTemplate(string $template_name)

Delete a Sailthru template by name

Includes (Reusable Template Components)

getInclude(string $include_name, [array $options])

Get an include by name, with additional parameters.

getIncludes()

Get all includes.

saveInclude(string $include_name, [array $include_fields])

Save an include by it’s name and an array of fields to update for the include.

Lists

getList(string $list)

Get list information by Sailthru list name.

getLists()

Get information on all Sailthru lists

saveList(string $list, [string $type, bool $primary = null, array $query])

Save list by list name, with additional parameters to update.

deleteList($list)

Delete list by name

Content

pushContent($title, $url, $date = null, $tags = null, $vars = [ ], $options = [ ])

Push a new piece of content to Sailthru.

title: title string for the content
url: URL string for the content
date: date string
tags: list or comma separated string values
vars: replaceable vars dictionary
options: array of optional parameters

Purchases

purchase(string $email, array $items, [bool $incomplete, string $message_id, array $options])

Push that a user has made a purchase, or has added items to their purchase total.

email: Email string
items: array of items with keys: id, title, price, qty, and url
incomplete: optional param setting this to be abandoned cart
message_id: message_id string
options: other options that can be set as per the API documentation

purchaseIncomplete(string $email, [array $items, string $message_id, array $options])

Push that a user has added items to their purchase total.

email: Email string
items: array of items with keys: id, title, price, qty, and url NOTE: Can be empty to cancel cart
message_id: message_id string
options: other options that can be set as per the API documentation

Stats

stats_list([string $list, string $date)

Retrieve information about your subscriber counts on a particular list, on a particular day.

stats_blast([string $blast_id, string $start_date, string $end_date, array $data)

Retrieve aggregated information about a particular blast or optionally querying over a specified date range or by other parameters in the data array.

stats_send([string $template, string $start_date, string $end_date, array $data])

Retrieve aggregated information about a particular template optionally querying over a specified date range or by other parameters in the data array.

stats(array $data)

Make a Stats API call based on the data parameters passed.

Verification

If you’ve setup postbacks, these functions can be used to verify a received postback’s validity.

receiveVerifyPost()

Validates a user signup verification postback.

receiveOptoutPost()

Validates a user optout postback.

receiveUpdatePost()

DEPRECATED

receiveHardBouncePost()

Validates an email hardbounce postback

Jobs

getJobStatus(string $job_id)

Fetch the status of a job.

job_id (required): the job ID which was returned from a previous job POST

processImportJob(string $list, string $emails, [bool|String $report_email, bool|String $postback_url, array $options])

Start a user import job

list: string Sailthru list to import emails into.
emails: comma-delimited string of emails to add to list.
report_email: optional String (or false) to set where to send a report email
postback_url: optional String (or false) to set whether there’s a postback URL.
options: array of optional parameters that can be set as per the API documentation

processImportJobFromFile(string $list, string $file_path, [bool $report_email, bool $postback_url, array $options)

Start a user import job from CSV file

list: string Sailthru list to import emails into.
file_path: string non-relative URL to file
report_email: optional String (or false) to set where to send a report email
postback_url: optional String (or false) to set whether there’s a postback URL.
options: array of optional parameters that can be set as per the API documentation

processPurchaseImportJobFromFile(string $file_path, [String|bool $report_email, String|bool $postback_url, array $options])

Start a purchase import job from file.

file_path: string non-relative URL to file containing purchase data
report_email: optional String (or false) to set where to send a report email
postback_url: optional String (or false) to set whether there’s a postback URL.
options: array of optional parameters that can be set as per the API documentation

processSnapshotJob(array $query, [String|bool $report_email, String|bool $postback_url, array $options)

Start a snapshot job.

query: array representing query parameters for snapshot
report_email: optional String (or false) to set where to send a report email
postback_url: optional String (or false) to set whether there’s a postback URL.
options: array of optional parameters that can be set as per the API documentation

processExportListJob(string $list, [string|bool $report_email, bool $postback_url, array $options])

Start a list export job

list: string of the Sailthru list name you want to export.
report_email: optional String (or false) to set where to send a report email
postback_url: optional String (or false) to set whether there’s a postback URL.
options: array of optional parameters that can be set as per the API documentation

processBlastQueryJob(string $blast_id, [string|bool $report_email, string|bool $postback_url, array $options])

Start a Blast query job to receive campaign data

blast_id: string ID for the blast you’d like to query
report_email: optional String (or false) to set where to send a report email
postback_url: optional String (or false) to set whether there’s a postback URL.
options: array of optional parameters that can be set as per the API documentation

processUpdateJobFromUrl(string $url, [array $update, string|bool $report_email, string|bool $postback_url, array $options])

Start an Update job for user profiles from a specified URL.

url: string for absolute URL to file
update: array representing updates to make
report_email: optional String (or false) to set where to send a report email
postback_url: optional String (or false) to set whether there’s a postback URL.
options: array of optional parameters that can be set as per the API documentation

processUpdateJobFromFile(string $file, [array $update, string|bool $report_email, string|bool $postback_url, array $options])

Start an Update job for user profiles from a file

processUpdateJobFromQuery(array $query, [array $update, string|bool $report_email, string|bool $postback_url, array $options])

Start an Update job from a query array.

query: array of properties to query users from Sailthru
update: array representing updates to make
report_email: optional String (or false) to set where to send a report email
postback_url: optional String (or false) to set whether there’s a postback URL.
options: array of optional parameters that can be set as per the API documentation

processUpdateJobFromEmails(string $emails, [array $update, string|bool $report_email, string|bool $postback_url, array $options])

Start a Update job for user profiles based on a set of emails.

emails: string of comma-delimited email addresses
update: array representing updates to make
report_email: optional String (or false) to set where to send a report email
postback_url: optional String (or false) to set whether there’s a postback URL.
options: array of optional parameters that can be set as per the API documentation

Users

saveUser(string $id, [array $options])

Push or save a user a user by an id, usually email or Sailthru ID.

id: string email, sailthru id, or external key
options: array of parameters to update (see User API reference)

getUserBySid(string $id)

Get user details by Sailthru ID

getUserByKey(string $id, string $key, [array $fields])

Get user details by key, optionally querying only specific fields.

id: string id representing the id value
key: string representing key type for id
fields: array representing what fields to return.

setHorizonCookie(string $email, string $domain, int $duration, bool $secure)

Helper to set Sailthru HID cookie for users.

email: string representing their email
domain: string representing the domain the cookie should go on. Defaults to current domain.
duration: int representing time in seconds
secure: boolean that, if true, will only drop the cookie on an HTTPS connection

Preview (for Templates)

previewTemplateWithHTML(string $template, string $email)

Get the HTML preview of a template for a given email address.

template: string of the Sailthru template name
email: string of the email address the template is to be rendered for.

previewBlastWithHTML(string $blast_id, string $email)

Preview the HTML for a blast for a given email address

blast_id: string of the Blast ID you wish to preview
email: string of the email address for whom the blast should preview

previewRecurringBlastWithHTML(string $blast_repeat_id, string $email)

Preview the HTML for a repeating blast for a given email address

blast_repeat_id: string of the repeat Blast ID you wish to preview
email: string of the email address for whom the blast should preview

previewContentWithHTML(string $content_html, string $email)

Render the given HTML as a Sailthru template for the given email address

content_html: string representing HTML to be parsed and rendered by Sailthru
email: string of the email address for whom the content_html should preview.

previewTemplateWithEmail(string $template, string $send_email)

Send a preview email for a template to a specific email address

template: string of the Sailthru template name
send_email: string of the email address you’d like to send the template to.

previewBlastWithEmail(string $blast_id, string $send_email)

Send a preview email for Blast to a specific email address

blast_id: string of the blast ID you’d like to send
send_email: the email address you’re like to send the blast preview to.

previewRecurringBlastWithEmail(string $blast_repeat_id, string $send_email)

Send a preview email for a repeating blast to a specific email address

Blast_repeat_id: string representing the ID for the repeating Blast
send_email: the email address you’d like to send the repeat blast preview to.

previewContentWithEmail(string $content_html, string $send_email)

Send a preview email of given html to a specific email address

content_html: string of HTML to be parsed and rendered for preview by Sailthru
send_email: string of the email address the content html preview should be sent to.

Triggers and Events

getTriggers()

Get an array of all Triggers.

getTriggerByTemplate(string $template, [string $trigger_id])

Get all triggers for a given template

template: string name of template you wish to query triggers by
trigger_id: string (optional) id of trigger you wish to look up

getTriggerByEvent(string $event)

Query triggers by event

event: string name of event you’d like to query triggers for.

getTriggerById(string $trigger_id)

Get a trigger by ID.

trigger_id: string representing the ID of the trigger to look up.

postTrigger(string $template, int $time, string $time_unit, string $event, string $zephyr)

Create a template-based trigger.

template: string template name
time: int representing amount of time
time_unit: string representing units used for time
event: string name of event that will execute the trigger
zephyr: the zephyr for the trigger to execute

postEventTrigger(string $event, int $time, string $time_unit, string $zephyr)

Create a trigger by event.

event: string name of event that will execute the trigger
time: int representing amount of delay before trigger execution
time_unit: string name of units for time delay
zephyr: string representing zephyr to be executed by Trigger.

postEvent(string $id, string $event, [array $options])

Post a custom event to Sailthru.

id: sailthru id of user (can be a different key if using options array, similar to User API)
event: string name of custom event
Options: array (optional) for additional parameters