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



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

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

#api_get(action, data) ⇒ Object

Perform API GET request



810
811
812
 
# File 'lib/sailthru.rb', line 810

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

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

Perform API POST request



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

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



642
643
644
645
 
# File 'lib/sailthru.rb', line 642

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_list(list) ⇒ Object

params

list, String

Deletes a list



604
605
606
 
# File 'lib/sailthru.rb', line 604

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



612
613
614
 
# File 'lib/sailthru.rb', line 612

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



713
714
715
 
# File 'lib/sailthru.rb', line 713

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.



579
580
581
 
# File 'lib/sailthru.rb', line 579

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

#get_lists ⇒ Object

params

Get information about all lists



586
587
588
 
# File 'lib/sailthru.rb', line 586

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



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

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



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

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



741
742
743
 
# File 'lib/sailthru.rb', line 741

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

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

Get user by specified key



723
724
725
726
727
728
729
730
 
# File 'lib/sailthru.rb', line 723

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



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

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



802
803
804
805
806
807
 
# File 'lib/sailthru.rb', line 802

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



788
789
790
791
792
793
794
795
 
# File 'lib/sailthru.rb', line 788

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



772
773
774
775
776
777
778
779
780
 
# File 'lib/sailthru.rb', line 772

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



706
707
708
709
710
 
# File 'lib/sailthru.rb', line 706

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



676
677
678
679
680
681
 
# File 'lib/sailthru.rb', line 676

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



684
685
686
687
688
689
 
# File 'lib/sailthru.rb', line 684

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



660
661
662
663
664
665
666
667
668
669
670
671
 
# File 'lib/sailthru.rb', line 660

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



699
700
701
702
703
 
# File 'lib/sailthru.rb', line 699

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



692
693
694
695
696
 
# File 'lib/sailthru.rb', line 692

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



625
626
627
628
629
630
631
632
633
634
 
# File 'lib/sailthru.rb', line 625

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.



594
595
596
597
598
 
# File 'lib/sailthru.rb', line 594

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



733
734
735
736
737
 
# File 'lib/sailthru.rb', line 733

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



648
649
650
 
# File 'lib/sailthru.rb', line 648

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