messagebus_ruby_api 0.1.1 → 0.4.0

data/.rvmrc

@@ -1 +1 @@
-rvm use ruby-1.9.2-p180@messagebus_ruby_api --create
+rvm use ruby-1.9.2-p180-patched@messagebus_ruby_api --create

data/Gemfile

@@ -1,5 +1,7 @@
 source "http://rubygems.org"
 
+gem 'activesupport'
+
 group :test, :development do
   gem 'rspec', '2.5.0'
   gem 'rr', '1.0.2'

data/README.rdoc

@@ -15,39 +15,75 @@ Start by requiring MessagebusRubyApi:
 
   client = MessagebusRubyApi::Client.new("<INSERT_YOUR_API_KEY>")
 
-
-=== Required Parameters
-
-    required_params = {
-      :subject => "e-mail subject",
-      :body => "This is the email body",
-      :fromEmail => "from@example.com",
-      :toEmail => "to@example.com"
-    }
-
-=== Optional Parameters
-
-    optional_params = {
-      :fromName => "From Name",
-      :toName => "To Name",
-      :tag => "tags separated by spaces"
+=== Setting common fields for your emails
+  client.common_info={:fromEmail="from@example.com"}
+
+==== When not using an API template
+===== Required common_info field
+  :fromEmail
+===== Optional common_info fields
+  :fromName, :replayTo, :tags
+==== When using an API template
+===== Required common_info field
+  :templateKey
+===== No Optional Fields
+
+=== Adding messages to the send buffer
+  result=client.add_message({:toEmail=>"to@example.com"})
+
+  If you get a result >0 you get back the number of messages waiting to get sent
+  If you get a result = 0 that means the buffer was flushed and you can get results from client.return_status
+  Note: you should read from client.return_status before adding more messages since client.return_status will get cleared during the next auto-flush
+
+==== When not using an API template
+===== Required message fields
+  :toEmail, :subject, :plaintextBody or :htmlBody
+===== Optional message fields
+  :tag, :toName,
+==== When using an API template
+===== Required common_info field
+  :mergeFields={"%EMAIL"=>"to@example.com", "%KEY1%"="testing"}
+
+  Note: the merge fields entries chould contain the keys used in the template, but only the %EMAIL% is required
+
+===== No Optional Fields
+
+=== Flushing the send buffer
+  client.flush
+
+  Note: Flushing returns the status of the messages that were sent (see bellow). It also clears old values to client.return_status
+
+  Warning: You always need to flush your buffer when you are done adding messages to be sent or if you want to send messages with a different common_info (failure to do so could result in unsent messages getting lost or old messages getting sent with your new common_info
+
+=== Checking on message ids sent
+  client.return_status
+
+  Status messages will be in the following form:
+
+  {
+      "statusMessage" => "OK",
+      "successCount" => 2,
+      "failureCount" => 0,
+      "results" => [
+            {
+          "status" => 200,
+          "messageId" => "e460d7f0-908e-012e-80b4-58b035f30fd1"
+            },
+            {
+          "status" => 200,
+          "messageId" => "e460d7f0-908e-012e-80b4-58b035f30fd2"
+            }
+      ]
     }
 
-=== Sending an e-mail with the client
+    If there are failures you will get 400 or 500 status codes as well as error messages
 
-    @params = {
-      :subject => "e-mail subject",
-      :body => "This is the email body",
-      :fromEmail => "from@example.com",
-      :toEmail => "to@example.com"
-    }
+== Older Versions
 
-    response = client.send_email(@params)
-    puts "API call failed" unless response.body =~ /^OK:(.*)$/
+  If you are using the old api with the text OK:<UUID> responses, please be sure to get the 'v1' branch
 
+  If you are using the old api with the 'body' parameter (instead of the new 'plaintextBody' and 'htmlBody' parameters), please be sure to get the 'v0' branch
 
 == More info
 
 Contact MessageBus if you have questions or problems (https://www.messagebus.com/contact)
-
-

data/lib/messagebus_ruby_api/client.rb

@@ -3,69 +3,55 @@ module MessagebusRubyApi
 
   class Client
     attr_reader :api_key, :endpoint_url, :http
-
+    attr_reader :buffer, :return_status, :email_buffer_size
+    attr_writer :common_info
+    @empty_results=nil
+    
     def initialize(api_key, endpoint_url_string = DEFAULT_API_ENDPOINT_STRING)
       @api_key = verified_reasonable_api_key(api_key)
       @endpoint_url = URI.parse(endpoint_url_string)
-      @http = api_endpoint_http_connection(endpoint_url)
+      @endpoint_bulk_path = "/api/v2/emails/send"
+      @http = Net::HTTP.new(@endpoint_url.host, @endpoint_url.port)
       @http.use_ssl = true
+      @email_buffer_size=20
+      @buffer=[]
+      @empty_results= {
+        :statusMessage => "",
+        :successCount => 0,
+        :failureCount => 0,
+        :results => []
+      }
+      @return_status=@empty_results
+      @common_info={}
     end
 
-    def complete_url(options)
-      params_string = to_param(check_params(options))
-      url = "/send?operation=sendEmail&#{params_string}&apiKey=#{api_key}"
-      url
-    end
-
-    def send_email(options)
-      verify_required_params(options)
-      response = @http.start do |http|
-        request = api_request(options)
-        request.basic_auth(@credentials[:user], @credentials[:password]) if @credentials
-        http.request(request)
+    def add_message(email_options)
+      @buffer<<email_options
+      if (@buffer.size >= @email_buffer_size)
+        self.flush
+        return 0
+      else
+        return @buffer.size
       end
-      case response
-        when Net::HTTPSuccess
-          return response
-        when Net::HTTPClientError, Net::HTTPServerError
-          if (response.body && response.body.size > 0)
-            raise MessagebusRubyApi::RemoteServerError.new(response.body)
-          else
-            raise MessagebusRubyApi::RemoteServerError.new("ERR:Remote Server Returned: #{response.code.to_s}")
-          end
-        else
-          raise "Unexpected HTTP Response: #{response.class.name}"
-      end
-      raise "Could not determine response"
-    end
-
-    def check_params(params)
-      params[:plainText] = check_plain_text(params[:plainText]) unless params[:plainText].nil?
-      params[:priority] = check_priority(params[:priority]) unless params[:priority].nil?
-      params
     end
 
-    def to_param(params)
-      params.map { |name, val| [name.to_s, val] }.sort.map { |param_name, param_value| "#{CGI.escape(param_name)}=#{CGI.escape(param_value)}" }.join("&")
+    def flush
+      if (@buffer.size==0)
+        @return_status=@empty_results
+        return
+      end
+      @return_status=self.buffered_send(@buffer, @common_info)
+      @buffer.clear
+      @return_status
     end
 
     def basic_auth_credentials=(credentials)
       @credentials = credentials
     end
 
-    private
-
-    def api_request(options)
-      Net::HTTP::Post.new(complete_url(options)) #, {"User-Agent" => "messagebus.com Messagebus Ruby API v1"})
-    end    
-
-    def api_endpoint_http_connection(endpoint_url)
-      Net::HTTP.new(endpoint_url.host, endpoint_url.port)
-    end
 
-    def check_plain_text(plain_text)
-      raise APIParameterError.new(":plainText can only be true or false, not \"#{plain_text}\" of type #{plain_text.class}") unless [true, false].include?(plain_text)
-      plain_text ? "1" : "0"
+    def create_api_request(path)
+      Net::HTTP::Post.new(path) #, {"User-Agent" => "messagebus.com Messagebus Ruby API v2"})
     end
 
     def check_priority(priority)
@@ -78,11 +64,88 @@ module MessagebusRubyApi
       api_key
     end
 
-    def verify_required_params(params)
+    def validate(params)
       raise APIParameterError.new("toEmail") unless params[:toEmail]
       raise APIParameterError.new("fromEmail") unless params[:fromEmail]
       raise APIParameterError.new("subject") unless params[:subject]
-      raise APIParameterError.new("body") unless params[:body]
+      raise APIParameterError.new("plaintextBody or htmlBody") unless params[:plaintextBody] || params[:htmlBody]
+      params[:priority] = check_priority(params[:priority]) unless params[:priority].nil?
+    end
+
+    def buffered_send(message_list, common_options)
+      if (message_list.length==0)
+        return {
+          :statusMessage => "OK",
+          :successCount => 0,
+          :failureCount => 0}
+      end
+      response = @http.start do |http|
+        request = create_api_request(@endpoint_bulk_path)
+        request.basic_auth(@credentials[:user], @credentials[:password]) if @credentials
+        request.form_data={'json' => make_json_message_from_list(message_list, common_options)}
+        http.request(request)
+      end
+      case response
+        when Net::HTTPSuccess
+          begin
+
+            return JSON.parse(response.body, :symbolize_names => true)
+          rescue JSON::ParserError => e
+            raise MessagebusRubyApi::RemoteServerError.new("Remote server returned unrecognized response: #{e.message}")
+          end
+        when Net::HTTPClientError, Net::HTTPServerError
+          if (response.body && response.body.size > 0)
+            result = begin
+              JSON.parse(response.body, :symbolize_names => true)
+            rescue JSON::ParserError
+              nil
+            end
+            raise MessagebusRubyApi::RemoteServerError.new("Remote Server Returned: #{response.code.to_s}.  #{result[:statusMessage] if result}", result)
+          else
+            raise MessagebusRubyApi::RemoteServerError.new("Remote Server Returned: #{response.code.to_s}")
+          end
+        else
+          raise "Unexpected HTTP Response: #{response.class.name}"
+      end
+      raise "Could not determine response"
+    end
+
+    def make_json_message(options)
+      map={}
+      map["toEmail"]=options[:toEmail] if (options.has_key? :toEmail)
+      map["toName"]=options[:toName] if (options.has_key? :toName)
+      map["subject"]=options[:subject] if (options.has_key? :subject)
+      map["plaintextBody"]=options[:plaintextBody] if (options.has_key? :plaintextBody)
+      map["htmlBody"]=options[:htmlBody] if (options.has_key? :htmlBody)
+      map["fromName"]=options[:fromName] if (options.has_key? :fromName)
+      map["tag"]=options[:tag] if (options.has_key? :tag)
+      map["replyTo"]=options[:replyTo] if (options.has_key? :replyTo)
+      map["errorsTo"]=options[:errorsTo] if (options.has_key? :errorsTo)
+      map["unsubscribeEmail"]=options[:unsubscribeEmail] if (options.has_key? :unsubscribeEmail)
+      map["unsubscribeURL"]=options[:unsubscribeURL] if (options.has_key? :unsubscribeURL)
+      map["mergeFields"]=options[:mergeFields] if (options.has_key? :mergeFields)
+      map
+    end
+
+    def make_json_message_from_list(option_list, common_options)
+      message_list=[]
+      option_list.each do |list_item|
+        message_list<<make_json_message(list_item)
+      end
+      json = {
+        "apiKey" => @api_key,
+        "messageCount" => message_list.length,
+        "messages" => message_list
+      }
+      if (common_options!=nil)
+        json["fromEmail"]=common_options[:fromEmail] if (common_options.has_key? :fromEmail)
+        json["fromName"]=common_options[:fromName] if (common_options.has_key? :fromName)
+        json["replyTo"]=common_options[:replyTo] if (common_options.has_key? :replyTo)
+        json["tags"]=common_options[:tags] if (common_options.has_key? :tags)
+        json["templateKey"]=common_options[:templateKey] if (common_options.has_key? :templateKey)
+      end
+      
+      json.reject { |k, v| v == nil }.to_json
     end
   end
 end

data/lib/messagebus_ruby_api/errors.rb

@@ -10,8 +10,10 @@ module MessagebusRubyApi
   end
 
   class RemoteServerError < StandardError
-    def initialize(message)
-      super
+    attr_reader :result
+    def initialize(message, result={})
+      super(message)
+      @result = result
     end
   end
   

data/lib/messagebus_ruby_api/version.rb

@@ -1,3 +1,3 @@
 module MessagebusRubyApi
-  VERSION = "0.1.1"
+  VERSION = "0.4.0"
 end

data/spec/messagebus_ruby_api/client_spec.rb

@@ -3,178 +3,117 @@ require "#{dir}/../spec_helper"
 
 describe MessagebusRubyApi::Client do
   attr_reader :client, :api_key, :required_params
+
+  def create_success_result(num_result)
+    list=[]
+    num_result.times do
+      list << @success_message
+    end
+    success_result = {
+      "statusMessage" => "OK",
+      "successCount" => 1,
+      "failureCount" => 0,
+      "results" => list
+    }
+    success_result
+  end
+
   before do
     FakeWeb.allow_net_connect = false
 
     @api_key = "3"*32
     @client = MessagebusRubyApi::Client.new(api_key)
-    @required_params = {:toEmail => "bob@example.com", :fromEmail => "alice@example.com", :body => "a nice ocean", :subject => "test subject"}
-  end
-
-  it "requires an api key" do
-    expect do
-      MessagebusRubyApi::Client.new("3"*32)
-    end.should_not raise_error(MessagebusRubyApi::BadAPIKeyError)
-
-    expect do
-      MessagebusRubyApi::Client.new("foo")
-    end.should raise_error(MessagebusRubyApi::BadAPIKeyError)
-  end
-
-  it "knows its API key" do
-    client.api_key.should == api_key
+    @required_params = {:toEmail => "bob@example.com", :fromEmail => "alice@example.com", :plaintextBody => "a nice ocean", :subject => "test subject"}
+    @success_message={
+      "status" => 200,
+      "messageId" => "e460d7f0-908e-012e-80b4-58b035f30fd1"
+    }
+    @simple_success_result = create_success_result(1)
   end
 
-  it "defaults the endpoint URL if one is not supplied" do
-    @client.endpoint_url.host.should =~ /api\.messagebus\.com/
-  end
-
-  it "talks to the supplied endpoint url" do
-    another_client = MessagebusRubyApi::Client.new(api_key, "http://localhost:8080")
-    another_client.endpoint_url.host.should =~ /localhost/
-  end
-
-  describe "required parameters" do
-    it "works when the minimum params are sent" do
-      url_params = client.to_param(required_params)
-      FakeWeb.register_uri(:post, api_url_from_params(url_params), :body => "OK:OK")
+  describe "#bulk_send" do
+
+    before do
+      @common_options={:fromEmail => "bob@example.com"}
+    end
+
+    describe "#add_message" do
+      it "buffered send that adds to empty buffer" do
+        client.common_info=@common_options
+        client.buffer.size.should == 0
+        client.add_message(required_params)
+        client.buffer.size.should == 1
+      end
+      
+      it "buffered send that adds to a buffer and auto-flushes" do
+        FakeWeb.register_uri(:post, "https://api.messagebus.com/api/v2/emails/send", :body => create_success_result(client.email_buffer_size).to_json)
+        client.common_info=@common_options
+        client.return_status[:results].size.should == 0
+        (client.email_buffer_size-1).times do |idx|
+          client.add_message(required_params).should == idx+1
+          client.return_status[:results].size.should == 0
+        end
+        client.add_message(required_params).should == 0
+        client.return_status[:results].size.should == client.email_buffer_size
+      end
+    end
+
+    describe "#flush" do
+      it "flush called on empty buffer" do
+        client.common_info=@common_options
+        client.return_status[:results].size.should == 0
+        client.flush
+        client.return_status[:results].size.should == 0
+      end
+      it "flush called on filled buffer" do
+        FakeWeb.register_uri(:post, "https://api.messagebus.com/api/v2/emails/send", :body => create_success_result(10).to_json)
+        client.common_info=@common_options
+        10.times do
+          client.add_message(required_params)
+        end
+        client.flush
+        client.return_status[:results].size.should == 10
+      end
+    end
+
+    it "send an empty buffer" do
       expect do
-        client.send_email(required_params)
+        response = client.buffered_send([], @common_options)
+        response[:successCount].should == 0
       end.should_not raise_error
     end
 
-    it "raises errors when missing to_email param" do
-      api_response = "ERR :Missing required paramater toEmail"
-      expect_api_errors(required_params.without(:toEmail), api_response, "toEmail")
-    end
-
-    it "raises errors when missing from_email param" do
-      api_response = "ERR:Missing required paramater fromEmail"
-      expect_api_errors(required_params.without(:fromEmail), api_response, "fromEmail")
-    end
-
-    it "raises errors when missing subject param" do
-      api_response = "ERR:Missing required paramater subject"
-      expect_api_errors(required_params.without(:subject), api_response, "subject")
-    end
-
-    it "raises errors when missing body param" do
-      api_response = "ERR:Missing required paramater body"
-      expect_api_errors(required_params.without(:body), api_response, "body")
-    end
-  end
-
-  describe "optional parameters" do
-    it "allows to_name" do
-      expect_api_success(required_params.merge(:toName => "Chuck Norris"))
-    end
-
-    it "allows from_name" do
-      expect_api_success(required_params.merge(:fromName => "Sally Norris"))
-    end
-
-    it "allows tag" do
-      expect_api_success(required_params.merge(:tag => "weekly"))
-    end
-
-    it "allows priority with values 1 through 5" do
-      expect_api_success(required_params.merge(:priority => 1))
-      expect_api_success(required_params.merge(:priority => 2))
-      expect_api_success(required_params.merge(:priority => 3))
-      expect_api_success(required_params.merge(:priority => 4))
-      expect_api_success(required_params.merge(:priority => 5))
-
-      expect do
-        client.send_email(required_params.merge(:priority => "foo"))
-      end.should raise_error(MessagebusRubyApi::APIParameterError)
-
+    it "send a single item buffer" do
+      buffer=[required_params]
+      FakeWeb.register_uri(:post, "https://api.messagebus.com/api/v2/emails/send", :body => @simple_success_result.to_json)
       expect do
-        client.send_email(required_params.merge(:priority => 0))
-      end.should raise_error(MessagebusRubyApi::APIParameterError)
-
-      expect do
-        client.send_email(required_params.merge(:priority => 6))
-      end.should raise_error(MessagebusRubyApi::APIParameterError)
-    end
-
-    it "allows reply_to" do
-      expect_api_success(required_params.merge(:replyTo => "obiwan@example.com"))
-    end
-
-    it "allows unsubscribe_email" do
-      expect_api_success(required_params.merge(:unsubscribeEmail => "unsubscribe@aol.com"))
-    end
-
-    it "allows unsubscribe_url" do
-      expect_api_success(required_params.merge(:unsubscribeUrl => "http://foobar.com/unsubscribe"))
-    end
-
-    it "allows plain_text" do
-      expect_api_success(required_params.merge(:plainText => false))
-      expect_api_success(required_params.merge(:plainText => true))
-
-      expect do
-        client.send_email(required_params.merge(:plainText => "omg not a boolean or nil"))
-      end.should raise_error(MessagebusRubyApi::APIParameterError)
-    end
-  end
-
-  describe "#to_param" do
-    it "converts to param names and sorts them" do
-      client.to_param({:toEmail => "bob@example.com", :fromEmail => "alex@example.com"}).should == "fromEmail=alex%40example.com&toEmail=bob%40example.com"
-    end
-  end
-
-  describe "server errors" do
-    it "raises an error with the error status received by the server" do
-      url_params = client.to_param(required_params)
-      error_response_body = "ERR:Some meaningful remote error"
-      FakeWeb.register_uri(:post, api_url_from_params(url_params), status: [500, ""], :body => error_response_body)
-      expect do
-        client.send_email(required_params)
-      end.should raise_error(MessagebusRubyApi::RemoteServerError, error_response_body)
-    end
-
-    it "raises an error if the remote server returns a status other than 200 OK" do
-      url_params = client.to_param(required_params)
-      FakeWeb.register_uri(:post, api_url_from_params(url_params), :status => [404, "Not Found"], :body => "")
-      expect do
-        client.send_email(required_params)
-      end.should raise_error(MessagebusRubyApi::RemoteServerError, "ERR:Remote Server Returned: 404")
+        response = client.buffered_send(buffer, @common_options)
+        response[:successCount].should == 1
+      end.should_not raise_error
     end
-  end
 
-  describe "#basic_auth_credentials=" do
-    it "uses basic auth with the supplied credentials" do
-      client.basic_auth_credentials = {:user => "user", :password => "pass"}
-      url_params = client.to_param(required_params)
-      FakeWeb.register_uri(:post, api_url_from_params(url_params), :body => "Unauthorized", :status => ["401", "Unauthorized"])
-      FakeWeb.register_uri(:post, "https://user:pass@api.messagebus.com/send?operation=sendEmail&apiKey=#{api_key}&#{url_params}", :body => "OK:OK")
+    it "send a several item buffer" do
+      buffer=[required_params, required_params]
+      @success_result2 = {
+        "statusMessage" => "OK",
+        "successCount" => 2,
+        "failureCount" => 0,
+        "results" => [
+          {
+            "status" => 200,
+            "messageId" => "e460d7f0-908e-012e-80b4-58b035f30fd1"
+          },
+          {
+            "status" => 200,
+            "messageId" => "e460d7f0-908e-012e-80b4-58b035f30fd2"
+          }
+        ]}
+      FakeWeb.register_uri(:post, "https://api.messagebus.com/api/v2/emails/send", :body => @success_result2.to_json)
       expect do
-        client.send_email(required_params)
+        response = client.buffered_send(buffer, @common_options)
+        response[:successCount].should == 2
       end.should_not raise_error
     end
   end
 end
 
-def expect_api_success(params)
-  expected_url = api_url_from_params(client.to_param(client.check_params(params.dup)))
-  FakeWeb.register_uri(:post, expected_url, :body => "OK:OK")
-  expect do
-    response = client.send_email(params)
-    response.body.should == "OK:OK"
-  end.should_not raise_error
-end
-
-def expect_api_errors(params, fake_response, expected_error_message="")
-  expected_params = client.to_param(params.dup)
-  FakeWeb.register_uri(:post, api_url_from_params(expected_params),
-                       :body => fake_response)
-  expect do
-    client.send_email(params)
-  end.should raise_error(MessagebusRubyApi::APIParameterError, "missing or malformed parameter #{expected_error_message}")
-end
-
-def api_url_from_params(url_param_string)
-  "https://api.messagebus.com/send?operation=sendEmail&apiKey=#{api_key}&#{url_param_string}"
-end

data/spec/spec_helper.rb

@@ -3,6 +3,7 @@ dir = File.dirname(__FILE__)
 require 'rubygems'
 require 'fakeweb'
 require 'rr'
+require 'json'
 
 require "#{dir}/spec_core_extensions"
 require "#{dir}/../lib/messagebus_ruby_api"

metadata

@@ -1,29 +1,24 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: messagebus_ruby_api
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.4.0
   prerelease: 
-  version: 0.1.1
 platform: ruby
-authors: 
+authors:
 - Messagebus dev team
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-06-02 00:00:00 -07:00
+date: 2011-08-15 00:00:00.000000000 -07:00
 default_executable: 
 dependencies: []
-
-description: "Allows you to use the Messagebus API "
-email: 
+description: ! 'Allows you to use the Messagebus API '
+email:
 - messagebus@googlegroups.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - lib/messagebus_ruby_api/client.rb
 - lib/messagebus_ruby_api/errors.rb
 - lib/messagebus_ruby_api/version.rb
@@ -36,34 +31,31 @@ files:
 - Rakefile
 - .rvmrc
 has_rdoc: true
-homepage: ""
+homepage: ''
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: messagebus_ruby_api
 rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: Send email through Messagebus service
-test_files: 
+test_files:
 - spec/messagebus_ruby_api/client_spec.rb
 - spec/spec_core_extensions.rb
 - spec/spec_helper.rb