ruby-cakemail 0.0.1

data/lib/cakemail/mailing.rb

@@ -0,0 +1,215 @@
+# A Mailing is specific email content (From Name, From Email, Subject, Body) sent to a specific list or a sub-list..
+# Mailings may have the following status:
+# * Incomplete => Mailing that is not fully prepared to be delivered
+# * Scheduled  => Mailing that is ready and scheduled to be delivered
+# * Delivering  =>  Mailing in process of being delivered
+# * Delivered => Mailing has been delivered
+# * Deleted => Please note: Only an Incomplete Mailing can be deleted
+# A Mailing in process of being delivered can be suspended and resumed at any time.
+module CakeMail
+  module API
+    class ClassMailing < CakeMail::ServiceClass
+      method :name => "Create", :requires => [ :campaign_id, :name, :user_key ], :optional => [ :encoding ]
+      method :name => "Delete", :requires => [ :mailing_id, :user_key ]
+      method :name => "GetEmailMessage", :requires => [ :mailing_id, :user_key ]
+      method :name => "GetHtmlMessage", :requires => [ :mailing_id, :user_key ]
+      method :name => "GetInfo", :requires => [ :mailing_id, :user_key ]
+      method :name => "GetLinksLog", :requires => [ :mailing_id, :user_key ], :optional => [ :start_date, :end_date ]
+      method :name => "GetList", :requires => [ :campaign_id, :user_key ],
+          :optional => [ :status, :campaign_id, :list_id, :limit, :offset, :count  ]
+      method :name => "GetLog", :requires => [ :mailing_id, :user_key ], :optional => [ :action, :record_id, :start_date, :end_date,
+          :date, :extra, :limit, :offset, :count, :uniques ]
+      method :name => "GetStats", :requires => [ :mailing_id, :information, :user_key ]
+      method :name => "GetTextMessage", :requires => [ :mailing_id, :user_key ]
+      method :name => "Resume", :requires => [ :mailing_id, :user_key ]
+      method :name => "Schedule", :requires => [ :mailing_id, :user_key ], :optional => [ :date ]
+      method :name => "SendTestEmail", :requires => [ :mailing_id, :test_email, :test_type, :user_key ]
+      method :name => "SetInfo", :requires => [ :mailing_id, :user_key ], :optional => [ :campaign_id, :list_id, :sublist_id, :next_step,
+          :encoding, :clickthru_html, :clickthru_text, :opening_stats, :unsub_bottom_link, :name, :subject,
+          :sender_name, :sender_email, :html_message, :text_message, :campaign_id ]
+      method :name => "Suspend", :requires => [ :mailing_id, :user_key ]
+      method :name => "Unschedule", :requires => [ :mailing_id, :user_key ]
+    end
+  end
+
+  class Mailing
+    attr_reader :id, :active_emails, :status, :suspended, :created_on, :scheduled_on, :scheduled_for, :in_queue, :out_queue, :recipients
+    attr_accessor :campaign_id, :list_id, :sublist_id, :next_step, :encoding, :clickthru_html, :clickthru_text, :opening_stats, 
+      :unsub_bottom_link, :name, :subject, :sender_name, :sender_email, :html_message, :text_message, :campaign_id
+
+    def initialize(campaign, id)
+      @campaign = campaign
+      @id = id
+      get_info
+    end
+    # Deletes a mailing.  
+    def delete
+      @campaign.user.session.request("CakeMail::API::ClassMailing", "Delete", { :mailing_id => @id, :user_key => @campaign.user.user_key })
+      self.freeze
+    end
+    # Returns the subject and the message of the mailing.  
+    def get_email_message
+      @campaign.user.session.request("CakeMail::API::ClassMailing", "GetEmailMessage", { :mailing_id => @id, 
+        :user_key => @campaign.user.user_key })
+      @subject = res['subject'].first
+      @message = res['message'].first
+    end
+    # Retrieves the html message of a mailing.  
+    def get_html_message
+      @campaign.user.session.request("CakeMail::API::ClassMailing", "GetHtmlMessage", { :mailing_id => @id, 
+        :user_key => @campaign.user.user_key })
+      @html_message = res['html_message'].first
+    end
+    # Retrieves the text message of a mailing.  
+    def get_text_message
+      @campaign.user.session.request("CakeMail::API::ClassMailing", "GetTextMessage", { :mailing_id => @id, 
+        :user_key => @campaign.user.user_key })
+      @text_message = res['text_message'].first
+    end
+    # Retrieves the setting for a mailing.  
+    def get_info(id = @id)
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "GetInfo", { :mailing_id => @id, 
+        :user_key => @campaign.user.user_key })
+      @active_emails = res['active_emails'].first
+      @campaign_id = res['campaign_id'].first
+      @clickthru_html = res['clickthru_html'].first
+      @clickthru_text = res['clickthru_text'].first
+      @created_on = res['created_on'].first
+      @encoding = res['encoding'].first
+      @html_message = res['html_message'].first
+      @id = res['id'].first
+      @in_queue = res['in_queue'].first
+      @list_id = res['list_id'].first
+      @name = res['name'].first
+      @next_step = res['next_step'].first
+      @opening_stats = res['opening_stats'].first
+      @out_queue = res['out_queue'].first
+      @recipients = res['recipients'].first
+      @scheduled_for = res['scheduled_for'].first
+      @scheduled_on = res['scheduled_on'].first
+      @sender_name = res['sender_name'].first
+      @status = res['status'].first
+      @subject = res['subject'].first
+      @sublist_id = res['sublist_id'].first
+      @suspended = res['suspended'].first
+      @text_message = res['text_message'].first
+      @unsub_bottom_link = res['unsub_bottom_link'].first
+    end
+    # Retrieves information about the log of a mailing.  
+    #
+    # Arguments :
+    # * args = { :action => optional, :record_id => optional, :start_date => optional, :end_date => optional, :date => optional, 
+    #   :extra => optional, :limit => optional, :offset => optional, :count => optional, :uniques => optional }
+    def get_log(args)
+      options = { :mailing_id => @id, :user_key  => @campaign.user.user_key }
+      options[:action] = args[:action] unless args[:action].nil?
+      options[:record_id] = args[:record_id] unless args[:record_id].nil?
+      options[:start_date] = args[:start_date] unless args[:start_date].nil?
+      options[:end_date] = args[:end_date] unless args[:end_date].nil?
+      options[:date] = args[:date] unless args[:date].nil?
+      options[:extra] = args[:extra] unless args[:extra].nil?
+      options[:limit] = args[:limit] unless args[:limit].nil?
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "GetLog", options)
+      res['log']
+    end
+    # Retrieves statistics about the links of a mailing.  
+    def get_links_log(start_date = nil, end_date = nil)
+      args = { :mailing_id => @id, :user_key  => @campaign.user.user_key }
+      args[:start_date] = start_date unless start_date.nil?
+      args[:end_date] = end_date unless end_date.nil?
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "GetLinksLog", args)
+      res['link']
+    end
+    # Retrieves the links of a mailing.  
+    def get_links(status = nil)
+      args = { :mailing_id => @id, :user_key  => @campaign.user.user_key }
+      args[:status] = status unless status.nil?
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "GetLinks", args)
+      res['link']
+    end
+    # Retrieves statistics about a mailing.  
+    def get_stats(information)
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "GetStats", { :information => information, :mailing_id => @id, 
+        :user_key => @campaign.user.user_key })
+      res[information].first
+    end
+    # Resumes the delivery of a mailing.  
+    def resume
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "Resume", { :mailing_id => @id, 
+        :user_key  => @campaign.user.user_key })
+    end
+    
+    def save
+      self.set_info
+    end
+    # Schedules a mailing for delivery.  
+    def schedule(date = nil)
+      args = { :mailing_id => @id, :user_key  => @campaign.user.user_key }
+      args[:date] = date unless date.nil?
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "Schedule", args)
+    end
+    # Sends the mailing as a test to an email.  
+    def send_test_email(test_email, test_type)
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "SendTestEmail", { :mailing_id => @id, 
+        :user_key  => @campaign.user.user_key, :test_email => test_email, :test_type => test_type })
+    end
+    # Modifies the settings of a mailing.  
+    def set_info
+      args = { :mailing_id => @id, :user_key => @campaign.user.user_key }
+      args[:campaign_id] = @campaign_id unless @campaign_id.nil?
+      args[:list_id] = @list_id unless @list_id.nil? or @list_id == '0'
+      args[:sublist_id] = @sublist_id unless @sublist_id.nil? or @sublist_id == '0'
+      args[:next_step] = @next_step unless @next_step.nil?
+      args[:encoding] = @encoding unless @encoding.nil?
+      args[:clickthru_html] = @clickthru_html unless @clickthru_html.nil?
+      args[:clickthru_text] = @clickthru_text unless @clickthru_text.nil?
+      args[:opening_stats] = @opening_stats unless @opening_stats.nil?
+      args[:unsub_bottom_link] = @unsub_bottom_link unless @unsub_bottom_link.nil?
+      args[:name] = @name unless @name.nil?
+      args[:subject] = @subject unless @subject.nil?
+      args[:sender_name]  = @sender_name unless @sender_name.nil?
+      args[:sender_email] = @sender_email unless @sender_email.nil?
+      args[:html_message] = @html_message unless @html_message.nil?
+      args[:text_message] = @text_message unless @text_message.nil?
+      args[:campaign_id] = @campaign_id unless @campaign_id.nil?
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "SetInfo", args)
+    end
+    # Suspends the delivery of a mailing.  
+    def suspend
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "Suspend", { :mailing_id => @id, 
+        :user_key  => @campaign.user.user_key })
+    end
+    # Unschedules a mailing from delivery.  
+    def unschedule
+      res = @campaign.user.session.request("CakeMail::API::ClassMailing", "Unschedule", { :mailing_id => @id, 
+        :user_key  => @campaign.user.user_key })
+    end
+    
+    class << self
+      # Creates a mailing.  
+      def create(campaign, name, encoding = nil)
+        args = { :campaign_id => campaign.id, :name => name, :user_key => campaign.user.user_key }
+        args[:encoding] = encoding unless encoding.nil?
+        res = campaign.user.session.request("CakeMail::API::ClassMailing", "Create", args)
+        Mailing.new(campaign, res['id'].first)
+      end
+      # Returns the list of mailings. 
+      # 
+      # Arguments :
+      # * args = { :campaign => required, :status => optional, :campaign_id => optional, :list_id => optional, :limit => optional,
+      #   :offset => optional, :count => optional } 
+      def get_list(args)
+        raise ArgumentError if args.nil? or args[:campaign].nil?
+        options = { :user_key => args[:campaign].user.user_key }
+        options[:status] = args[:status] unless args[:status].nil?
+        options[:campaign_id] = args[:campaign_id] unless args[:campaign_id].nil?
+        options[:list_id] = args[:list_id] unless args[:list_id].nil?
+        options[:limit] = args[:limit] unless args[:limit].nil?
+        options[:offset] = args[:offset] unless args[:offset].nil?
+        options[:count] = args[:count] unless args[:count].nil?
+        res = args[:campaign].user.session.request("CakeMail::API::ClassMailing", "GetList", options)
+        res['mailing']
+      end
+    end
+  end
+end

