Class: Sailthru::SailthruClient

Inherits:
Object
  • Object
show all
Includes:
Helpers
Defined in:
lib/sailthru.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Helpers

#extract_param_values, #flatten_nested_hash, #get_signature_hash, #get_signature_string

Constructor Details

#initialize(api_key, secret, api_uri = nil, proxy_host = nil, proxy_port = nil) ⇒ SailthruClient

params:

api_key, String
secret, String
api_uri, String

Instantiate a new client; constructor optionally takes overrides for key/secret/uri and proxy server settings.



105
106
107
108
109
110
111
112
 
# File 'lib/sailthru.rb', line 105

def initialize(api_key, secret, api_uri=nil, proxy_host=nil, proxy_port=nil)
  @api_key = api_key
  @secret  = secret
  @api_uri = if api_uri.nil? then 'https://api.sailthru.com' else api_uri end
  @proxy_host = proxy_host
  @proxy_port = proxy_port
  @verify_ssl = true
end

Instance Attribute Details

#verify_ssl ⇒ Object

Returns the value of attribute verify_ssl.



97
98
99
 
# File 'lib/sailthru.rb', line 97

def verify_ssl
  @verify_ssl
end

Instance Method Details

#api_delete(action, data) ⇒ Object

Perform API DELETE request



831
832
833
 
# File 'lib/sailthru.rb', line 831

def api_delete(action, data)
  api_request(action, data, 'DELETE')
end

#api_get(action, data) ⇒ Object

Perform API GET request



821
822
823
 
# File 'lib/sailthru.rb', line 821

def api_get(action, data)
  api_request(action, data, 'GET')
end

#api_post(action, data, binary_key = nil) ⇒ Object

Perform API POST request



826
827
828
 
# File 'lib/sailthru.rb', line 826

def api_post(action, data, binary_key = nil)
  api_request(action, data, 'POST', binary_key)
end

#cancel_blast(blast_id) ⇒ Object

params:

blast_id, Fixnum | String

Cancel a scheduled Blast



285
286
287
 
# File 'lib/sailthru.rb', line 285

def cancel_blast(blast_id)
  api_post(:blast, {:blast_id => blast_id, :schedule_time => ''})
end

#cancel_send(send_id) ⇒ Object 



175
176
177
 
# File 'lib/sailthru.rb', line 175

def cancel_send(send_id)
  self.api_delete(:send, {:send_id => send_id.to_s})
end

#change_email(new_email, old_email, options = {}) ⇒ Object

params:

new_email, String
old_email, String
options, Hash mapping optional parameters

returns:

Hash of response data.

change a user’s email address.



333
334
335
336
337
338
 
# File 'lib/sailthru.rb', line 333

def change_email(new_email, old_email, options = {})
  data = options
  data[:email] = new_email
  data[:change_email] = old_email
  self.api_post(:email, data)
end

#delete_alert(email, alert_id) ⇒ Object

params

email, String
alert_id, String

delete user alert



653
654
655
656
 
# File 'lib/sailthru.rb', line 653

def delete_alert(email, alert_id)
  data = {:email => email, :alert_id => alert_id}
  api_delete(:alert, data)
end

#delete_blast(blast_id) ⇒ Object

params:

blast_id, Fixnum | String

Delete a Blast



293
294
295
 
# File 'lib/sailthru.rb', line 293

def delete_blast(blast_id)
  api_delete(:blast, {:blast_id => blast_id})
end

#delete_content(url) ⇒ Object

params

url, String

Delete a piece of content from Sailthru. docs.sailthru.com/api/content



580
581
582
583
584
 
# File 'lib/sailthru.rb', line 580

def delete_content(url)
  data = {}
  data[:url] = url
  api_delete(:content, data)
end

#delete_list(list) ⇒ Object

params

list, String

Deletes a list



615
616
617
 
# File 'lib/sailthru.rb', line 615

def delete_list(list)
  api_delete(:list, {:list => list})
end

