sailthru 1.0.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+sailthru-*.gem
+github-test.rb

data/README.txt

@@ -0,0 +1,27 @@
+= sailthru
+
+== DESCRIPTION:
+
+Sailthru Triggermail Client, with some added bonus features and simpler integration with your Rails stack, including YML config for keys and mailing list name.
+
+== INSTALLATION:
+
+ $ gem install sailthru
+
+== USAGE:
+
+= Include in your app.
+
+  require 'sailthru/client'
+
+= Set your configuration in RAILS_ROOT/config/sailthru.yml.
+
+  api_key: YOUR_API_KEY
+  secret: YOUR_SECRET
+  api_uri: http://api.sailthru.com
+  mailing_list_key: mailing_list
+
+= Make calls to Sailthru as you would with the normal triggermail client:
+
+  client = Sailthru::Client.new
+  client.send(...)

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/sailthru/client.rb

@@ -0,0 +1,94 @@
+require 'sailthru/triggermail_client'
+
+module Sailthru
+  class Client
+    def initialize
+      @config = YAML.load(File.read(Rails.root + 'config' + 'sailthru.yml'))
+      @client = Sailthru::TriggermailClient.new(
+        @config['api_key'],
+        @config['secret'],
+        @config['api_uri'] || 'http://api.sailthru.com'
+      )
+     rescue Exception => ex
+      raise Exception.new(
+        "Please create a sailthru.yml file in your root config directory, containing api_key, secret, optional api_uri and optional mailing_list_key"
+      )
+    end
+
+    # Additional Helper Methods
+
+    def toggle_email_in_mailing_list(email, wants_email, vars={})
+      if !email.blank?
+        wants_email ? add_to_mailing_list(email, vars) : remove_from_mailing_list(email, vars)
+      end
+    rescue Exception => e
+      puts "EXCEPTION from Sailthru:   #{e}"
+    end
+
+    def add_to_mailing_list(email, vars)
+      return @client.set_email(email, normalize_vars(vars), {mailing_list_key => 1}, {})
+    end
+
+    def remove_from_mailing_list(email, vars)
+      return @client.set_email(email, normalize_vars(vars), {mailing_list_key => 0}, {})
+    end
+
+    # Sailthru Triggermail Client passthru methods.
+
+    def send(template_name, email, vars, options = {}, schedule_time = nil)
+      @client.send(template_name, email, vars, options, schedule_time)
+    end
+
+    def get_send(send_id)
+      @client.get_send(send_id)
+    end
+
+    def schedule_blast(name, list, schedule_time, from_name, from_email, subject, content_html, content_text, options)
+      @client.schedule_blast(name, list, schedule_time, from_name, from_email, subject, content_html, content_text, options)
+    end
+
+    def get_blast(blast_id)
+      @client.get_blast(blast_id)
+    end
+
+    def get_email(email)
+      @client.get_email(email)
+    end
+
+    def set_email(email, vars = {}, lists = {}, templates = {})
+      @client.set_email(email, vars, lists, templates)
+    end
+
+    def import_contacts(email, password, with_names = false)
+      @client.import_contacts(email, password, with_names)
+    end
+
+    def get_template(template_name)
+      @client.get_template(template_name)
+    end
+
+    def save_template(template_name, template_fields)
+      @client.save_template(template_name, template_fields)
+    end
+
+    def receive_verify_post(params, request)
+      @client.receive_verify_post(params, request)
+    end
+
+    protected
+    def normalize_vars(vars)
+      result = {:first_name => "", :last_name => ""}
+      result[:first_name] = vars[:first_name] if vars_has_this?(vars, :first_name)
+      result[:last_name]  = vars[:last_name]  if vars_has_this?(vars, :last_name)
+      result
+    end
+
+    def vars_has_this?(vars, key)
+      return vars.has_key?(key) && !vars[key].blank?
+    end
+
+    def mailing_list_key
+      @config['mailing_list_key'] || 'main_list'
+    end
+  end
+end

data/lib/sailthru/triggermail_client.rb

