Ruby Library

Welcome to our updated API documentation! (Details here.)
We invite you to rate this page at the bottom or send feedback to docs@sailthru.com.
The Sailthru API client library for Ruby is available as a gem. It is also available here on Github.

The library offers access to Sailthru’s REST API.

  • Helper functions exist to expedite most functionality across all API endpoints.

  • You can also use the included low-level functions to build fully custom API calls according to the parameters specified in the Sailthru API reference documentation.

Contents

Getting Started

Installation

This client can be installed as a gem. The gem supports Ruby 1.9.3 and above.

To install: gem install sailthru-client

Setup

This client library requires the client API key and secret, which can be found at https://my.sailthru.com/settings/api_postbacks

To use the sailthru ruby client library, add the following code to your application:

require 'sailthru'
api_key = '***'
api_secret = '***'
sailthru_client = Sailthru::Client.new(api_key, api_secret)

To increase timeout from 10 seconds (default) to 30 seconds, replace the above with:

require 'sailthru'
api_key = '***'
api_secret = '***'
api_uri = 'https://api.sailthru.com'
proxy_host = nil
proxy_port = nil
opts = {
    :http_read_timeout => 30,
    :http_ssl_timeout => 30,
    :http_open_timeout => 30
}
sailthru_client = Sailthru::Client.new(api_key, api_secret, api_uri, proxy_host, proxy_port, opts)

Version

version = Sailthru::VERSION

Helper Functions

The following subsections represent the Sailthru API endpoint accessed by the helper functions within.

USER

save_user(id, options = {})

  • Underlying Endpoint: user POST

  • Save data in options to the user with id. Returns a JSON document indicating whether save was successful.

  • Parameters

    • id (required) – the string id of the user
      • Defaults to Sailthru ID (sid)

      • Can specify key in options for all other id values

    • options (optional) – JSON document to add to the user

Example: Update existing user by Sailthru ID

sid = '4e2879472d7acd6d97144f9e' # sailthru ID
options = {
    :keys => {
        :email => 'test@sailthru.com',
        :twitter => 'abcdefg',
        :fb => 777777777
    },
    :lists => {
        :list_1 => 1, # add to list
        :list_2 => 0, # remove from list
    }
}
response = sailthru_client.save_user(sid, options)

Example: Update existing user by email

options = {
    :key => 'email',
    :lists => {
        :list_1 => 0
    }
}
response = sailthru_client.save_user('test@sailthru.com', options)

get_user_by_sid(id, fields = {})

  • Underlying Endpoint: user GET

  • Get the data in fields from the user with id. Returns a JSON document with data.

  • Parameters:

    • id (required) – the string Sailthru ID (sid) of the user

    • fields (optional) – JSON document of fields to be returned for the user. The value for each key-value pair in this document should be 1. An empty object will return no fields unless there is an error.

Example: Get user by Sailthru ID

fields = { :keys => 1, :vars => 1, :activity => 1 }
response = sailthru_client.get_user_by_sid('4e2879472d7acd6d97144f9e', fields)

get_user_by_key(id, key, fields = {})

  • Underlying Endpoint: user GET

  • Get the data in fields from the user with id. Returns a JSON document with data.

  • Parameters:

    • id (required) – the string id of the user

    • key (required) – the string indicating the type of id (see options)

    • fields (optional) – JSON document of fields to be returned for the user. The value for each key-value pair in this document should be 1. An empty object will return no fields unless there is an error.

Example: Get user by custom key

fields = { :vars => 1, :lists => 1}
response = sailthru_client.get_user_by_key('test@sailthru.com', 'email', fields)

CONTENT

push_content(title, url, date = nil, tags = nil, vars = {}, options = {})

  • Underlying Endpoint: content POST

  • Save a piece of content with title and url. Optionally save additional data. Returns a JSON document with added data.

  • Parameters:

    • title (required) – the string of title for the piece of content

    • url (required) – the string of the url for the piece of content

    • date (optional) – the string date attributed for the piece of content, current date/time will be used if not provided

    • tags (optional) – the array of tags for the piece of content

    • vars (optional) – the JSON document of variables for the piece of content

    • options (optional) – JSON document to add additional fields to the content

Example: Add a piece of content with minimum parameters