#delete_template(template_name) ⇒ Object

params:

template_name, String

returns:

Hash of response data.

Delete a template.



370
371
372
 
# File 'lib/sailthru.rb', line 370

def delete_template(template_name)
  self.api_delete(:template, {:template => template_name})
end

#get_alert(email) ⇒ Object

params

email, String

get user alert data



623
624
625
 
# File 'lib/sailthru.rb', line 623

def get_alert(email)
  api_get(:alert, {:email => email})
end

#get_blast(blast_id, options = {}) ⇒ Object

params:

blast_id, Fixnum | String
options, hash

returns:

Hash, response data from server

Get information on a previously scheduled email blast



276
277
278
279
 
# File 'lib/sailthru.rb', line 276

def get_blast(blast_id, options={})
  options[:blast_id] = blast_id.to_s
  api_get(:blast, options)
end

#get_email(email) ⇒ Object

params:

email, String

returns:

Hash, response data from server

Return information about an email address, including replacement vars and lists.



303
304
305
 
# File 'lib/sailthru.rb', line 303

def get_email(email)
  api_get(:email, {:email => email})
end

#get_job_status(job_id) ⇒ Object

get status of a job



724
725
726
 
# File 'lib/sailthru.rb', line 724

def get_job_status(job_id)
  api_get(:job, {'job_id' => job_id})
end

#get_list(list) ⇒ Object

params

list, String

Get information about a list.



590
591
592
 
# File 'lib/sailthru.rb', line 590

def get_list(list)
  return api_get(:list, {:list => list})
end

#get_lists ⇒ Object

params

Get information about all lists



597
598
599
 
# File 'lib/sailthru.rb', line 597

def get_lists()
    return api_get(:list, {})
end

#get_send(send_id) ⇒ Object

params:

send_id, Fixnum

returns:

Hash, response data from server

Get the status of a send.



170
171
172
 
# File 'lib/sailthru.rb', line 170

def get_send(send_id)
  self.api_get(:send, {:send_id => send_id.to_s})
end

#get_stats(stat) ⇒ Object

DEPRECATED: Please use either stats_list or stats_blast params:

 stat, String

returns:
 hash, response from server

Request various stats from Sailthru.



471
472
473
474
 
# File 'lib/sailthru.rb', line 471

def get_stats(stat)
  warn "[DEPRECATION] `get_stats` is deprecated. Please use `stats_list` and `stats_blast` instead"
  api_get(:stats, {:stat => stat})
end

#get_template(template_name) ⇒ Object

params:

template_name, String

returns:

Hash of response data.

Get a template.



346
347
348
 
# File 'lib/sailthru.rb', line 346

def get_template(template_name)
  self.api_get(:template, {:template => template_name})
end

#get_trigger_by_event(event) ⇒ Object

params

event, String

Get an existing trigger



770
771
772
773
774
 
# File 'lib/sailthru.rb', line 770

def get_trigger_by_event(event)
    data = {}
    data['event'] = event
    api_get(:trigger, data)
end

#get_trigger_by_template(template, trigger_id = nil) ⇒ Object

params

template, String
trigger_id, String

Get an existing trigger



760
761
762
763
764
765
 
# File 'lib/sailthru.rb', line 760

def get_trigger_by_template(template, trigger_id = nil)
    data = {}
    data['template'] = template
    if trigger_id != nil then data['trigger_id'] = trigger_id end
    api_get(:trigger, data)
end

#get_triggers ⇒ Object

params Get an existing trigger



752
753
754
 
# File 'lib/sailthru.rb', line 752

def get_triggers()
    api_get(:trigger, {})
end

#get_user_by_key(id, key, fields = {}) ⇒ Object

Get user by specified key



734
735
736
737
738
739
740
741
 
# File 'lib/sailthru.rb', line 734

def get_user_by_key(id, key, fields = {})
    data = {
        'id' => id,
        'key' => key,
        'fields' => fields
    }
    api_get(:user, data)
end

