PHP5 Library
Contents
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
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 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.
- 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
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
- 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
- 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
- Options:
- start_date
- end-date
- status
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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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)
- id: string id representing the id value
- key: string representing key type for id
- fields: array representing what fields to return.
- 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.
- blast_id: string of the Blast ID you wish to preview
- email: string of the email address for whom the blast should preview
- 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.
- template: string of the template name
- send_email: string of the email address you'd like to send the template to.
- 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
- event: string name of event you'd like to query triggers for.
- trigger_id: string representing the ID of the trigger to look up.
- 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
- 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.
- 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