mailbuild 1.0

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2008 Cameron Yule
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,39 @@
+== Mailbuild
+
+An implementation of the Mailbuild API, http://www.mailbuild.com/api
+
+
+== Install
+
+sudo gem install mailbuild
+
+
+== Usage
+
+There is a sample Rails application available demonstrating all API calls;
+
+svn co http://mailbuild.rubyforge.org/svn/rails_mailbuild_example/
+
+
+== Debugging
+
+Run Ruby with the debug switch (ruby -d) to see SOAP wiredumps.
+
+This lets you see the XML being sent/received.
+
+
+== License
+
+The Mailbuild gem is released under the MIT license. See MIT-LICENSE file.
+
+
+== Credit
+
+The cattr_accessor code is by Tobias Lutke.
+
+
+== Contact
+
+For bugs or support requests, http://rubyforge.org/projects/mailbuild/
+
+Anything else, drop me an email at cameron@cameronyule.com

data/lib/mailbuild.rb

@@ -0,0 +1,22 @@
+# Copyright (c) 2008 Cameron Yule
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require File.dirname(__FILE__) + '/support/cattr_accessor'
+require File.dirname(__FILE__) + '/mailbuild/mailbuild'

data/lib/mailbuild/mailbuild.rb

@@ -0,0 +1,161 @@
+require 'soap/wsdlDriver'
+require 'cgi'
+require 'support/cattr_accessor'
+require 'mailbuild/mailbuild_error'
+
+# Implementation of the Mailbuild API.
+
+class Mailbuild
+  
+  include MailbuildError
+  
+  cattr_accessor :api_key, :list_id, :subdomain
+  
+  # Implements Subscriber.Add
+  # http://www.mailbuild.com/api/subscriber.add.aspx
+  #
+  def self.add(email, name, list_id = @@list_id)
+    self.connect
+    result = @@service.AddSubscriber({:ApiKey=>@@api_key, :ListID=>list_id, :Email=>email, :Name=>name})
+    response = result.subscriber_AddResult
+    self.parse_response(response, 'Subscriber.Add')
+  end
+  
+  # Implements Subscriber.AddWithCustomFields
+  # http://www.mailbuild.com/api/subscriber.addwithcustomfields.aspx
+  #
+  def self.add_with_custom_field(email, name, custom_fields = {}, list_id = @@list_id)
+    self.connect
+    
+    # Convert custom fields to an array of hashes
+    custom = custom_fields.collect{|key, value| {:Key => key.to_s, :Value => value}}    
+
+    result = @@service.AddSubscriberWithCustomFields({:ApiKey=>@@api_key, :ListID=>list_id, :Email=>email, :Name=>name, :CustomFields=>{:SubscriberCustomField =>custom}})
+    response = result.subscriber_AddWithCustomFieldsResult
+    self.parse_response(response, 'Subscriber.AddWithCustomFields')
+  end
+
+  # Implements <tt>Subscriber.Unsubscribe</tt>
+  # http://www.mailbuild.com/api/subscriber.unsubscribe.aspx
+  #
+  def self.unsubscribe(email, list_id = @@list_id)
+    self.connect
+    result = @@service.Unsubscribe({:ApiKey=>@@api_key, :ListID=>list_id, :Email=>email})
+    response = result.subscriber_UnsubscribeResult
+    self.parse_response(response, 'Subscriber.Unsubscribe')
+  end
+  
+  # This method is undocumented.
+  #
+  # Implements Subscribers.GetSingleSubscriber
+  #
+  def self.subscriber(email, list_id = @@list_id)
+    self.connect
+    result = @@service.GetSingleSubscriber({:ApiKey=>@@api_key, :ListID=>list_id, :EmailAddress=>email})
+    subscriber = result.subscribers_GetSingleSubscriberResult    
+    self.parse_response(subscriber, 'Subscribers.GetSingleSubscriber')
+  end
+
+  # The Mailbuild API documentation is currently out of date.
+  # This method is actually implemented as Subscribers.GetSubscribers
+  #
+  # Implements Subscribers.GetActive
+  # http://www.mailbuild.com/api/Subscribers.GetActive.aspx
+  #
+  def self.subscribers(date, list_id = @@list_id)
+    self.connect
+    result = @@service.GetSubscribers({:ApiKey=>@@api_key, :ListID=>list_id, :Date=>date})
+    subscribers = result.subscribers_GetActiveResult
+    self.parse_response(subscribers, 'Subscribers.GetSubscribers')
+  end
+
+  # Implements Subscribers.GetUnsubscribed
+  # http://www.mailbuild.com/api/Subscribers.GetUnsubscribed.aspx
+  #
+  def self.unsubscribed(date, list_id = @@list_id)
+    self.connect
+    result = @@service.GetUnsubscribed({:ApiKey=>@@api_key, :ListID=>list_id, :Date=>date})
+    unsubscribed = result.subscribers_GetUnsubscribedResult
+    self.parse_response(unsubscribed, 'Subscribers.GetUnsubscribed')
+  end
+
+  # Implements Subscribers.GetBounced
+  # http://www.mailbuild.com/api/Subscribers.GetBounced.aspx
+  #
+  def self.bounced(date, list_id = @@list_id)
+    self.connect
+    result = @@service.GetBounced({:ApiKey=>@@api_key, :ListID=>list_id, :Date=>date})
+    bounced = result.subscribers_GetBouncedResult
+    self.parse_response(bounced, 'Subscribers.GetBounced')
+  end
+  
+  protected
+  
+    def self.connect
+      self.check_config
+      wsdl_url = "http://#{@@subdomain}.createsend.com/api/api.asmx?wsdl"
+      @@service = SOAP::WSDLDriverFactory.new(wsdl_url).create_rpc_driver or raise ConnectionError.new('Unable to self.connect to Mailbuild SOAP service. Network problem?')
+
+      @@service.wiredump_dev = STDERR if $DEBUG
+    end
+    
+    def self.check_config
+      raise ArgumentError.new("Please set your Mailbuild API key") if @@api_key.blank?
+      raise ArgumentError.new("Please set your Mailbuild list ID") if @@list_id.blank?
+      raise ArgumentError.new("Please set your Mailbuild subdomain") if @@subdomain.blank?
+    end
+  
+    def self.parse_response(response, method_name)
+      if response.respond_to? :code
+        response_code = response.code.to_i
+        self.parse_response_code(response_code, method_name)
+      else
+        self.handle_subscribers_list(response, method_name)
+      end
+    end
+  
+    def self.parse_response_code(response_code, method_name)
+      case response_code
+        when 1
+          raise EmailError.new("#{method_name}: Invalid email address.")
+        when 5
+          raise DateError.new("#{method_name}: Invalid date.")
+        when 100
+          raise APIKeyError.new("#{method_name}: Invalid API Key.")
+        when 101
+          raise ListIDError.new("#{method_name}: Invalid ListID.")
+        when 203
+          raise SubscriberNotFoundError.new("#{method_name} Subscriber not in list.")
+        else
+          return true
+      end
+    end
+    
+    def self.handle_subscribers_list(subscribers, method_name)
+      if subscribers.respond_to?(:subscriber)
+        if subscribers.subscriber.is_a? Array
+          subscribers.subscriber.collect{|subscriber| self.create_subscriber_object(subscriber)}
+        else
+          [self.create_subscriber_object(subscribers.subscriber)]
+        end
+      elsif subscribers.respond_to?(:emailAddress)
+        self.create_subscriber_object(subscribers)
+      else
+        raise SubscribersNotFoundError.new("#{method_name}: No subscribers returned.")
+      end
+    end
+    
+    def self.create_subscriber_object(subscriber)
+      custom = self.parse_custom_fields(subscriber)
+      {:email => subscriber.emailAddress, :name => subscriber.name, :subscribed_at => subscriber.date, :state => subscriber.state, :custom => custom}
+    end
+      
+    def self.parse_custom_fields(subscriber)
+      if subscriber.respond_to?(:customFields) && subscriber.customFields.respond_to?(:subscriberCustomField) && !subscriber.customFields.subscriberCustomField.first.value.is_a?(SOAP::Mapping::Object)
+        subscriber.customFields.subscriberCustomField
+      else
+        nil
+      end
+    end
+      
+end

