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

Contact us

Top