title = 'hello world'
url = 'http://example.com/product-url'
response = sailthru_client.push_content(title, url)

Example Add a piece of content with all available parameters

title = 'hello world 2'
url = 'http://example2.com/product-url'
date = 'Mon, 23 May 2016 11:22:33 -0400'
tags = ["blue", "red", "green"]
vars = { :vars => [ :price => 17299]}
response = sailthru_client.push_content(title, url, date, tags, vars)

LIST

save_list(list, options = {})

  • Underlying Endpoint: list POST

  • Create or update a list. Returns a JSON document with added data.

    • list (required) – the string name of the list

    • options (optional) – JSON document to add additional fields to the list

Example: Save a primary list called my-list. If my-list exists, will update my-list

list_name = 'my-list'
options = { :primary => 1 }
response = sailthru_client.save_list(list_name, options)

get_lists()

  • Underlying Endpoint: list GET

  • Get all lists. Returns a JSON document with list data.

Example: Get all lists

response = sailthru_client.get_lists()

get_list(list)

  • Underlying Endpoint: list GET

  • Get a single list. Returns a JSON document with list data.

  • Parameters:

    • list (required) – the string name of the list

Example: Get list named my-list

list_name = 'my-list'
response = sailthru_client.get_list(list_name)

delete_list(list)

  • Underlying Endpoint: list DELETE

  • Delete a single list. Returns a JSON document verifying list was deleted.

  • Parameters:

    • list (required) – the string name of the list

Example: Delete list named my-list

list_name = 'my-list'
response = sailthru_client.delete_list(list_name)

stats_list(list = nil, date = nil)

  • Underlying Endpoint: stats GET

  • Get information about subscriber counts on a particular list and/or on a particular day.

  • Parameters:

    • list (optional) – the string name of the list

    • date (optional) – the date

Example: Get subscriber counts for all lists today

response = sailthru_client.stats_list()

Example: Get subscriber counts for one list

list_name = 'my-list'
response = sailthru_client.stats_list(list_name)

Example: Get subscriber counts for all lists on a particular date

date = 'Sun, 18 Dec 2016 15:17:58 -0500'
response = sailthru_client.stats_list('', date)

Example: Get subscriber counts for one list on a particular date

list_name = 'my-list'
date = 'Sun, 18 Dec 2016 15:17:58 -0500'
response = sailthru_client.stats_list(list_name, date)

TEMPLATE

save_template(template_name, template_fields)

  • Underlying Endpoint: template POST

  • Create or update a template. Returns a JSON document with added data.

Example: Save a template called my-template. If it exists, will update my-template

template_fields = {
    :replyto_email => 'test@sailthru.com',
    :subject => 'Ruby Test'
}
response = sailthru_client.save_template('my-template', template_fields)

get_templates()

  • Underlying Endpoint: template GET

  • Get all templates. Returns a JSON document with template data.

Example: Get all templates

response = sailthru_client.get_templates()

get_template(template_name)

  • Underlying Endpoint: template GET

  • Get a single template. Returns a JSON document with template data.

  • Parameters:

    • template_name (required) – the string name of the template

Example: Get template named my-template

response = sailthru_client.get_template('my-template')

delete_template(template_name)

  • Underlying Endpoint: template DELETE

  • Delete a single template. Returns a JSON document verifying template was deleted.

  • Parameters:

    • template_name (required) – the string name of the template

Example: Delete template named my-template

response = sailthru_client.delete_template('my-template')

EVENT

post_event(id, event, options = {})

  • Underlying Endpoint: event POST

  • Notify Sailthru an event occurred. Returns a JSON document verifying event triggered.

  • Parameters:

    • id (required) – the string id of the user to perform the event
      • Defaults to Sailthru ID (sid)

      • Can specify key in options for all other id values

    • event (required) – the string name of the event

    • options (optional) – JSON document for additional event specifications

Example: Event will_attend_concert happens on 3/1/2017 for

test@sailthru.com
id = 'test@sailthru.com'
event = 'will_attend_concert'
options = {
    :key => 'email' ,
    :schedule_time => 'March 1, 2017 9:00pm EST',
}
response = sailthru_client.post_event(id, event, options)

TRIGGERS

