PHP5 Library

A client library for accessing the 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 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 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 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: 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 template to be used
list: the name of the 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 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) 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 template by name, with additional options available.
getTemplates() Get all templates
getTemplateFromRevision(string $revision_id) Get template by revision id
saveTemplate(string $template_name, [array $template_fields]) Update template by template name, and updated fields.
saveTemplateFromRevision(string $template_name, string $revision_id) Update template by template name and revision id
deleteTemplate(string $template_name) Delete a 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 list name.
getLists() Get information on all 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.

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 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 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
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 ID.

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

getUserBySid(string $id) Get user details by 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 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 template for the given email address

content_html: string representing HTML to be parsed and rendered by the system
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 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
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.

id: 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