PHP5 Library
Contents
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 endpointmethod
: 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