post_event_trigger(event, time, time_unit, zephyr)

  • Underlying Endpoint: trigger POST

  • Create or update a trigger for an event. Returns a JSON document with trigger data.

  • Parameters:

    • event (required) – the string name of the event

    • time (required) – integer value for trigger time

    • time_unit (required) – trigger time unit – can be minutes, hours or days

    • zephyr (required) – the string value of Zephyr syntax

Example:

event = 'will_attend_concert'
time = 10
time_unit = 'minutes'
zephyr = '{api_send("my-template")}'
response = sailthru_client.post_event_trigger(event, time, time_unit, zephyr)

get_trigger_by_event(event)

  • Underlying Endpoint: trigger GET

  • Get an existing trigger for an event. Returns a JSON document with trigger data.

  • Parameters:

    • event (required) – the string name of the event

Example: Get all triggers for event named will_attend_concert

response = sailthru_client.get_trigger_by_event('will_attend_concert')

post_template_trigger(template, time, time_unit, event, zephyr)

  • Underlying Endpoint: trigger POST

  • Create or update a trigger for a template. Returns a JSON document with trigger data.

  • Parameters:

    • template (required) – the string name of the template

    • time (required) – integer value for trigger time

    • time_unit (required) – trigger time unit – can be minutes, hours or days

    • event (required) – string event name set to occur on click, open, send, purchase or cancel

    • zephyr (required) – the string value of Zephyr syntax

Example:

template = 'my-template'
time = 1
time_unit = 'minutes'
event = 'open'
zephyr = '{api_user({"lists": {"opened-email": 1}})}'
response = sailthru_client.post_template_trigger(template, time, time_unit, event, zephyr)

get_trigger_by_template(template, trigger_id = nil)

  • Underlying Endpoint: trigger GET

  • Get an existing trigger for a template. Returns a JSON document with trigger data.

  • Parameters:

    • template (required) – the string name of the template

    • trigger_id (optional) – the specific id for the trigger to retrieve

Example: Get all triggers for template named my-template

response = sailthru_client.get_trigger_by_template('my-template')

Example: Get trigger with id 5858546a66c379a53f8b5602 for template my-template

response = sailthru_client.get_trigger_by_template('my-template', '5858546a66c379a53f8b5602')

get_triggers()

  • Underlying Endpoint: trigger GET

  • Get all existing triggers. Returns a JSON document with all trigger data.

Example: Get all triggers

response = sailthru_client.get_triggers()

SEND

send_email(template_name, email, vars={}, options = {}, schedule_time = nil)

  • Underlying Endpoint: send POST

  • Send a transactional email. Returns a JSON document with send data.

  • Parameters:

    • template_name (required) – the string name of the template to send

    • email (required) – the string email to send the transactional

    • vars (optional) – JSON document of the replacement vars to use in the send.

    • options (optional)

      • replyto – override the Reply-To header

      • test – send as test email (subject line will be marked, will not count towards stats)

      • headers[Cc] – include an email address on copy. Cc must be capitalized like shown.

      • headers[Bcc] – include an email address on blind copy. Bcc must be capitalized like shown. Note that BCC should be used carefully as some email domains guard against it in spam filters.

      • behalf_email – Use the Sender/From headers to send the email on behalf of a third party. Note that this should be used sparingly as it will impact deliverability.

    • schedule_time (optional) – send the email at some point in the future, otherwise it will send immediately. Any date recognized by PHP’s strtotime function is valid, but be sure to specify timezone or use a UTC time to avoid confusion.

Example: Send a test transactional email to test@sailthru.com with template my-template in 2 hours with vars name and myvar

template_name = 'my-template'
email = 'test@sailthru.com'
vars = { :name => 'Bob Foo', :myvar => [1111, 2, 3]}
options = { :test => 1}
schedule_time = '+2 hours'
response = sailthru_client.send_email(template_name, email, vars, options, schedule_time)

