A client library to remotely access the REST APIs in perl. There are several helper functions for frequently used services, like send, blast, email, and template. There are also low-level API calls (GET, POST and DELETE) to access all available API endpoints. Additionally, API throttling can be done using the provided rate limiting helper function. You can download the library on GitHub.
Authentication Authentication is done using your account's provided API key and secret. For example:
$sailthru = Sailthru::Client->new( $API_KEY, $API_SEC );
Send API Helper Functions
send(template, email, vars, options, schedule_time)
Description: Send a single message to "email", using the given "template" and "vars" API: send (POST) Parameters:
- template (required): name of the template to use as the basis for the message content
- email (required): valid email address to send the message to
-
vars (optional): a hash reference of custom vars to be used in template evaluation
-
options (optional): a hash reference that can be used to specify any other valid API parameters for the send POST, the full list is available here
-
schedule_time (optional): a time string the message will be sent at
Examples: send "Abandoned Cart Reminder" template to "example@example.com", using custom send vars, for a time in the future.
$template = 'Abandoned Cart Reminder';
$email = 'example@example.com';
$vars = { 'foo' => 'bar' };
$options = { 'behalf_email' => 'behalf@example.com' };
$schedule_time = 'tomorrow 9:30am EDT';
$sailthru->send($template, $email, $vars, $options, $schedule_time);
get_send(send_id)
Description: Looks up the delivery status of a particular send, by its "send_id". API: send (GET) Parameters:
- send_id (required): the send ID which was in the response of a previous send call
Examples: Look up a send by send_id
$send = $sailthru->get_send('V-WWJIO6iCcAi0Vo');
Email API Helper Functions
set_email(email, vars, lists, templates)
Description: Update the profile identified by "email", on "vars", "lists" or "templates" API: email (POST) Parameters:
- email (required): valid email address to identify the profile
- vars (optional): a hash reference of vars to set or remove
- lists (optional): a hash reference of lists to subscribe or unsubscribe
- templates (optional): a hash reference of templates to opt-in or opt-out
Examples: set var "foo", subscribe list "daily" and opt in template "daily message" for user with email "example@example.com"
$sailthru->set_email(
"example@example.com",
{ "foo" => "bar" },
{ "daily" => 1 },
{ "daily message" => 1 }
);
remove var "foo", unsubscribe list "daily" and opt out template "daily message" for user with email "example@example.com"
$sailthru->set_email(
"example@example.com",
{ "foo" => "" },
{ "daily" => 0 },
{ "daily message" => 0 }
);
get_email(email)
Description: Looks up a profile by "email". API: email (GET) Parameters:
- email (required): a valid email address to identify user
Examples: Look up a profile by email "example@example.com"
$profile = $sailthru->get_email("example@example.com");
Blast API Helper Functions
schedule_blast(name, list, schedule_time, from_name, from_email, subject, content_html, content_text, options)
Description: Schedule an email campaign to a list of users API: blast (POST) Parameters:
- name (required): the name to give to the new blast
- list (required): the mailing list name to send to
- schedule_time (required): when the blast should be sent. See blast API for accepted format.
- from_name (required): the name appearing in the "From" of the email
- from_email (required): the email address to use as the "from" - choose from any of your verified emails
- subject (required): the subject line of the email
- content_html (required): the HTML-format version of the email
- content_text (required): the text-format version of the email
- options (optional): a hash reference of options to schedule this blast. Available options can be found in blast API page.
Examples: Schedule a blast named "promotion" to users in list "newsletter subscribers"
$status = $sailthru->schedule_blast(
"promotion",
"newsletter subscribers",
"tomorrow 8:00am UTC",
"Daily Newsletter",
"[newsletter@example.com](mailto:newsletter@example.com)",
"The hottest discount",
"sample html page...",
"sample text page...",
{ "is_link_tracking" => 1 }
);
schedule_blast_from_template(template, list, schedule_time, options)
Description: Schedule an email campaign to a list of users using a template API: blast (POST) Parameters:
- template (required): the template name to use for the campaign
- list (required): the mailing list name to send to
- schedule_time (required): when the blast should be sent. See blast API for accepted format.
- options (optional): a hash reference of options to schedule this blast. Available options can be found in blast API page.
Examples: Schedule a blast using template "black Friday promotion" to users in list "newsletter subscribers"
$status = $sailthru->schedule_blast(
"black Friday promotion",
"newsletter subscribers",
"tomorrow 8:00am UTC",
{ "is_link_tracking" => 1 }
);
get_blast(blast_id)
Description: Get data on a single blast, by its "blast_id". API: blast (GET) Parameters:
- blast_id (required): the blast ID which was in the response of a previous blast call
Examples: Look up a blast by blast_id
$blast = $sailthru->get_blast(123456);
Template API Helper Functions
get_template(template)
Description: Get information about a "template" API: template (GET) Parameters:
- template (required): the name of the template
Examples: Look up a template by template name
$template = $sailthru->get_template("newsletter");
Rate Limiting API Helper Functions
get_last_rate_limit_info(action, method)
Description: Get the latest rate limit information for API endpoint "action" and HTTP "method" Parameters:
- action (required): the API endpoint
- method (required): the HTTP method
Examples: Look up rate limit information for "user" POST API call
$rate_limit_info = $sailthru_client->get_last_rate_limit_info('user', 'POST');
# get_last_rate_limit_info returns undef if given endpoint/method wasn't triggered previously
if (defined $rate_limit_info) {
$limit = $rate_limit_info->limit;
$remaining = $rate_limit_info->remaining;
$reset_timestamp = $rate_limit_info->reset;
# throttle api calls based on last rate limit info
if ($remaining <= 0) {
$seconds_till_reset = $reset_timestamp - time
# sleep or perform other business logic before next user api call
sleep($reconds_till_reset);
}
}
Low-Level Functions
api_get(action, data)
Description GET API call to "action" with "data" Parameter definitions
- action (required): name of the API endpoint
- data (required): hash reference of API parameters
Example: get a block by block id **"0a13caa0-1535-11e5-8db3-02882d48a718**"
$sailthru->api_get("block",
{ "block_id" => "0a13caa0-1535-11e5-8db3-02882d48a718"});
api_post(action, data)
Description POST API call to "action" with "data" Parameter definitions
- action (required): name of the API endpoint
- data (required): hash reference of payload data
Example: create a new block "VIP"
$sailthru->api_post("block", { "name" => "VIP", "type" => "html", "content" => "<div>VIP shopping area</div>"});
api_delete(action, data)
Description DELETE API call to "action" with "data" Parameter definitions
- action (required): name of the API endpoint
- data (required): hash reference of payload data
Example: delete a block by block id "****0a13caa0-1535-11e5-8db3-02882d48a718****"
$sailthru->api_delete("block",
{"block_id" => "0a13caa0-1535-11e5-8db3-02882d48a718"});