data/lib/cakemail/relay.rb

@@ -0,0 +1,64 @@
+# The Relay accepts an individual email in a single API call, and applies open and link tracking, performs sender-email authentication, 
+# delivers the email and logs recipient activity.
+#
+# Possible usage:
+# * Password reminders
+# * Email invoices
+# * Automatic email notifications
+# * Membership invitations
+# * Confirmations
+# * User to user messaging systems
+# * SMTP to Relay
+module CakeMail
+  module API
+    class ClassRelay < CakeMail::ServiceClass
+      method :name => "send", :requires => [ :user_key, :email, :sender_name, :sender_email, :subject ], :optional => [ :html_message, 
+        :text_message, :encoding, :track_opening, :track_clicks_in_html, :track_clicks_in_text ], :custom_args_xml => [
+          Proc.new do |builder, args|
+            unless args[:data].nil?
+              args[:data].each { |r| builder.data({ :type => r[:type] }, r[:value]) }
+            end
+          end 
+          ]
+      method :name => "GetLogs", :requires => [ :user_key, :log_type ], :optional => [ :start_time, :end_time ]
+    end
+  end
+
+  class Relay
+    class << self
+      # Send an email using the Relay.
+      #  
+      # Arguments :
+      # * args = { :user => required, :email => required, :sender_name => required, :sender_email => required, :subject => required, 
+      #   :html_message => optional, :text_message => optional, :encoding => optional, :track_opening => optional,
+      #   :track_clicks_in_html => optional, :track_clicks_in_text => optional, :data => optional/custom }
+      # Custom format of :data :
+      # * [ { :type => "text", :name => "schedule" }, { :type => "text", :name => "schedule" }, ... ]
+      def send(args)
+        raise ArgumentError if args.nil? or args[:user] or args[:email].nil? or args[:sender_name] or args[:sender_email] or args[:subject]
+        options = { :user_key => args[:user].user_key, :email => args[:email], :sender_name => args[:sender_name], 
+          :sender_email => args[:sender_email], :subject => args[:subject] }
+        options[:html_message] = args[:html_message] unless args[:html_message].nil?
+        options[:text_message] = args[:text_message] unless args[:text_message].nil?
+        options[:encoding] = args[:encoding] unless args[:encoding].nil?
+        options[:track_opening] = args[:track_opening] unless args[:track_opening].nil?
+        options[:track_clicks_in_html] = args[:track_clicks_in_html] unless args[:track_clicks_in_html].nil?
+        options[:track_clicks_in_text] = args[:track_clicks_in_text] unless args[:track_clicks_in_text].nil?
+        options[:data] = args[:data] unless args[:data].nil?
+        res = args[:user].session.request("CakeMail::API::ClassRelay", "Send", options)
+      end
+      # Retrieves logs from Relay.
+      #  
+      # Arguments :
+      # * args = { :user => required, :log_type => required, :start_time => optional, :end_time => optional }
+      def get_logs(args)
+        raise ArgumentError if args.nil? or args[:user] or args[:log_type].nil?
+        options = { :user_key => args[:user].user_key, :log_type => args[:log_type] }
+        options[:start_time] = args[:start_time] unless args[:start_time].nil?
+        options[:end_time] = args[:end_time] unless args[:end_time].nil?
+        res = args[:user].session.request("CakeMail::API::ClassRelay", "Send", options)
+        return res['bounce_log']
+      end
+    end
+  end
+end