#get_user_by_sid(id, fields = {}) ⇒ Object

Get user by Sailthru ID



729
730
731
 
# File 'lib/sailthru.rb', line 729

def get_user_by_sid(id, fields = {})
    api_get(:user, {'id' => id, 'fields' => fields})
end

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



152
153
154
155
156
157
158
159
160
161
 
# File 'lib/sailthru.rb', line 152

def multi_send(template_name, emails, vars={}, options = {}, schedule_time = nil, evars = {})
  post = {}
  post[:template] = template_name
  post[:email] = emails
  post[:vars] = vars if vars.length >= 1
  post[:options] = options if options.length >= 1
  post[:schedule_time] = schedule_time if !schedule_time.nil?
  post[:evars] = evars if evars.length >= 1
  return self.api_post(:send, post)
end

#post_event(id, event, options = {}) ⇒ Object

params

id, String
event, String
options, Hash (Can contain vars, Hash and/or key)

Notify Sailthru of an Event



813
814
815
816
817
818
 
# File 'lib/sailthru.rb', line 813

def post_event(id, event, options = {})
    data = options
    data['id'] = id
    data['event'] = event
    api_post(:event, data)
end

#post_event_trigger(event, time, time_unit, zephyr) ⇒ Object

params

template, String
time, String
time_unit, String
zephyr, String

Create or update a trigger



799
800
801
802
803
804
805
806
 
# File 'lib/sailthru.rb', line 799

def post_event_trigger(event, time, time_unit, zephyr)
    data = {}
    data['time'] = time
    data['time_unit'] = time_unit
    data['event'] = event
    data['zephyr'] = zephyr
    api_post(:trigger, data)
end

#post_template_trigger(template, time, time_unit, event, zephyr) ⇒ Object

params

template, String
time, String
time_unit, String
event, String
zephyr, String

Create or update a trigger



783
784
785
786
787
788
789
790
791
 
# File 'lib/sailthru.rb', line 783

def post_template_trigger(template, time, time_unit, event, zephyr)
    data = {}
    data['template'] = template
    data['time'] = time
    data['time_unit'] = time_unit
    data['event'] = event
    data['zephyr'] = zephyr
    api_post(:trigger, data)
end

#process_export_list_job(list, report_email = nil, postback_url = nil) ⇒ Object

implementation for export list job



717
718
719
720
721
 
# File 'lib/sailthru.rb', line 717

def process_export_list_job(list, report_email = nil, postback_url = nil)
  data = {}
  data['list'] = list
  process_job(:export_list_data, data, report_email, postback_url)
end

#process_import_job(list, emails, report_email = nil, postback_url = nil) ⇒ Object

params

emails, String | Array

implementation for import_job



687
688
689
690
691
692
 
# File 'lib/sailthru.rb', line 687

def process_import_job(list, emails, report_email = nil, postback_url = nil)
  data = {}
  data['list'] = list
  data['emails'] = Array(emails).join(',')
  process_job(:import, data, report_email, postback_url)
end

#process_import_job_from_file(list, file_path, report_email = nil, postback_url = nil) ⇒ Object

implementation for import job using file upload



695
696
697
698
699
700
 
# File 'lib/sailthru.rb', line 695

def process_import_job_from_file(list, file_path, report_email = nil, postback_url = nil)
  data = {}
  data['list'] = list
  data['file'] = file_path
  process_job(:import, data, report_email, postback_url, 'file')
end

#process_job(job, options = {}, report_email = nil, postback_url = nil, binary_key = nil) ⇒ Object

params

job, String
options, hash
report_email, String
postback_url, String
binary_key, String

interface for making request to job call



671
672
673
674
675
676
677
678
679
680
681
682
 
# File 'lib/sailthru.rb', line 671

def process_job(job, options = {}, report_email = nil, postback_url = nil, binary_key = nil)
  data = options
  data['job'] = job
  if !report_email.nil?
    data['report_email'] = report_email
  end

  if !postback_url.nil?
    data['postback_url'] = postback_url
  end
  api_post(:job, data, binary_key)