multi_send(template_name, emails, vars={}, options = {}, schedule_time = nil, evars = {})

  • Underlying Endpoint: send POST

  • Send a transactional email to multiple email addresses at once. Returns a JSON document with send data.

  • Parameters:

    • template_name (required) – the string name of the template to send

    • email (required) – the string email to send the transactional

    • vars (optional) – JSON document of the replacement vars to use in the send.

    • options (optional)

      • replyto – override the Reply-To header

      • test – send as test email (subject line will be marked, will not count towards stats)

      • headers[Cc] – include an email address on copy. Cc must be capitalized like shown.

      • headers[Bcc] – include an email address on blind copy. Bcc must be capitalized like shown. Note that BCC should be used carefully as some email domains guard against it in spam filters.

      • behalf_email – Use the Sender/From headers to send the email on behalf of a third party. Note that this should be used sparingly as it will impact deliverability.

    • schedule_time (optional) – send the email at some point in the future, otherwise it will send immediately. Any date recognized by PHP’s strtotime function is valid, but be sure to specify timezone or use a UTC time to avoid confusion.

    • evars (optional) – JSON document where each key is an email address, and each value is a key/value hash of variables for that particular email address

Example: Send transactional emails to test@sailthru.com and example@sailthru.com with template my-template. Send 2 days before Saturday, September 14, 2012 9:00pm EST with vars deal and percent_off set the same for both emails and var name differing by email.

template_name = 'my-template'
emails = 'test@sailthru.com, example@sailthru.com'
vars = { :deal => 'Black Friday Deal', :percent_off => 10}
options = { :replyto => 'support@sailthru.com'}
schedule_time = 'Saturday, September 14, 2012 9:00pm EST -2 days'
evars = {
    'test@sailthru.com' => { :name => 'Bob Foo'},
    'example@sailthru.com' => { :name => 'Alice Bar'}
}
response = sailthru_client.multi_send(template_name, emails, vars, options, schedule_time, evars)

get_send(send_id)

  • Underlying Endpoint: send GET

  • Check on the status of a send. Returns a JSON document with send data.

  • Parameters:

    • send_id (required) – the unique identifier of the send

Example: Get send data for send with id WFrilv9TCv82i1LS

send_id = 'WFrilv9TCv82i1LS'
response = sailthru_client.get_send(send_id)

cancel_send(send_id)

  • Underlying Endpoint: send DELETE

  • Cancel a future send before it goes out. Returns a JSON document indicating whether send was successfully cancelled

    • send_id (required) – the unique identifier of the send

Example: Cancel send with send id WFrTROkyi1gUi1Nw

send_id = 'WFrTROkyi1gUi1Nw'
response = sailthru_client.cancel_send(send_id)

stats_send(template = nil, start_date = nil, end_date = nil, options = {})

  • Underlying Endpoint: stats GET

  • Retrieve aggregated information from transactionals from a template over a specified date range. Returns a JSON document with send stats data.

  • Parameters:

    • template (required) – the string name of the template to pull information from

    • start_date (required) – beginning of the date range from which to pull aggregated send stats.

    • end_date (required) – end of the date range from which to pull aggregated send stats.

    • options (optional) – JSON document for additional send specifications

Example: Get send data for my-template for December 2016

response = sailthru_client.stats_send('my-template', '2016-12-01', '2016-12-31')

BLAST

schedule_blast(name, list, schedule_time, from_name, from_email, subject, content_html, content_text, options = {})

  • Underlying Endpoint: blast POST

  • Schedule a mass mail blast. Returns a JSON document with blast data.

  • Parameters:

    • name (required) – string name of the blast

    • list (required) – string name of the list to send the blast to

    • schedule_time (required) – date string time to send the blast

    • from_name (required) – the name appearing in the “From” of the email

    • from_email (required) – email address to use as the “from” – choose from any of your verified emails

    • subject (required) – subject line of the email

    • html (required) – HTML-format version of the email

    • text (required) – text-format version of the email

    • options (optional) – JSON document for additional blast specifications

Example: Send all users on my-list an email from Sailthru in 5 hours with email support@sailthru.com and with subject Testing My Blast.

blast_name = 'my-blast'
list = 'my-list'
schedule_time = '+5 hours'
from_name = 'Sailthru'
from_email = 'support@sailthru.com'
subject = 'Testing My Blast'
html = '<p>Lorem ispum is great</p>'
text = 'Lorem ispum is great'
response = sailthru_client.schedule_blast(blast_name, list, schedule_time, from_name, from_email, subject, html, text)