data/lib/cakemail/service.rb

@@ -0,0 +1,46 @@
+module CakeMail  
+  class ServiceMethod
+    attr_reader :name, :requires, :optional
+
+    def initialize(name, requires, optional, custom_args_xml)
+      @name = name
+      @requires = requires
+      @optional = optional
+      @custom_args_xml = custom_args_xml
+    end
+
+    def to_xml(builder, args)
+      @requires.each do |arg|
+        raise ArgumentError.new(arg.to_s) unless args.has_key?(arg)
+        builder.__send__(arg.to_s, args[arg])
+      end
+      @optional.each do |arg|
+        builder.__send__(arg.to_s, args[arg]) if args.has_key?(arg)
+      end
+      @custom_args_xml.each do |arg|
+        arg.call(builder, args)
+      end
+    end
+  end
+
+  class ServiceClass
+    class InvalidMethod < Exception; end
+
+    def self.method(args)
+      raise ArgumentError.new("args or name missing") if args.nil? or args[:name].nil?
+      @methods ||= { }
+      name = args[:name]
+      @methods[name] = ServiceMethod.new(name, args[:requires] || [ ], args[:optional] || [ ], args[:custom_args_xml] || [ ])
+    end
+
+    def self.method_xml(builder, session, method, args)
+      raise ArgumentError.new("builder or session missing") if builder.nil? or session.nil?
+      raise InvalidMethod unless @methods.has_key?(method)
+      builder.class(:type => self.to_s.gsub(/.*::/, ''), :locale => session.class::API_LOCALE) do |klass|
+        klass.method(:type => method) do |meth|
+          @methods[method].to_xml(meth, args)
+        end
+      end
+    end
+  end
+end