end

#process_snapshot_job(query = {}, report_email = nil, postback_url = nil) ⇒ Object

implementation for snapshot job



710
711
712
713
714
 
# File 'lib/sailthru.rb', line 710

def process_snapshot_job(query = {}, report_email = nil, postback_url = nil)
  data = {}
  data['query'] = query
  process_job(:snapshot, data, report_email, postback_url)
end

#process_update_job_from_file(file_path, report_email = nil, postback_url = nil) ⇒ Object

implementation for update job using file upload



703
704
705
706
707
 
# File 'lib/sailthru.rb', line 703

def process_update_job_from_file(file_path, report_email = nil, postback_url = nil)
  data = {}
  data['file'] = file_path
  process_job(:update, data, report_email, postback_url, 'file')
end

#purchase(email, items, incomplete = nil, message_id = nil, options = {}) ⇒ Object

params:

email, String
items, String
incomplete, Integer
message_id, String
options, Hash

returns:

hash, response from server

Record that a user has made a purchase, or has added items to their purchase total.



448
449
450
451
452
453
454
455
456
457
458
459
460
461
 
# File 'lib/sailthru.rb', line 448

def purchase(email, items, incomplete = nil, message_id = nil, options = {})
  data = options
  data[:email] = email
  data[:items] = items

  if incomplete != nil
    data[:incomplete] = incomplete.to_i
  end

  if message_id != nil
    data[:message_id] = message_id
  end
  api_post(:purchase, data)
end

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

params

title, String
url, String
date, String
tags, Array or Comma separated string
vars, Hash
options, Hash

Push a new piece of content to Sailthru, triggering any applicable alerts. docs.sailthru.com/api/content



556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
 
# File 'lib/sailthru.rb', line 556

def push_content(title, url, date = nil, tags = nil, vars = {}, options = {})
  data = options
  data[:title] = title
  data[:url] = url
  if date != nil
    data[:date] = date
  end
  if tags != nil
    if tags.class == Array
      tags = tags.join(',')
    end
    data[:tags] = tags
  end
  if vars.length > 0
    data[:vars] = vars
  end
  api_post(:content, data)
end

#receive_hardbounce_post(params, request) ⇒ Object

params:

params, Hash
request, String

returns:

TrueClass or FalseClass, Returns true if the incoming request is an authenticated hardbounce post.



424
425
426
427
428
429
430
431
432
433
434
435
436
 
# File 'lib/sailthru.rb', line 424

def receive_hardbounce_post(params, request)
  if request.post?
    [:action, :email, :sig].each { |key| return false unless params.has_key?(key) }

    return false unless params[:action] == :hardbounce

    sig = params.delete(:sig)
    return false unless sig == get_signature_hash(params, @secret)
    return true
  else
    return false
  end
end

#receive_optout_post(params, request) ⇒ Object

params:

params, Hash
request, String

returns:

TrueClass or FalseClass, Returns true if the incoming request is an authenticated optout post.



405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/sailthru.rb', line 405

def receive_optout_post(params, request)
  if request.post?
    [:action, :email, :sig].each { |key| return false unless params.has_key?(key) }

    return false unless params[:action] == :optout

    sig = params.delete(:sig)
    return false unless sig == get_signature_hash(params, @secret)
    return true
  else
    return false
  end
end

#receive_verify_post(params, request) ⇒ Object

params:

params, Hash
request, String

returns:

TrueClass or FalseClass, Returns true if the incoming request is an authenticated verify post.



380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/sailthru.rb', line 380

def receive_verify_post(params, request)
  if request.post?
    [:action, :email, :send_id, :sig].each { |key| return false unless params.has_key?(key) }

    return false unless params[:action] == :verify

    sig = params.delete(:sig)
    return false unless sig == get_signature_hash(params, @secret)

    _send = self.get_send(params[:send_id])
    return false unless _send.has_key?(:email)

    return false unless _send[:email] == params[:email]

    return true
  else
    return false
  end