schedule_blast_from_template(template, list, schedule_time, options={})

  • Underlying Endpoint: blast POST

  • Schedule a blast from a template. Returns a JSON document with blast data.

  • Parameters:

    • template (required) – string name of the template to use for blast

    • list (required) – string name of the list to send the blast to

    • schedule_time (required) – date string time to send the blast

    • options (required) – JSON document for additional blast specifications

      • from_name (required) – the name appearing in the “From” of the email

      • from_email (required) – email address to use as the “from” – choose from any of your verified emails

      • html_content (required) – HTML-format version of the email

      • content_text (required) – text-format version of the email

Example: Send all users on my-list an email now using template my-template

template = 'my-template'
list = 'my-list'
schedule_time = 'now'
options = {
    :from_name => 'Sailthru',
    :from_email => ['support@sailthru.com](mailto:%27support@sailthru.com)',
    :html_content => '<p>Lorem ispum is great</p>',
    :content_text => 'Lorem ispum is great'
}
response = sailthru_client.schedule_blast_from_template(template, list, schedule_time, options)

schedule_blast_from_blast(blast_id, schedule_time, options={})

  • Underlying Endpoint: blast POST

  • Schedule a blast from a previous blast. Returns a JSON document with blast data.

  • Parameters:

    • blast_id (required) – the number id for blast

    • schedule_time (required) – date string time to send the blast

    • options (optional) – JSON document for additional blast specifications

Example:

blast_id = 8430147
schedule_time ='now'
vars = {
   :deal => 'Black Friday',
   :percents => [10, 20, 30],
   :gifts => {
       :kids => 'puzzle',
       :adults => {
           :men => 'tools',
           :women => 'jewelry'
       }
   }
}
options = {:vars => vars}
response = sailthru_client.schedule_blast_from_blast(blast_id, schedule_time, options)

update_blast(blast_id, name = nil, list = nil, schedule_time = nil, from_name = nil, from_email = nil, subject = nil, content_html = nil, content_text = nil, options = {})

  • Underlying Endpoint: blast POST

  • Update an existing blast. Returns a JSON document with blast data.

  • Parameters:

    • blast_id (required) – the number id for blast

    • name (optional) – string name of the blast

    • list (optional) – string name of the list to send the blast to

    • schedule_time (optional) – date string time to send the blast

    • from_name (optional) – the name appearing in the “From” of the email

    • from_email (optional) – email address to use as the “from” – choose from any of your verified emails

    • 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) – JSON document for additional blast specifications

Example: Update blast with id 8435921 to use list list_A and from name to Sailthru Support

blast_id = 8435921
response = sailthru_client.update_blast(blast_id, nil, 'list_A', nil, 'Sailthru Support')

get_blast(blast_id, options={})

  • Underlying Endpoint: blast GET

  • Get information on a previously scheduled email blast. Returns a JSON document with blast data.

  • Parameters:

    • blast_id (required) – the number id for blast

    • options (optional) – JSON document for additional blast specifications

Example: Get information about blast with id 8435921

response = sailthru_client.get_blast(8435921)

cancel_blast(blast_id)

  • Underlying Endpoint: blast POST

  • Cancel a scheduled email blast (sets schedule_time of blast to empty string). Returns a JSON document with blast data.

  • Parameters:

    • blast_id (required) – the number id for blast

Example: Cancel blast with id 8435921

response = sailthru_client.cancel_blast(8435921)

delete_blast(blast_id)

  • Underlying Endpoint: blast DELETE

  • Delete a blast. Returns a JSON document indicating whether blast was successfully deleted

  • Parameters:

    • blast_id (required) – the number id for blast

Example: Delete blast with id 8435921

response = sailthru_client.cancel_blast(8435921)

stats_blast(blast_id = nil, start_date = nil, end_date = nil, options = {})

  • Underlying Endpoint: stats GET

  • Retrieve information about a particular blast (campaign) or aggregated information from all blasts over a specified date range. Must specify either a blast_id or a start_date and end_date.

  • Parameters:

    • blast_id (optional when dates given) – id of the blast to pull information from

    • start_date (optional when blast_id given) – beginning of the date range from which to pull aggregated send stats.

    • end_date (optional when blast_id given) – end of the date range from which to pull aggregated blast stats.

    • options (optional) – JSON document for additional blast specifications

Example: Get stats information for blast with id 8436709

response = sailthru_client.stats_blast(8436709)

