sailthru-client 1.13 → 1.14

data/README.md

@@ -24,202 +24,214 @@ It can make requests to following [API calls](http://docs.sailthru.com/api):
 
 Examples
 --------
-	require 'sailthru' #if using as gem
 
- 	api_key = "api_key";
-    api_secret = 'secret';
-    api_url = "https://api.sailthru.com";
- 	sailthru = Sailthru::SailthruClient.new(api_key, api_secret, api_url)
+``` ruby
+require 'sailthru' #if using as gem
 
-### [send](http://docs.sailthru.com/api/send)
+api_key = "api_key";
+api_secret = 'secret';
+api_url = "https://api.sailthru.com";
+sailthru = Sailthru::SailthruClient.new(api_key, api_secret, api_url)
+```
 
-    #send
-    template_name = 'my-template'
-    email = 'praj@sailthru.com'
-    vars = {'name' => 'Prajwal Tuladhar', "myvar" => [1111,2,3]}
-    options = {'test' => 1}
-    schedule_time = '+3 hours'
-    response = sailthru.send(template_name, email, vars, options, schedule_time)
-
-    #get send
-    send_id = '6363'
-    response = sailthru.get_send(send_id)
-
-    #cancel send
-    send_id = '236236sbs'
-    response = sailthru.cancel_send(send_id)
-
-    #multi send
-    template_name = 'my-template'
-    emails = 'praj@sailthru.com, ian@sailthru.com'
-    vars = {'name' => 'Prajwal Tuladhar', "myvar" => [1111,2,3]}
-    options = {'test' => 1}
-    response = sailthru.multi_send(template_name, emails, vars, options)
+### [send](http://docs.sailthru.com/api/send)
+``` ruby
+#send
+template_name = 'my-template'
+email = 'praj@sailthru.com'
+vars = {'name' => 'Prajwal Tuladhar', "myvar" => [1111,2,3]}
+options = {'test' => 1}
+schedule_time = '+3 hours'
+response = sailthru.send(template_name, email, vars, options, schedule_time)
+
+#get send
+send_id = '6363'
+response = sailthru.get_send(send_id)
+
+#cancel send
+send_id = '236236sbs'
+response = sailthru.cancel_send(send_id)
+
+#multi send
+template_name = 'my-template'
+emails = 'praj@sailthru.com, ian@sailthru.com'
+vars = {'name' => 'Prajwal Tuladhar', "myvar" => [1111,2,3]}
+options = {'test' => 1}
+response = sailthru.multi_send(template_name, emails, vars, options)
+```
 
 ### [email](http://docs.sailthru.com/api/email)
+``` ruby
+#get email
+email = 'praj@sailthru.com'
+response = sailthru.get_email(email)
 
-    #get email
-    email = 'praj@sailthru.com'
-    response = sailthru.get_email(email)
-
-    #set email
-    email = 'praj@sailthru.com'
-    response = sailthru.set_email(email)
+#set email
+email = 'praj@sailthru.com'
+response = sailthru.set_email(email)
+```
 
 ### [blast](http://docs.sailthru.com/api/blast)
-
-	#schedule blast
-	blast_name = 'My blast name'
-	template = 'my-template'
-	schedule_time = '+5 hours'
-	from_name = 'prajwal tuladhar'
-	from_email = 'praj@sailthru.com'
-	subject = 'What's up!'
-	html = '<p>Lorem ispum is great</p>'
-	text = 'Lorem ispum is great'
-	response = sailthru.schedule_blast(blast_name, template, schedule_time, from_name, from_email, subject, html, text)
-
-    #schedule blast from template
-    template = 'default'
-    list = 'default'
-    schedule_time = 'now'
-    response = sailthru.schedule_blast_from_template(template, list, schedule_time)
-
-    #schedule blast from previous blast
-    blast_id = 67535
-    schedule_time ='now'
-    vars = {
-        'my_var' => '3y6366546363',
-        'my_var2' => [7,8,9],
-        'my_var3' => {'president' => 'obama', 'nested' => {'vp' => 'palin'}}
-    }
-    options = {:vars => vars}
-    response = sailthru.schedule_blast_from_blast(blast_id, "now", options)
-
-	#update blast
-	blast_id = 7886
-	name = 'prajwal tuladhar 64'
-	response = sailthru.update_blast(blast_id, name = name)
-
-	#get blast info
-	blast_id = 7886
-	response = sailthru.get_blast(blast_id)
-
-	#cancel blast
-	blast_id = 7886
-	response = sailthru.cancel_blast(blast_id)
-
-	#delete blast
-	blast_id = 7886
-	response = sailthru.delete_blast(blast_id)
-
+``` ruby
+#schedule blast
+blast_name = 'My blast name'
+template = 'my-template'
+schedule_time = '+5 hours'
+from_name = 'prajwal tuladhar'
+from_email = 'praj@sailthru.com'
+subject = "What's up!"
+html = '<p>Lorem ispum is great</p>'
+text = 'Lorem ispum is great'
+response = sailthru.schedule_blast(blast_name, template, schedule_time, from_name, from_email, subject, html, text)
+
+#schedule blast from template
+template = 'default'
+list = 'default'
+schedule_time = 'now'
+response = sailthru.schedule_blast_from_template(template, list, schedule_time)
+
+#schedule blast from previous blast
+blast_id = 67535
+schedule_time ='now'
+vars = {
+'my_var' => '3y6366546363',
+'my_var2' => [7,8,9],
+'my_var3' => {'president' => 'obama', 'nested' => {'vp' => 'palin'}}
+}
+options = {:vars => vars}
+response = sailthru.schedule_blast_from_blast(blast_id, "now", options)
+
+#update blast
+blast_id = 7886
+name = 'prajwal tuladhar 64'
+response = sailthru.update_blast(blast_id, name = name)
+
+#get blast info
+blast_id = 7886
+response = sailthru.get_blast(blast_id)
+
+#cancel blast
+blast_id = 7886
+response = sailthru.cancel_blast(blast_id)
+
+#delete blast
+blast_id = 7886
+response = sailthru.delete_blast(blast_id)
+```
 
 ### [list](http://docs.sailthru.com/api/list)
 
-	#save list
-	list_name = 'my-list'
-	emails = ['praj@sailthru.com', 'ian@sailthru.com']
-	response = sailthru.save_list(list_name, emails)
+Get information about a list, or create a list.
 
-	#download /get list
-	list_name = 'my-list'
-	format = 'json'
-	response = sailthru.get_list(list_name, format)
+``` ruby
+#save list
+list_name = 'my-list'
+options = {
+    'primary' => 1,
+}
+response = sailthru.save_list(list_name, options)
 
-	#delete list
-	list_name = 'my-list'
-	response = sailthru.delete_list(list_name)
+#get list information
+list_name = 'my-list'
+response = sailthru.get_list(list_name)
 
-### [contacts](http://docs.sailthru.com/api/contacts)
+#get all lists
+response = sailthru.get_lists()
 
-	#import contacts
-	email = 'infynyxx@aol.com'
-	password = 'my super awesome password'
-	with_names = true
-	response = sailthru.import_contacts(email, password, with_names)
+#delete list
+list_name = 'my-list'
+response = sailthru.delete_list(list_name)
+```
 
 ### [content](http://docs.sailthru.com/api/content)
-
-	#push content
-	title = 'hello world'
-    url = 'http://example.com/product-url'
-    response = sailthru.push_content(title, url)
-
-    #another push content exammple
-    title = 'hello world'
-    url = 'http://example.com/product-url'
-    tags = ["blue", "red", "green"]
-    vars = {'vars' => ['price' => 17299]}
-    date = nil
-	response = sailthru.push_content(title, url, date, tags = tags, vars = vars)
+``` ruby
+#push content
+title = 'hello world'
+url = 'http://example.com/product-url'
+response = sailthru.push_content(title, url)
+
+#another push content exammple
+title = 'hello world'
+url = 'http://example.com/product-url'
+tags = ["blue", "red", "green"]
+vars = {'vars' => ['price' => 17299]}
+date = nil
+response = sailthru.push_content(title, url, date, tags = tags, vars = vars)
+```
 
 ### [alert](http://docs.sailthru.com/api/alert)
-
-	#get alert info
-	email = 'praj@sailthru.com'
-	response = sailthru.get_alert(email)
-
-	#save alert
-	email = 'praj@sailthru.com'
-	type = 'daily'
-	_when = '+5 hours'
-	extras = {'tags' => ['red', 'blue'], 'match' => {'type' => 'yellow'}}
-	response = sailthru.save_alert(email, type, _when, extras)
-
-	#delete alert
-	email = 'praj@sailthru.com'
-	alert_id = '4d4b17a36763d930210007ba'
-	response = sailthru.delete_alert(email, alert_id)
+``` ruby
+#get alert info
+email = 'praj@sailthru.com'
+response = sailthru.get_alert(email)
+
+#save alert
+email = 'praj@sailthru.com'
+type = 'daily'
+_when = '+5 hours'
+extras = {'tags' => ['red', 'blue'], 'match' => {'type' => 'yellow'}}
+response = sailthru.save_alert(email, type, _when, extras)
+
+#delete alert
+email = 'praj@sailthru.com'
+alert_id = '4d4b17a36763d930210007ba'
+response = sailthru.delete_alert(email, alert_id)
+``` ruby
 
 ### [purchase](http://docs.sailthru.com/api/purchase)
-
-	#purchase API call
-	email = 'praj@sailthru.com'
-	items = [{"price"=>1099, "qty"=>22, "title"=>"High-Impact Water Bottle", "url"=>"http://example.com/234/high-impact-water-bottle", "id"=>"234"}, {"price"=>500, "qty"=>2, "title"=>"Lorem Ispum", "url"=>"http://example.com/2304/lorem-ispum", "id"=>"2304"}]
-	response = sailthru.purchase(email, items)
+``` ruby
+#purchase API call
+email = 'praj@sailthru.com'
+items = [{"price"=>1099, "qty"=>22, "title"=>"High-Impact Water Bottle", "url"=>"http://example.com/234/high-impact-water-bottle", "id"=>"234"}, {"price"=>500, "qty"=>2, "title"=>"Lorem Ispum", "url"=>"http://example.com/2304/lorem-ispum", "id"=>"2304"}]
+response = sailthru.purchase(email, items)
+```
 
 ### [stats](http://docs.sailthru.com/api/stats)
+``` ruby
+#stats list
+response = sailthru.stats_list()
 
-	#stats list
-	response = sailthru.stats_list()
-
-	#stats blast
-	blast_id = 42382
-	response = sailthru.stats_blast(blast_id)
+#stats blast
+blast_id = 42382
+response = sailthru.stats_blast(blast_id)
+```
 
 ### [horizon](http://docs.sailthru.com/api/horizon)
+``` ruby
+#get horizon user info
+email = 'praj@sailthru.com'
+response = sailthru.get_horizon(email)
 
-	#get horizon user info
-	email = 'praj@sailthru.com'
-	response = sailthru.get_horizon(email)
+#set horizon data
+email = 'praj@sailthru.com'
+tags = ['red', 'blue']
+response = sailthru.set_horizon(email, tags)
+```
 
-	#set horizon data
-	email = 'praj@sailthru.com'
-	tags = ['red', 'blue']
-	response = sailthru.set_horizon(email, tags)
 
 ### [job] (http://docs.sailthru.com/api/job)
-
-    # get status of job id
-    job_id = '4dd58f036803fa3b5500000b'
-    response = sailthru.get_job_status(job_id)
-
-    # process import job for email string
-    list = 'test-list'
-    emails = 'a@a.com,b@b.com'
-    response = sailthru.process_import_job(list, emails)
-
-    # process import job from CSV or text file
-    list = 'test-list'
-    source_file = '/home/praj/Desktop/emails.txt'
-    response = sailthru.process_import_job(list, source_file)
-
-    # process snapshot job
-    query = {}
-    report_email = 'praj@sailthru.com'
-    postback_url = 'http://example.com/reports/snapshot_postback'
-    response = sailthru.process_snapshot_job(query)
-
-    # process export list job
-    list = 'test-list'
-    response = sailthru.process_export_list_job(list)
+``` ruby
+# get status of job id
+job_id = '4dd58f036803fa3b5500000b'
+response = sailthru.get_job_status(job_id)
+
+# process import job for email string
+list = 'test-list'
+emails = 'a@a.com,b@b.com'
+response = sailthru.process_import_job(list, emails)
+
+# process import job from CSV or text file
+list = 'test-list'
+source_file = '/home/praj/Desktop/emails.txt'
+response = sailthru.process_import_job(list, source_file)
+
+# process snapshot job
+query = {}
+report_email = 'praj@sailthru.com'
+postback_url = 'http://example.com/reports/snapshot_postback'
+response = sailthru.process_snapshot_job(query)
+
+# process export list job
+list = 'test-list'
+response = sailthru.process_export_list_job(list)
+```

data/lib/sailthru.rb

@@ -9,7 +9,7 @@ require 'net/http/post/multipart'
 
 module Sailthru
 
-  Version = VERSION = '1.13'
+  Version = VERSION = '1.14'
 
   class SailthruClientException < Exception
   end
@@ -87,7 +87,7 @@ module Sailthru
       end
       return f
     end
-    
+
   end
 
   class SailthruClient
@@ -101,11 +101,13 @@ module Sailthru
     #   secret, String
     #   api_uri, String
     #
-    # Instantiate a new client; constructor optionally takes overrides for key/secret/uri.
-    def initialize(api_key, secret, api_uri = nil)
+    # Instantiate a new client; constructor optionally takes overrides for key/secret/uri and proxy server settings.
+    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
 
@@ -200,7 +202,7 @@ module Sailthru
       post[:schedule_time] = schedule_time
       api_post(:blast, post)
     end
-    
+
 
     # params
     #   blast_id, Fixnum | String
@@ -298,22 +300,6 @@ module Sailthru
       self.api_post(:email, data)
     end
 
-    # params:
-    #  email, String
-    #  password, String
-    #  with_names, Boolean
-    # returns:
-    #  Hash, response data from server
-    #
-    # Fetch email contacts from an address book at one of the major email providers (aol/gmail/hotmail/yahoo)
-    # Use the with_names parameter if you want to fetch the contact names as well as emails
-    def import_contacts(email, password, with_names = false)
-      data = { :email => email, :password => password }
-      data[:names] = 1 if with_names
-      self.api_post(:contacts, data)
-    end
-
-
     # params:
     #   template_name, String
     # returns:
@@ -337,7 +323,7 @@ module Sailthru
       data[:template] = template_name
       self.api_post(:template, data)
     end
-    
+
     # params:
     #   template_name, String
     # returns:
@@ -490,27 +476,29 @@ module Sailthru
 
     # params
     #   list, String
-    #   format, String
     #
-    # Download a list. Obviously, this can potentially be a very large download.
-    # 'txt' is default format since, its more compact as compare to others
-    def get_list(list, format = 'txt')
-      return api_get(:list, {:list => list, :format => format})
+    # Get information about a list. 
+    def get_list(list)
+      return api_get(:list, {:list => list})
     end
 
+    # params
+    #
+    # Get information about all lists 
+    def get_lists()
+        return api_get(:list, {})
+    end
 
     # params
     #   list, String
-    #   emails, String | Array
-    # Upload a list. The list import job is queued and will happen shortly after the API request.
-    def save_list(list, emails)
-      data = {}
+    #   options, Hash
+    # Create a list, or update a list.
+    def save_list(list, options = {})
+      data = options
       data[:list] = list
-      data[:emails] = (emails.class == Array) ? emails.join(',') : emails
      return api_post(:list, data)
     end
 
-
     # params
     #   list, String
     #
@@ -590,7 +578,7 @@ module Sailthru
     def stats(data)
       api_get(:stats, data)
     end
-    
+
     # params
     #   job, String
     #   options, hash
@@ -605,21 +593,23 @@ module Sailthru
       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
     
+    # params
+    #   emails, String | Array
     # implementation for import_job  
     def process_import_job(list, emails, report_email = nil, postback_url = nil)
       data = {}
       data['list'] = list
-      data['emails'] = emails
+      data['emails'] = Array(emails).join(',')
       process_job(:import, data, report_email, postback_url)
     end
-    
+
     # implementation for import job using file upload
     def process_import_job_from_file(list, file_path, report_email = nil, postback_url = nil)
       data = {}
@@ -627,26 +617,26 @@ module Sailthru
       data['file'] = file_path
       process_job(:import, data, report_email, postback_url, 'file')
     end
-    
+
     # implementation for snapshot job
     def process_snapshot_job(query = {}, report_email = nil, postback_url = nil)
       data = {}
       data['query'] = query
       process_job(:snapshot, data, report_email, postback_url)
     end
-    
+
     # implementation for export list job
     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
-    
+
     # get status of a job
     def get_job_status(job_id)
       api_get(:job, {'job_id' => job_id})
     end
-    
+
 
     # Perform API GET request
     def api_get(action, data)
@@ -662,7 +652,7 @@ module Sailthru
     def api_delete(action, data)
       api_request(action, data, 'DELETE')
     end
-    
+
     protected
 
     # params:
@@ -687,10 +677,10 @@ module Sailthru
         data[:format] ||= 'json'
         data[:sig] = get_signature_hash(data, @secret)
       end
-      
+
       if (!binary_key.nil?)
         data[binary_key] = binary_key_data
-      end 
+      end
       _result = self.http_request("#{@api_uri}/#{action}", data, request_type, binary_key)
 
       # NOTE: don't do the unserialize here
@@ -714,18 +704,18 @@ module Sailthru
     #   String, body of response
     def http_request(uri, data, method = 'POST', binary_key = nil)
       data = flatten_nested_hash(data, false)
-      
+
       if method != 'POST'
         uri += "?" + data.map{ |key, value| "#{CGI::escape(key.to_s)}=#{CGI::escape(value.to_s)}" }.join("&")
       end
-      
+
       req = nil
       headers = {"User-Agent" => "Sailthru API Ruby Client #{VERSION}"}
 
       _uri  = URI.parse(uri)
-      
+
       if method == 'POST'
-        if (!binary_key.nil?) 
+        if (!binary_key.nil?)
           binary_data = data[binary_key]
           data[binary_key] = UploadIO.new(File.open(binary_data), "text/plain")
           req = Net::HTTP::Post::Multipart.new(_uri.path, data)
@@ -733,7 +723,7 @@ module Sailthru
           req = Net::HTTP::Post.new(_uri.path, headers)
           req.set_form_data(data)
         end
-        
+
       else
         request_uri = "#{_uri.path}?#{_uri.query}"
         if method == 'DELETE'
@@ -744,8 +734,8 @@ module Sailthru
       end
 
       begin
-        http = Net::HTTP.new(_uri.host, _uri.port)
-        
+        http = Net::HTTP::Proxy(@proxy_host, @proxy_port).new(_uri.host, _uri.port)
+
         if _uri.scheme == 'https'
             http.use_ssl = true
             http.verify_mode = OpenSSL::SSL::VERIFY_NONE if @verify_ssl != true  # some openSSL client doesn't work without doing this
@@ -754,18 +744,18 @@ module Sailthru
         response = http.start {
             http.request(req)
         }
-        
+
       rescue Exception => e
         raise SailthruClientException.new("Unable to open stream: #{_uri}\n#{e}");
       end
-      
+
       if response.body
         return response.body
       else
         raise SailthruClientException.new("No response received from stream: #{_uri}")
       end
     end
-    
+
     def http_multipart_request(uri, data)
       req = Net::HTTP::Post::Multipart.new url.path,
         "file" => UploadIO.new(data['file'], "application/octet-stream")

metadata

@@ -1,12 +1,11 @@
 --- !ruby/object:Gem::Specification 
 name: sailthru-client
 version: !ruby/object:Gem::Version 
-  hash: 21
-  prerelease: 
+  prerelease: false
   segments: 
   - 1
-  - 13
-  version: "1.13"
+  - 14
+  version: "1.14"
 platform: ruby
 authors: 
 - Prajwal Tuladhar
@@ -14,17 +13,16 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-08 00:00:00 Z
+date: 2012-02-10 00:00:00 -05:00
+default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: json
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -34,11 +32,9 @@ dependencies:
   name: multipart-post
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -48,11 +44,9 @@ dependencies:
   name: fakeweb
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -62,11 +56,9 @@ dependencies:
   name: shoulda
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -83,6 +75,7 @@ extra_rdoc_files:
 files: 
 - README.md
 - lib/sailthru.rb
+has_rdoc: true
 homepage: http://docs.sailthru.com
 licenses: []
 
@@ -93,27 +86,23 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.8
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: A simple client library to remotely access the Sailthru REST API.