end

#save_alert(email, type, template, _when = nil, options = {}) ⇒ Object

params

email, String
type, String
template, String
_when, String
options, hash

Add a new alert to a user. You can add either a realtime or a summary alert (daily/weekly). _when is only required when alert type is weekly or daily



636
637
638
639
640
641
642
643
644
645
 
# File 'lib/sailthru.rb', line 636

def save_alert(email, type, template, _when = nil, options = {})
  data = options
  data[:email] = email
  data[:type] = type
  data[:template] = template
  if (type == 'weekly' || type == 'daily')
    data[:when] = _when
  end
  api_post(:alert, data)
end

#save_list(list, options = {}) ⇒ Object

params

list, String
options, Hash

Create a list, or update a list.



605
606
607
608
609
 
# File 'lib/sailthru.rb', line 605

def save_list(list, options = {})
  data = options
  data[:list] = list
 return api_post(:list, data)
end

#save_template(template_name, template_fields) ⇒ Object

params:

template_name, String
template_fields, Hash

returns:

Hash containg response from the server.

Save a template.



358
359
360
361
362
 
# File 'lib/sailthru.rb', line 358

def save_template(template_name, template_fields)
  data = template_fields
  data[:template] = template_name
  self.api_post(:template, data)
end

#save_user(id, options = {}) ⇒ Object

Create new user, or update existing user



744
745
746
747
748
 
# File 'lib/sailthru.rb', line 744

def save_user(id, options = {})
    data = options
    data['id'] = id
    api_post(:user, data)
end

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

params:

name, String
list, String
schedule_time, String
from_name, String
from_email, String
subject, String
content_html, String
content_text, String
options, Hash

returns:

Hash, response data from server

Schedule a mass mail blast



193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/sailthru.rb', line 193

def schedule_blast(name, list, schedule_time, from_name, from_email, subject, content_html, content_text, options = {})
  post = options ? options : {}
  post[:name] = name
  post[:list] = list
  post[:schedule_time] = schedule_time
  post[:from_name] = from_name
  post[:from_email] = from_email
  post[:subject] = subject
  post[:content_html] = content_html
  post[:content_text] = content_text
  api_post(:blast, post)
end

#schedule_blast_from_blast(blast_id, schedule_time, options = {}) ⇒ Object

Schedule a mass mail blast from previous blast



216
217
218
219
220
221
222
 
# File 'lib/sailthru.rb', line 216

def schedule_blast_from_blast(blast_id, schedule_time, options={})
  post = options ? options : {}
  post[:copy_blast] = blast_id
  #post[:name] = name
  post[:schedule_time] = schedule_time
  api_post(:blast, post)
end

#schedule_blast_from_template(template, list, schedule_time, options = {}) ⇒ Object

Schedule a mass mail blast from template



207
208
209
210
211
212
213
 
# File 'lib/sailthru.rb', line 207

def schedule_blast_from_template(template, list, schedule_time, options={})
  post = options ? options : {}
  post[:copy_template] = template
  post[:list] = list
  post[:schedule_time] = schedule_time
  api_post(:blast, post)
end

#send(template_name, email, vars = {}, options = {}, schedule_time = nil) ⇒ Object

params:

template_name, String
email, String
replacements, Hash
options, Hash
  replyto: override Reply-To header
  test: send as test email (subject line will be marked, will not count towards stats)
schedule_time, Date

returns:

Hash, response data from server

Send a transactional email, or schedule one for the near future docs.sailthru.com/api/send



127
128
129
130
 
# File 'lib/sailthru.rb', line 127

def send(template_name, email, vars={}, options = {}, schedule_time = nil)
  warn "[DEPRECATION] `send` is deprecated. Please use `send_email` instead."
  send_email(template_name, email, vars={}, options = {}, schedule_time = nil)
end

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

params:

