PHP5 Library

Installation

Composer

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

composer require sailthru/sailthru-php5-client

GitHub

Basic Usage

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])

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

$client->apiDelete(string $action, array $data, [array $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

• 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

• 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

• 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

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

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

• 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