data/lib/mailbuild/mailbuild_error.rb

@@ -0,0 +1,10 @@
+module MailbuildError
+  class Error < RuntimeError; end
+  class ConnectionError < Error; end
+  class EmailError < ArgumentError; end
+  class APIKeyError < ArgumentError; end
+  class ListIDError < ArgumentError; end
+  class SubscribersNotFoundError < RuntimeError; end
+  class SubscriberNotFoundError < RuntimeError; end
+  class DateError < RuntimeError; end
+end

data/lib/support/cattr_accessor.rb

@@ -0,0 +1,78 @@
+# Extends the class object with class and instance accessors for class attributes, 
+# just like the native attr* accessors for instance attributes.
+#
+# Copyright (c) 2005 Tobias Lutke
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+class Class # :nodoc:
+  def cattr_reader(*syms)
+    syms.each do |sym|
+      class_eval <<-EOS
+        if ! defined? @@#{sym.id2name}
+          @@#{sym.id2name} = nil
+        end
+        
+        def self.#{sym.id2name}
+          @@#{sym}
+        end
+
+        def #{sym.id2name}
+          @@#{sym}
+        end
+
+        def call_#{sym.id2name}
+          case @@#{sym.id2name}
+            when Symbol then send(@@#{sym})
+            when Proc   then @@#{sym}.call(self)
+            when String then @@#{sym}
+            else nil
+          end
+        end
+      EOS
+    end
+  end
+  
+  def cattr_writer(*syms)
+    syms.each do |sym|
+      class_eval <<-EOS
+        if ! defined? @@#{sym.id2name}
+          @@#{sym.id2name} = nil
+        end
+        
+        def self.#{sym.id2name}=(obj)
+          @@#{sym.id2name} = obj
+        end
+
+        def self.set_#{sym.id2name}(obj)
+          @@#{sym.id2name} = obj
+        end
+
+        def #{sym.id2name}=(obj)
+          @@#{sym} = obj
+        end
+      EOS
+    end
+  end
+  
+  def cattr_accessor(*syms)
+    cattr_reader(*syms)
+    cattr_writer(*syms)
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: mailbuild
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+platform: ruby
+authors: 
+- Cameron Yule
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-07-24 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: 
+email: cameron@cameronyule.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- MIT-LICENSE
+files: 
+- lib/mailbuild
+- lib/mailbuild/mailbuild.rb
+- lib/mailbuild/mailbuild_error.rb
+- lib/mailbuild.rb
+- lib/support
+- lib/support/cattr_accessor.rb
+- README
+- MIT-LICENSE
+has_rdoc: true
+homepage: http://rubyforge.org/projects/mailbuild/
+post_install_message: 
+rdoc_options: 
+- --title
+- Mailbuild | RDoc documentation
+- --main
+- README
+- --line-numbers
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: mailbuild
+rubygems_version: 1.1.1
+signing_key: 
+specification_version: 2
+summary: Ruby interface to the Mailbuild API.
+test_files: []
+