Perl Library
Contents
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"});