template_name, String
email, String
vars, Hash
options, Hash
  replyto: override Reply-To header
  test: send as test email (subject line will be marked, will not count towards stats)

returns:

Hash, response data from server



141
142
143
144
145
146
147
148
149
 
# File 'lib/sailthru.rb', line 141

def send_email(template_name, email, vars={}, options = {}, schedule_time = nil)
  post = {}
  post[:template] = template_name
  post[:email] = email
  post[:vars] = vars if vars.length >= 1
  post[:options] = options if options.length >= 1
  post[:schedule_time] = schedule_time if !schedule_time.nil?
  return self.api_post(:send, post)
end

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

params:

email, String
vars, Hash
lists, Hash mapping list name => 1 for subscribed, 0 for unsubscribed
options, Hash mapping optional parameters

returns:

Hash, response data from server

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



316
317
318
319
320
321
322
323
 
# File 'lib/sailthru.rb', line 316

def set_email(email, vars = {}, lists = {}, templates = {}, options = {})
  data = options
  data[:email] = email
  data[:vars] = vars unless vars.empty?
  data[:lists] = lists unless lists.empty?
  data[:templates] = templates unless templates.empty?
  self.api_post(:email, data)
end

#stats(data) ⇒ Object

Make Stats API Request



659
660
661
 
# File 'lib/sailthru.rb', line 659

def stats(data)
  api_get(:stats, data)
end

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

params

blast_id, String
start_date, String
end_date, String
options, Hash

returns:

hash, response from server

Retrieve information about a particular blast or aggregated information from all of blasts over a specified date range



506
507
508
509
510
511
512
513
514
515
516
517
518
519
 
# File 'lib/sailthru.rb', line 506

def stats_blast(blast_id = nil, start_date = nil, end_date = nil, options = {})
  data = options
  if blast_id != nil
    data[:blast_id] = blast_id
  end
  if start_date != nil
    data[:start_date] = start_date
  end
  if end_date != nil
    data[:end_date] = end_date
  end
  data[:stat] = 'blast'
  stats(data)
end

#stats_list(list = nil, date = nil) ⇒ Object

params

list, String
date, String

returns:

hash, response from server

Retrieve information about your subscriber counts on a particular list, on a particular day.



484
485
486
487
488
489
490
491
492
493
494
 
# File 'lib/sailthru.rb', line 484

def stats_list(list = nil, date = nil)
  data = {}
  if list != nil
    data[:list] = list
  end
  if date != nil
    data[:date] = date
  end
  data[:stat] = 'list'
  stats(data)
end

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

params

template, String
start_date, String
end_date, String
options, Hash

returns:

hash, response from server

Retrieve information about a particular blast or aggregated information from all of blasts over a specified date range



530
531
532
533
534
535
536
537
538
539
540
541
542
543
 
# File 'lib/sailthru.rb', line 530

def stats_send(template = nil, start_date = nil, end_date = nil, options = {})
  data = options
  if template != nil
    data[:template] = template
  end
  if start_date != nil
    data[:start_date] = start_date
  end
  if end_date != nil
    data[:end_date] = end_date
  end
  data[:stat] = 'send'
  stats(data)
end

#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 = {}) ⇒ Object

params

blast_id, Fixnum | String
name, String
list, String
schedule_time, String
from_name, String
from_email, String
subject, String
content_html, String
content_text, String
options, hash

updates existing blast



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/sailthru.rb', line 238

def 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 = {})
  data = options ? options : {}
  data[:blast_id] = blast_id
  if name != nil
    data[:name] = name
  end
  if list !=  nil
    data[:list] = list
  end
  if schedule_time != nil
    data[:schedule_time] = schedule_time
  end
  if from_name != nil
    data[:from_name] = from_name
  end
  if from_email != nil
    data[:from_email] = from_email
  end
  if subject != nil
    data[:subject] = subject
  end
  if content_html != nil
    data[:content_html] = content_html
  end
  if content_text != nil
    data[:content_text] = content_text
  end
  api_post(:blast, data)
end