Example: Get stats information for all blasts between 2016-12-01 and 2016-12-29

response = sailthru_client.stats_blast(nil, '2016-12-01', '2016-12-29')

EMAIL

set_email(email, vars = {}, lists = {}, templates = {}, options = {})

  • Underlying Endpoint: email POST

  • Set replacement vars and/or list subscriptions for an email address

  • Parameters:

    • email (required) – the string email to update

    • vars (optional) – the JSON document of vars to add or update for the email

    • lists (optional) – the JSON document of lists to add or remove for the email

    • templates (optional) – the JSON document of templates to add or remove for the email

    • options (optional) – JSON document for additional blast specifications

Example: Update test@sailthru.com with source and fname vars, add my-list list and my-template template

vars = { :source => 'web', :fname => 'Bob' }
lists = {'my-list' => 1}
templates = {'my-template' => 1}
response = sailthru_client.set_email('test@sailthru.com', vars, lists, templates)

Rate Limit

get_last_rate_limit_info(endpoint, method)

Allows inspection of the X-Rate-Limit-* headers returned by the Sailthru API by retrieving the last known rate limit information for the given endpoint and method combination. It must follow an API call.

EXAMPLE: After a POST to the send API

template_name = 'some template'
email = 'test@sailthru.com'
response = sailthru.send_email(template_name, email, {foo: 'bar'})
rate_limit_info = sailthru.get_last_rate_limit_info('send', 'post')

The return type will be nil if there is no rate limit information for the given endpoint / method combination (e.g. if you have not yet made a request to that endpoint). Otherwise, it will be a hash in the following format:

{
    limit: 1234,
    remaining: 1230,
    reset: 1459381680
}
  • limit – Number representing the limit of requests/minute for this action / method combination

  • remaining – Number representing how many requests remain in the current minute

  • reset – Number representing the UNIX epoch timestamp of when the next minute starts, and when the rate limit resets

Low-Level Functions

api_get(action, data)

  • Request item that matches data from collection action. Returns a JSON document

  • Parameters:

    • action – the name of the collection requesting item from

    • data – a JSON document search for item from collection

Example: Call to get all the vars and lists for User with email address test@sailthru.com. Exclude fields parameter to get all data for the user.

data = {
    :id => 'test@sailthru.com',
    :key => 'email',
    :fields => { :vars => 1, :lists => 1}
}
response = sailthru_client.api_get('user', data)
  • Successful response:
    {
        "vars" => {
            "source" => "web", "fname" => "Bob"
        }, "lists" => {
            "Master List" => "Fri, 02 Dec 2016 10:01:59 -0500"
        }
    }
    
  • Unsuccessful response:
    {
        "error"=>99,
        "errormsg"=>"error message"
    }
    

api_post(action, data)

  • Save item that matches data into collection action. Returns a JSON document indicating whether data was successfully saved in action collection

  • Parameters:

    • action – the name of the collection to save item to

    • data – a JSON document to save in collection

Example: For the User with sid (sailthru ID) 4e2879472d7acd6d97144f9e: Add the user to list-A, remove the user from list-B, add source and address vars.

data = {
     :id => '4e2879472d7acd6d97144f9e', #sailthru ID
     :lists => {
         :list_A => 1,
         :list_B => 0   #optout of this list
     },
     :vars => {
         :source => 'test',
         :address => {
             :city => 'New York',
             :state => 'NY',
             :zipcode => 10011
         }
    }
}
response = sailthru_client.api_post('user', data)
  • Successful response:
    {
        "ok"=>true
    }
    
  • Unsuccessful response:
    {
        "error"=>99, 
        "errormsg"=>"Invalid sid: 444"
    }
    

api_delete(action, data)

  • Delete item that matches data from collection action. Returns a JSON document indicating whether data was successfully saved in action collection

  • Parameters:

    • action – the name of the collection to delete item from

    • data – a JSON document to remove from collection

Example: Remove the Template with template_id 5033705

data = { :template_id => '5033705' }
response = sailthru_client.api_delete('template', data)
  • Successful response:
    {
        "template"=>nil, 
        "ok"=>true
    }
    
  • Unsuccessful response:
    {
       "error"=>99, 
       "errormsg"=>"A valid template or template_id must be provided"
    }
    
Top