@@ -0,0 +1,351 @@
+################################################################################
+# Triggermail API Ruby Client
+################################################################################
+#
+# A simple client library to remotely access the Triggermail REST API.
+#
+################################################################################
+#
+# Copyright (c) 2007 Sailthru, Inc.
+# All rights reserved.
+#
+# Special thanks to the iminlikewithyou.com team for the development
+# of this library.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+################################################################################
+ 
+require 'net/http'
+require 'uri'
+require 'rubygems'
+require 'json'
+require 'md5'
+
+module Sailthru
+
+  class TriggermailClientException < Exception
+  end
+
+  class TriggermailClient
+    attr_accessor :api_uri, :api_key, :secret, :version, :last_request
+  
+    VERSION = '1.0'
+
+    # params:
+    #   api_key, String
+    #   secret, String
+    #   api_uri, String
+    # 
+    # Instantiate a new client; constructor optionally takes overrides for key/secret/uri.
+    def initialize(api_key, secret, api_uri)
+      @api_key = api_key
+      @secret  = secret
+      @api_uri = api_uri
+    end
+  
+    # 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, String (see schedule_blast schedule_time in API docs)
+    # returns:
+    #   Hash, response data from server
+    def send(template_name, email, vars, options = {}, schedule_time = nil)
+      post = {}
+      post[:template] = template_name
+      post[:email] = email
+      post[:vars] = vars
+      post[:options] = options
+      post[:schedule_time] = schedule_time if schedule_time
+      result = self.api_post(:send, post)
+    end
+
+  
+    # params:
+    #   send_id, Fixnum
+    # returns:
+    #   Hash, response data from server
+    # 
+    # Get the status of a send.
+    def get_send(send_id)
+      self.api_get(:send, {:send_id => send_id.to_s})      
+    end
+  
+    # 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
+    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
+      self.api_post(:blast, post)
+    end
+  
+  
+    # params:
+    #   blast_id, Fixnum
+    # returns:
+    #   Hash, response data from server
+    #
+    # Get information on a previously scheduled email blast
+    def get_blast(blast_id)
+      self.api_get(:blast, {:blast_id => blast_id.to_s})
+    end
+  
+    # params:
+    #   email, String
+    # returns:
+    #   Hash, response data from server
+    # 
+    # Return information about an email address, including replacement vars and lists.
+    def get_email(email)
+      self.api_get(:email, {:email => email})
+    end
+  
+    # params:
+    #   email, String
+    #   vars, Hash
+    #   lists, Hash mapping list name => 1 for subscribed, 0 for unsubscribed
+    # returns:
+    #   Hash, response data from server
+    # 
+    # Set replacement vars and/or list subscriptions for an email address.
+    def set_email(email, vars = {}, lists = {}, templates = {})
+      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
+  
+    # 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:
+    #   Hash of response data.
+    # 
+    # Get a template.
+    def get_template(template_name)
+      self.api_get(:template, {:template => template_name})
+    end
+  
+  
+    # params:
+    #   template_name, String
+    #   template_fields, Hash
+    # returns:
+    #   Hash containg response from the server.
+    # 
+    # Save a template.
+    def save_template(template_name, template_fields)
+      data = template_fields
+      data[:template] = template_name
+      self.api_post(:template, data)
+    end
+  
+  
+    # params:
+    #   params, Hash
+    #   request, String
+    # returns:
+    #   TrueClass or FalseClass, Returns true if the incoming request is an authenticated verify post.
+    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[:sig]
+        params.delete(:sig)
+        return false unless sig == TriggermailClient.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
+  
+  
+    # Perform API GET request
+    def api_get(action, data)
+      api_request(action, data, 'GET')
+    end
+  
+    # Perform API POST request
+    def api_post(action, data)
+      api_request(action, data, 'POST')
+    end
+  
+    # params:
+    #   action, String
+    #   data, Hash
+    #   request, String "GET" or "POST"
+    # returns:
+    #   Hash
+    #   
+    # Perform an API request, using the shared-secret auth hash.
+    #   
+    def api_request(action, data, request_type)
+      data[:api_key] = @api_key
+      data[:format] ||= 'json'
+      data[:sig] = Sailthru::TriggermailClient.get_signature_hash(data, @secret)
+      _result = self.http_request("#{@api_uri}/#{action}", data, request_type)
+    
+    
+      # NOTE: don't do the unserialize here
+      unserialized = JSON.parse(_result)
+      return unserialized ? unserialized : _result
+    end
+  
+  
+    # params:
+    #   uri, String
+    #   data, Hash
+    #   method, String "GET" or "POST"
+    # returns:
+    #   String, body of response
+    def http_request(uri, data, method = 'POST')
+      data = flatten_nested_hash(data, false)
+      # puts data.inspect
+      if method == 'POST'
+        post_data = data
+      else
+        uri += "?" + data.map{ |key, value| "#{key}=#{value}" }.join("&")
+      end
+    
+      req = nil
+      headers = {"User-Agent" => "Triggermail API Ruby Client #{VERSION}"}
+    
+      _uri  = URI.parse(uri)
+      if method == 'POST'
+        req = Net::HTTP::Post.new(_uri.path, headers)
+        req.set_form_data(data)
+      else
+        req = Net::HTTP::Get.new("#{_uri.path}?#{_uri.query}", headers)
+      end
+    
+      @last_request = req
+      begin
+        response = Net::HTTP.start(_uri.host, _uri.port) {|http|
+          http.request(req)
+        }
+      rescue Exception => e
+        raise Sailthru::TriggermailClientException.new("Unable to open stream: #{_uri.to_s}");
+      end
+    
+      if response.body
+        return response.body
+      else
+        raise Sailthru::TriggermailClientException.new("No response received from stream: #{_uri.to_s}")
+      end
+    
+    end
+  
+    # Flatten nested hash for GET / POST request.
+    def flatten_nested_hash(hash, brackets = true)
+      f = {}
+      hash.each do |key, value|
+        _key = brackets ? "[#{key}]" : key.to_s
+        if value.class == Hash
+          flatten_nested_hash(value).each do |k, v|
+            f["#{_key}#{k}"] = v
+          end
+        else
+          f[_key] = value
+        end
+      end
+      return f
+    end
+
+    # params:
+    #   params, Hash
+    # returns:
+    #   Array, values of each item in the Hash (and nested hashes)
+    #
+    # Extracts the values of a set of parameters, recursing into nested assoc arrays.
+    def self.extract_param_values(params)
+      values = []
+      params.each do |k, v|
+        # puts "k,v: #{k}, #{v}"
+        if v.class == Hash
+          values.concat Sailthru::TriggermailClient.extract_param_values(v)
+        else
+          values.push v
+        end
+      end
+      return values
+    end
+  
+  
+    # params:
+    #   params, Hash
+    #   secret, String
+    # returns:
+    #   String, an MD5 hash of the secret + sorted list of parameter values for an API call.
+    def self.get_signature_hash(params, secret)
+      string = secret + self.extract_param_values(params).sort_by{|x| x.to_s}.join("")
+      MD5.md5(string) # debuggin
+    end
+  
+  end
+end

data/sailthru.gemspec

@@ -0,0 +1,36 @@
+Gem::Specification.new do |s|
+  s.name = %q{sailthru}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Ian Enders"]
+  s.date = %q{2010-04-02}
+  s.description = %q{Sailthru triggermail client.}
+  s.email = %q{ian.enders@gmail.com}
+  s.extra_rdoc_files = [
+    "README.txt"
+  ]
+  s.files = [
+    ".gitignore",
+     "README.txt",
+     "VERSION",
+     "lib/sailthru/client.rb",
+     "lib/sailthru/triggermail_client.rb",
+     "sailthru.gemspec"
+  ]
+  s.homepage = %q{http://github.com/ienders/sailthru}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Gemified Sailthru Client Library}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: sailthru
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Ian Enders
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-02 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Sailthru triggermail client.
+email: ian.enders@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.txt
+files: 
+- .gitignore
+- README.txt
+- VERSION
+- lib/sailthru/client.rb
+- lib/sailthru/triggermail_client.rb
+- sailthru.gemspec
+has_rdoc: true
+homepage: http://github.com/ienders/sailthru
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Gemified Sailthru Client Library
+test_files: []
+