postal 0.2.3 → 0.3.0

data/.gitignore

@@ -5,4 +5,6 @@ rdoc
 pkg
 test/run*.rb
 run*.rb
-test/lyris.yml
+test/lyris.yml
+.rvmrc
+*.gem

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    postal (0.3.0)
+      savon (= 0.9.7)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    akami (1.0.0)
+      gyoku (>= 0.4.0)
+    builder (3.0.0)
+    gyoku (0.4.4)
+      builder (>= 2.1.2)
+    httpi (0.9.5)
+      rack
+    nokogiri (1.5.0)
+    nori (1.0.2)
+    rack (1.4.1)
+    savon (0.9.7)
+      akami (~> 1.0)
+      builder (>= 2.1.2)
+      gyoku (>= 0.4.0)
+      httpi (~> 0.9)
+      nokogiri (>= 1.4.0)
+      nori (~> 1.0)
+      wasabi (~> 2.0)
+    wasabi (2.0.0)
+      nokogiri (>= 1.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  postal!

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Rob Cameron
+Copyright (c) 2009 The Active Network
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,108 @@
+# Introduction
+
+Postal is a gem for working with the Lyris API. "But the Lyris API is just a SOAP service, why
+don't I use something like Soap4r?" Well you could, but it wouldn't be very pretty. When the
+interface is created all properties passed to a method are required and always in a certain order.
+
+Postal does use the Soap4r interface behind the scenes but gives you a simple ActiveRecord-like
+interface for search and adding records.
+
+## Installation
+
+Get the gem:
+
+    gem sources -a http://gems.github.com
+    sudo gem install cannikin-postal
+  
+Then to use just add the require to your script:
+
+    require 'rubygems'
+    require 'postal'
+  
+## Usage
+
+Postal feels a lot like using ActiveRecord. You create/save new Members, find existing ones, etc.
+All of the examples below assume you've already set up Postal with your username, password and WSDL
+endpoint, and optionally the name of the list that all operations should use:
+
+    Postal.options[:wsdl] = 'http://mymailserver.com:82/?wsdl'
+    Postal.options[:username] = 'username'
+    Postal.options[:password] = 'password'
+    Postal.options[:list_name] = 'my-test-list'
+
+If you don't set your list name in the options you can pass it in with each method call.
+
+See the /test directory for examples of just about everything you can do with Postal.
+
+### Lists
+
+    # find a list based on its name
+    Postal::List.find('my-list-name')
+  
+### Members
+
+    # add a member to a list (the list saved to Postal.options)
+    new_member = Postal::Member.new(:email => "john.doe@anonymous.com", :name => "John Doe")
+    id = new_member.save
+    # id => 1234567 (the new member_id in Lyris)
+    
+    # add a member to a specific list and save in one call (both lines are equivalent)
+    Postal::Member.new(:email => "john.doe@anonymous.com", :name => "John Doe", :list_name => "new-list").save
+    Postal::Member.create(:email => "john.doe@anonymous.com", :name => "John Doe", :list_name => "new-list")
+  
+Postal also has a `save!` method that throws an error if the person can't be saved, rather than just
+returning false.
+
+    # update a member's demographics
+    new_member = Postal::Member.new(:email => "john.doe@anonymous.com", :name => "John Doe")
+    new_member.save
+    new_member.update_attributes(:field_0 => 'Male')
+    
+    # find a member's id based on an email address
+    Postal::Member.find('john.doe@anonymous.com')
+    
+    # find a member based on member_id
+    Postal::Member.find(1234567)
+    
+    # find a member based on Lyris "filters" (see Lyris API docs for syntax)
+    Postal::Member.find_by_filter('EmailAddress like john.doe%')
+    
+    # delete member(s) based on filters
+    Postal::Member.destroy("EmailAddress like john.doe-delete%")
+  
+### Mailings
+
+    # directly send an email to an array of email addresses
+    mail = Postal::Mailing.new( :to => ['john.doe@anonymous.com','jane.doe@anonymous.com'], 
+                                :html_message => "<p>Test from Postal at #{Time.now.to_s}</p>", 
+                                :text_message => 'Test test from Postal at #{Time.now.to_s}', 
+                                :from => 'Postmaster <postmaster@company.com>',
+                                :subject => 'Test from Postal')
+    mail.valid?
+    mail.send
+  
+Mailings require a couple things to be valid, mainly someone to send to, a subject, and 
+the name of a list to send to. `mail.valid?` will return false if any of these do not exist.
+
+## To Do
+
+* Implement wrappers for remaining Lyris methods
+
+## Thanks
+
+Special thanks to this article: http://markthomas.org/2007/09/12/getting-started-with-soap4r/
+Mark details how to use Soap4r (for which there is very little documentation in the world) and
+his example includes talking to Lyris! Postal probably couldn't have happened without his article.
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2009 The Active Network. See LICENSE for details.

data/lib/postal.rb

@@ -4,9 +4,7 @@ $:.unshift File.dirname(__FILE__) # for use/testing when no gem is installed
 require 'logger'
 
 # internal
-require 'postal/lmapi/lmapi.rb'
-require 'postal/lmapi/lmapi_driver.rb'
-require 'postal/lmapi/lmapi_mapping_registry.rb'
+require 'postal/driver'
 require 'postal/base'
 require 'postal/content'
 require 'postal/list'
@@ -37,9 +35,7 @@ module Postal
   # Make a driver instance available at Postal.driver
   def driver
     unless @driver
-      @driver = Postal::Lmapi::Soap.new(@options[:wsdl])
-      @driver.options['protocol.http.basic_auth'] << [@options[:wsdl], @options[:username], @options[:password]]
-      @driver.options['protocol.http.proxy'] = @options[:proxy]
+      @driver = Postal::Driver.new @options[:wsdl], @options[:proxy], @options[:username], @options[:password]
     end
     return @driver
   end

data/lib/postal/content.rb

@@ -7,22 +7,21 @@ module Postal
         unless args.find { |arg| arg.match(/ListName/) }
           args << "ListName=#{Postal.options[:list_name]}"
         end
-        if soap_contents = Postal.driver.selectContent(args)
+        if soap_contents = Postal.driver.selectContent(args)[:item]
           contents = soap_contents.collect do |content|
-            puts content.inspect
-            Content.new(:content_id => content.contentID,
-                        :date_created => content.dateCreated, 
-                        :description => content.description, 
-                        :doc_parts => content.docParts, 
-                        :doc_type => content.docType,
-                        :header_from => content.headerFrom,
-                        :header_to => content.headerTo,
-                        :is_read_only => content.isReadOnly,
-                        :is_template => content.isTemplate,
-                        :list_name => content.listName,
-                        :native_title => content.nativeTitle,
-                        :site_name => content.siteName,
-                        :title => content.title)
+            Content.new(:content_id => content[:content_id],
+                        :date_created => content[:date_created], 
+                        :description => content[:description], 
+                        :doc_parts => content[:doc_parts], 
+                        :doc_type => content[:doc_yype],
+                        :header_from => content[:header_from],
+                        :header_to => content[:header_to],
+                        :is_read_only => content[:is_read_only],
+                        :is_template => content[:is_template],
+                        :list_name => content[:list_name],
+                        :native_title => content[:native_title],
+                        :site_name => content[:site_name],
+                        :title => content[:title])
           end
           if contents.size == 1
             return contents.first

data/lib/postal/driver.rb

@@ -0,0 +1,121 @@
+# Main class used by client programs
+
+require 'savon'
+
+module Postal
+  class Driver
+
+    attr_accessor :client
+    
+    DefaultEndpointUrl = "http://www.mymailserver.com/"
+
+    def initialize(wsdl_url = nil, proxy = nil, username = nil, password = nil)
+      wsdl_url ||= DefaultEndpointUrl
+      @client = Savon::Client.new do |wsdl, http|
+        wsdl.document = wsdl_url
+        if proxy
+          http.proxy = proxy
+        end
+        if username && password
+          http.auth.basic username, password
+        end
+      end
+    end
+    
+    
+    def soap_actions
+      @client.wsdl.soap_actions
+    end
+    
+
+    def selectMembers(args)
+      response = @client.request :wsdl, :select_members do |soap|
+        soap.body = { "FilterCriteriaArray" => {'item' => args} }
+      end
+      response.to_hash[:select_members_response][:return]
+    end
+
+    
+    def createSingleMember(email, name, list_name)
+      response = @client.request :wsdl, :create_single_member do |soap|
+        soap.body = { "EmailAddress" => email,
+                      "FullName" => name || "",
+                      "ListName" => list_name}
+      end
+      response.to_hash[:create_single_member_response][:return].to_i
+    end
+
+    
+    def deleteMembers(args)
+      response = @client.request :wsdl, :delete_members do |soap|
+        soap.body = { "FilterCriteriaArray" => {'item' => args} }
+      end
+      response.to_hash[:delete_members_response][:return].to_i
+    end
+    
+
+    def unsubscribe(list_name, id, email)
+      response = @client.request :wsdl, :unsubscribe do |soap|
+        soap.body = { 'SimpleMemberStructArrayIn' => { 
+                        'item' => {
+                          'ListName' => list_name,
+                          'MemberID' => id,
+                          'EmailAddress' => email }}}
+      end
+      response.to_hash[:unsubscribe_response][:return]
+    end
+
+    
+    def updateMemberDemographics(list_name, id, email, demographics)
+      response = @client.request :wsdl, :update_member_demographics do |soap|
+        soap.body = { "SimpleMemberStructIn" => {
+                        'ListName' => list_name,
+                        'MemberID' => id,
+                        'EmailAddress' => email},
+                      "DemographicsArray" => {'item' => demographics} }
+      end
+      response.to_hash[:update_member_demographics_response][:return]
+    end
+    
+
+    def selectContent(args)
+      response = @client.request :wsdl, :select_content do |soap|
+        soap.body = { "FilterCriteriaArray" => {'item' => args} }
+      end
+      response.to_hash[:select_content_response][:return]
+    end  
+
+    
+    def selectLists(list_name, site_name)
+      response = @client.request :wsdl, :select_lists do |soap|
+        soap.body = { "ListName" => list_name,
+                      "SiteName" => site_name}
+      end
+      if response.to_hash[:select_lists_response]
+        return response.to_hash[:select_lists_response][:return]
+      else
+        return nil
+      end
+    end
+    
+
+    def importContent(content_id)
+      response = @client.request :wsdl, :import_content do |soap|
+        soap.body = { "ContentID" => content_id }
+      end
+      response.to_hash[:import_content_response][:return]
+    end
+
+
+    def sendMailingDirect(email_addresses=[], member_ids=[], mail)
+      response = @client.request :wsdl, :send_mailing_direct do |soap|
+        soap.body = { "EmailAddressArray" => {:item => email_addresses},
+                      "MemberIDArray" => {:item => member_ids},
+                      "MailingStructIn" => mail }
+      end
+      response.to_hash[:send_mailing_direct_response][:return]
+    end
+
+  end
+end
+

data/lib/postal/mailing.rb

@@ -4,7 +4,7 @@ module Postal
     class << self
       
       def import(content_id)
-        mail = Postal.driver.importContent(content_id)
+        mail = Mailing.new(Postal.driver.importContent(content_id))
         return mail
       end
       
@@ -106,17 +106,17 @@ module Postal
         @mailing = args[:mailing]
       else
         @subject = args[:mailing].subject
-        @is_html_section_encoded = args[:mailing].isHtmlSectionEncoded
-        @html_section_encoding = args[:mailing].htmlSectionEncoding
-        @html_message = args[:mailing].htmlMessage
-        @char_set_id = args[:mailing].charSetID
-        @is_text_section_encoded = args[:mailing].isTextSectionEncoded
-        @text_section_encoding = args[:mailing].textSectionEncoding
+        @is_html_section_encoded = args[:mailing].is_html_section_encoded
+        @html_section_encoding = args[:mailing].html_section_encoding
+        @html_message = args[:mailing].html_message
+        @char_set_id = args[:mailing].char_set_id
+        @is_text_section_encoded = args[:mailing].is_text_section_encoded
+        @text_section_encoding = args[:mailing].text_section_encoding
         @title = args[:mailing].title
-        @text_message = args[:mailing].textMessage
+        @text_message = args[:mailing].text_message
         @attachments = args[:mailing].attachments
         @from = args[:mailing].from
-        @additional_headers = args[:mailing].additionalHeaders
+        @additional_headers = args[:mailing].additional_headers
         @mailing = args[:mailing]
       end
     end
@@ -127,48 +127,73 @@ module Postal
       if valid?
         
         # are we sending to a list of email addresses or member ids
-        case @to.to_a.first
+        case [@to].flatten.first
         when ::String
-          emails = @to.to_a
+          emails = [@to].flatten
           member_ids = []
         when ::Fixnum
           emails = []
-          member_ids = @to.to_a
+          member_ids = [@to].flatten
         end
         
         if @mailing.nil?
-          mail = Postal::Lmapi::MailingStruct.new(:additionalHeaders => @additional_headers, 
-                                                  :attachments => @attachments, 
-                                                  :bypassModeration => @bypass_moderation, 
-                                                  :campaign => @campaign, 
-                                                  :charSetID => @char_set_id, 
-                                                  :detectHtml => @detect_html, 
-                                                  :dontAttemptAfterDate => @dont_attempt_after_date, 
-                                                  :enableRecovery => @enable_recovery, 
-                                                  :from => @from, 
-                                                  :htmlMessage => @html_message, 
-                                                  :htmlSectionEncoding => @html_section_encoding, 
-                                                  :isHtmlSectionEncoded => @is_html_section_encoded, 
-                                                  :isTextSectionEncoded => @is_text_section_encoded,
-                                                  :listName => @list_name,
-                                                  :recencyNumberOfMailings => @recency_number_of_mailings,
-                                                  :recencyWhich => @recency_which,
-                                                  :replyTo => @reply_to,
-                                                  :resendAfterDays => @resend_after_days,
-                                                  :sampleSize => @sample_size,
-                                                  :scheduledMailingDate => @scheduled_mailing_date,
-                                                  :subject => @subject,
-                                                  :textMessage => @text_message,
-                                                  :textSectionEncoding => @text_section_encoding,
-                                                  :title => @title,
-                                                  # :to => @to,
-                                                  :trackOpens => @track_opens,
-                                                  :rewriteDateWhenSent => @rewrite_date_when_sent )
+          mail = { 'AdditionalHeaders' => @additional_headers, 
+                   'Attachments' => @attachments, 
+                   'BypassModeration' => @bypass_moderation, 
+                   'Campaign' => @campaign, 
+                   'CharSetID' => @char_set_id, 
+                   'DetectHtml' => @detect_html, 
+                   'DontAttemptAfterDate' => @dont_attempt_after_date, 
+                   'EnableRecovery' => @enable_recovery, 
+                   'From' => @from, 
+                   'HtmlMessage' => @html_message, 
+                   'HtmlSectionEncoding' => @html_section_encoding, 
+                   'IsHtmlSectionEncoded' => @is_html_section_encoded, 
+                   'IsTextSectionEncoded' => @is_text_section_encoded,
+                   'ListName' => @list_name,
+                   'RecencyNumberOfMailings' => @recency_number_of_mailings,
+                   'RecencyWhich' => @recency_which,
+                   'ReplyTo' => @reply_to,
+                   'ResendAfterDays' => @resend_after_days,
+                   'SampleSize' => @sample_size,
+                   'ScheduledMailingDate' => @scheduled_mailing_date,
+                   'Subject' => @subject,
+                   'TextMessage' => @text_message,
+                   'TextSectionEncoding' => @text_section_encoding,
+                   'Title' => @title,
+                   # :to => @to,
+                   'TrackOpens' => @track_opens,
+                   'RewriteDateWhenSent' => @rewrite_date_when_sent }
         
           return Postal.driver.sendMailingDirect(emails,member_ids,mail)
         else
-          mail = Postal::Lmapi::MailingStruct.new(@mailing)
-          mail.listName = @list_name || Postal.options[:list_name]
+          mail = { 'AdditionalHeaders' => @mailing.additional_headers, 
+                   'Attachments' => @mailing.attachments, 
+                   'BypassModeration' => @mailing.bypass_moderation, 
+                   'Campaign' => @mailing.campaign, 
+                   'CharSetID' => @mailing.char_set_id, 
+                   'DetectHtml' => @mailing.detect_html, 
+                   'DontAttemptAfterDate' => @mailing.dont_attempt_after_date, 
+                   'EnableRecovery' => @mailing.enable_recovery, 
+                   'From' => @mailing.from, 
+                   'HtmlMessage' => @mailing.html_message, 
+                   'HtmlSectionEncoding' => @mailing.html_section_encoding, 
+                   'IsHtmlSectionEncoded' => @mailing.is_html_section_encoded, 
+                   'IsTextSectionEncoded' => @mailing.is_text_section_encoded,
+                   'RecencyNumberOfMailings' => @mailing.recency_number_of_mailings,
+                   'RecencyWhich' => @mailing.recency_which,
+                   'ReplyTo' => @mailing.reply_to,
+                   'ResendAfterDays' => @mailing.resend_after_days,
+                   'SampleSize' => @mailing.sample_size,
+                   'ScheduledMailingDate' => @mailing.scheduled_mailing_date,
+                   'Subject' => @mailing.subject,
+                   'TextMessage' => @mailing.text_message,
+                   'TextSectionEncoding' => @mailing.text_section_encoding,
+                   'Title' => @mailing.title,
+                   # :to => @to,
+                   'TrackOpens' => @mailing.track_opens,
+                   'RewriteDateWhenSent' => @mailing.rewrite_date_when_sent,
+                   'ListName' => @mailing.list_name || Postal.options[:list_name] }
           return Postal.driver.sendMailingDirect(emails,member_ids,mail)
         end