data/lib/cakemail/session.rb

@@ -0,0 +1,70 @@
+module CakeMail
+  class Session
+    class HttpRequestError < Exception; end
+    class ApiRequestError < Exception; end
+
+    API_SERVER_BASE_URL = "http://api.cakemail.com/"
+    API_VERSION = "1.0"
+    API_LOCALE = "en_US"
+
+    attr_reader :api_id, :api_key, :user_key
+    
+    def initialize(api_id, api_key)
+      @api_id = api_id
+      @api_key = api_key
+      @crypto = Crypt::Blowfish.new(@api_key)
+    end
+    # Returns a logged in user.
+    def login(email, password)
+      user = CakeMail::User.login(self, email, password)
+      return user
+    end
+    # Recover password.
+    def password_recovery(email)
+      CakeMail::User.password_recovery(email)
+    end
+    
+    def request(service_class, method, args)
+      builder = Builder::XmlMarkup.new(:indent => 1)
+      builder.instruct! :xml, :version => "1.0", :encoding => "utf-8"
+      req = builder.body(:version => API_VERSION) { |body| Object.module_eval(service_class).method_xml(body, self, method, args) } 
+      res = Net::HTTP.post_form(URI.parse(API_SERVER_BASE_URL), {'alg' => 'blowfish', 'mode' => 'ecb', 'id' => @api_id, 'request' => encode(req)})
+      raise HttpRequestError if res.nil? || res.body.nil? || (res.code.to_i != 200)
+      r = XmlSimple.xml_in(decode(res.body))
+      raise ApiRequestError if r.nil? || !r.has_key?('class') || !r['class'].is_a?(Array)
+      r = r['class'].first
+      raise ApiRequestError if (r['type'] != service_class.gsub(/.*::/, '')) ||
+      !r['method'].is_a?(Array) || (r['method'].first['type'] != method)
+      r = r['method'].first
+      r = unescape_xmlsimple_result(r)
+      if r.has_key?('error_code')
+        error = "Error #{r['error_code'].first}"
+        error += ": #{CGI.unescape(r['error_message'].first)}" if r.has_key?('error_message')
+        error += " [#{service_class.to_s} :: #{method}]"
+        raise ApiRequestError.new(error)
+      end
+      return r
+    end
+
+    private
+    def encode(req)
+      @crypto.encrypt_string(req).unpack("H*").first
+    end
+
+    def decode(req)
+      @crypto.decrypt_string([req].pack("H*"))
+    end
+
+    def unescape_xmlsimple_result(data)
+      if data.is_a?(Hash)
+        newdata = { }
+        data.each { |k,v| newdata[k] = unescape_xmlsimple_result(v) }
+        newdata
+      elsif data.is_a?(Array)
+        data.map { |elem| unescape_xmlsimple_result(elem) }
+      elsif data.is_a?(String)
+        CGI.unescape(data)
+      end
+    end
+  end
+end

data/lib/cakemail/suppressionlist.rb

@@ -0,0 +1,102 @@
+module CakeMail
+  module API
+    class ClassSuppressionList < CakeMail::ServiceClass
+      method :name => "ImportEmails", :requires => [ :user_key ], :custom_args_xml => [
+        Proc.new do |builder, args|
+          unless args[:email].nil?
+            args[:email].each { |r| builder.email(r) }
+          end
+        end 
+        ]
+      method :name => "ExportEmails", :requires => [ :user_key ], :optional => [ :source_type, :limit, :offset, :count ]
+      method :name => "DeleteEmails", :requires => [ :user_key ], :custom_args_xml => [
+        Proc.new do |builder, args|
+          unless args[:email].nil?
+            args[:email].each { |r| builder.email(r) }
+          end
+        end 
+        ]
+      method :name => "ImportDomains", :requires => [ :user_key ], :custom_args_xml => [
+          Proc.new do |builder, args|
+            unless args[:domain].nil?
+              args[:domain].each { |r| builder.domain(r) }
+            end
+          end 
+          ]
+      method :name => "ExportDomains", :requires => [ :user_key ], :optional => [ :limit, :offset, :count ]
+      method :name => "DeleteDomains", :requires => [ :user_key ], :custom_args_xml => [
+          Proc.new do |builder, args|
+            unless args[:domain].nil?
+              args[:domain].each { |r| builder.domain(r) }
+            end
+          end 
+          ]
+    end
+  end
+
+  class SuppressionList
+    class << self
+      # Imports one or more emails into the suppression list.
+      #
+      # Custom argument :
+      # emails = [ 'test@example.com', 'test2@example.com', ... ]  
+      def import_emails(user, emails)                    
+        res = user.session.request("CakeMail::API::ClassSuppressionList", "ImportEmails", { :email => emails, :user_key => user.user_key })
+      end
+      # Exports the suppressed emails.
+      #
+      # Arguments :
+      # * args = { :user => required, :source_type => optional, :limit => optional, :count => optional,    }  
+      def export_emails(args)
+        raise ArgumentError if args.nil? or args[:user].nil?
+        options = { :user_key => args[:user].user_key }
+        options[:source_type] = arg[:source_type] unless arg[:source_type].nil?
+        options[:limit] = arg[:limit] unless arg[:limit].nil?
+        options[:offset] = arg[:offset] unless arg[:offset].nil?
+        options[:count] = arg[:count] unless arg[:count].nil?
+        res = arg[:user].session.request("CakeMail::API::ClassSuppressionList", "ExportEmails", options)
+        if !arg[:count].nil?
+          return res['count']
+        end
+        return res['record']
+      end
+      # Deletes one or more emails from the suppression list.
+      #
+      # Custom argument :
+      # emails = [ 'test@example.com', 'test2@example.com', ... ]  
+      def delete_emails(user, emails)
+        res = user.session.request("CakeMail::API::ClassSuppressionList", "DeleteEmails", { :user_key => user.user_key, :email => emails })
+      end
+      # Imports one or more domains into the suppression list. 
+      #
+      # Custom argument :
+      # * domains = [ 'domain1.com', 'domain2', ...]
+      def import_domains(user, domains)                    
+        res = user.session.request("CakeMail::API::ClassSuppressionList", "ImportDomains", { :domain => domains, :user_key => user.user_key })
+      end
+      # Exports the suppressed emails.
+      #
+      # Arguments :
+      # * args = { :user => required, :limit => optional, :offset => optional, :count => optional }
+      def export_domains(args)
+        raise ArgumentError if args.nil? or args[:user].nil?
+        options = { :user_key => args[:user].user_key }
+        options[:limit] = args[:limit] unless args[:limit].nil?
+        options[:offset] = args[:offset] unless args[:offset].nil?
+        options[:count] = args[:count] unless args[:count].nil?
+        res = args[:user].session.request("CakeMail::API::ClassSuppressionList", "ExportDomains", options)
+        if !args[:count].nil?
+          return res['count']
+        end
+        return res['record']
+      end
+      # Deletes one or more domains from the suppression list.
+      #
+      # Custom argument :
+      # * domains = [ 'domain1.com', 'domain2', ...]
+      def delete_domains(user, domains)
+        res = user.session.request("CakeMail::API::ClassSuppressionList", "DeleteDomains", { :user_key => user.user_key, :domain => domains })
+      end
+    end
+  end
+end