mad_mimi 0.0.1 → 0.0.2

data/Gemfile.lock

@@ -1,24 +1,24 @@
 PATH
   remote: .
   specs:
-    mad_mimi (0.0.1)
-      faraday (= 0.5.4)
-      faraday_middleware (= 0.3.1)
-      multi_xml (= 0.2.0)
+    mad_mimi (0.0.2)
+      faraday (= 0.5.5)
+      faraday_middleware (= 0.3.2)
+      multi_xml (= 0.2.1)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    addressable (2.2.3)
+    addressable (2.2.4)
     crack (0.1.8)
     diff-lcs (1.1.2)
-    faraday (0.5.4)
-      addressable (~> 2.2.2)
+    faraday (0.5.5)
+      addressable (~> 2.2.4)
       multipart-post (~> 1.1.0)
       rack (>= 1.1.0, < 2)
-    faraday_middleware (0.3.1)
-      faraday (~> 0.5.3)
-    multi_xml (0.2.0)
+    faraday_middleware (0.3.2)
+      faraday (~> 0.5.4)
+    multi_xml (0.2.1)
     multipart-post (1.1.0)
     rack (1.2.1)
     rspec (2.4.0)

data/README.rdoc

@@ -1,6 +1,71 @@
-= MadMimi
+= The MadMimi Ruby Gem
 
-Manage your MadMimi audience
+A Ruby wrapper for the MadMimi API. Deliver emails and manage your MadMimi audience.
+
+== Installation
+
+  gem install mad_mimi
+
+== Documentation
+
+  http://rdoc.info/gems/mad_mimi
+
+== Usage Examples
+
+  require "rubygems"
+  require "mad_mimi"
+
+  # Sets the MadMimi configuration options. Best used by passing a block.
+  MadMimi.configure do |config|
+    config.username = "YourMadMimiEmailAddress"
+    config.api_key  = "YourMadMimiApiKey"
+  end
+
+  # Sending transactional email
+  MadMimi.mailer.mail({ :promotion_name => "Welcome", :recipients => "Ozéias Sant'Ana <oz.santana@gmail.com>" })
+
+  # Performs an audience search and returns the up to the first 100 results.
+  MadMimi.audience.search
+
+  # Get Audience Members
+  MadMimi.audience.members
+
+  # Get all Audience Lists
+  MadMimi.audience.lists
+
+  # Add Audience List Membership
+  MadMimi.audience.add_to_list('Clients', {:first_name => 'Ozéias', :last_name => 'Santana', :email => 'oz.santana@gmail.com'})
+
+  # Remove Audience List Membership
+  MadMimi.audience.remove_from_list('Clients', 'oz.santana@gmail.com')
+
+  # Suppress an Audience Member
+  MadMimi.audience.suppress('oz.santana@gmail.com')
+
+== Contributing
+
+In the spirit of {free software}[http://www.fsf.org/licensing/essays/free-sw.html], *everyone* is encouraged to help improve this project.
+
+Here are some ways you can contribute:
+
+* by using alpha, beta, and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code (no patch is too small: fix typos, add comments, clean up inconsistent whitespace)
+* by refactoring code
+* by closing {issues}[https://github.com/ozeias/mad_mimi/issues]
+* by reviewing patches
+
+== Submitting an Issue
+
+We use the {GitHub issue tracker}[https://github.com/ozeias/mad_mimi/issues] to track bugs and
+features. Before submitting a bug report or feature request, check to make sure it hasn't already
+been submitted. You can indicate support for an existing issuse by voting it up. When submitting a
+bug report, please include a {Gist}[http://gist.github.com/] that includes a stack trace and any
+details that may be necessary to reproduce the bug, including your gem version, Ruby version, and
+operating system. Ideally, a bug report should include a pull request with failing specs.
 
 == Copyright
 

data/lib/mad_mimi.rb

@@ -1,6 +1,7 @@
 require "singleton"
 
 require "mad_mimi/audience"
+require "mad_mimi/mailer"
 require "mad_mimi/config"
 
 module MadMimi #:nodoc
@@ -10,8 +11,8 @@ module MadMimi #:nodoc
     # Example:
     #
     #   MadMimi.configure do |config|
-    #     config.username = "emailaddress"
-    #     config.api_key  = "api_key"
+    #     config.username = "YourMadMimiEmailAddress"
+    #     config.api_key  = "YourMadMimiApiKey"
     #   end
     #
     # Returns:
@@ -33,12 +34,16 @@ module MadMimi #:nodoc
       }
     end
 
-    def api_url
-      'http://api.madmimi.com'
+    def api_url(ssl = false)
+      "#{ssl ? 'https' : 'http'}://api.madmimi.com"
     end
 
     def audience
       MadMimi::Audience.new
     end
+
+    def mailer
+      MadMimi::Mailer.new
+    end
   end
 end

data/lib/mad_mimi/audience.rb

@@ -1,7 +1,22 @@
 require File.expand_path('../request', __FILE__)
+
 module MadMimi #:nodoc
   class Audience #:nodoc
     include Request
+    # Search
+    #
+    # Performs an audience search and returns the up to the first 100 results.
+    #
+    # == Optional parameters are:
+    # * <tt>:query</tt> -- The query parameter can be any search criteria you can use in the interface. A common use would be to use this function to get all of a member’s details by sending the email address as the query.
+    # * <tt>:raw</tt> -- if you want to return all users, regardless of suppression status, add the raw=true parameter on the end of your query.
+    # * <tt>:add_list</tt> -- You can add the results of the search to a new or existing list by passing an additional add_list parameter with the name of the list.
+    #
+    # See {Search}[http://madmimi.com/developer/lists/search]
+    def search(options = {})
+      response = get('/audience_members/search.xml', options)
+      response ? response["audience"]["member"] : response
+    end
 
     # Get Audience Members
     #
@@ -14,8 +29,8 @@ module MadMimi #:nodoc
     #
     # See {Get Audience Members}[http://madmimi.com/developer/lists]
     def members(options = {})
-      members = get('/audience_members')
-      members ? members["audience"]["member"] : members
+      response = get('/audience_members')
+      response ? response["audience"]["member"] : response
     end
 
     # Get all Audience Lists
@@ -24,8 +39,8 @@ module MadMimi #:nodoc
     #
     # See {Get all Audience Lists}[http://madmimi.com/developer/lists/get-all-audience-lists]
     def lists
-      lists = get('/audience_lists/lists.xml')
-      lists ? lists["lists"]["list"] : lists
+      response = get('/audience_lists/lists.xml')
+      response ? response["lists"]["list"] : response
     end
 
     # Add Audience List Membership

data/lib/mad_mimi/mailer.rb

@@ -0,0 +1,36 @@
+require File.expand_path('../request', __FILE__)
+
+module MadMimi #:nodoc
+  # The Mailer API that lets you use Mad Mimi to send your transactional emails like welcome letters,
+  # password resets, and account activations. You can also use it to programmatically send promotional
+  # emails to an audience list.
+
+  class Mailer
+    include Request
+
+    # Sending transactional email
+    #
+    # Sends a single transactional email to the recipient. Returns a unique transaction id if successful.
+    #
+    # == Required parameters are:
+    # * <tt>:promotion_name</tt> -- The name of the promotion Mimi will send. For +raw_html+ or +raw_plain_text+ promotions, MadMimi will automatically create or update the promotion in your account.
+    # * <tt>:recipients</tt> -- The recipient (singular although the parameter name is plural) again just the email or in +Display Name <email@domain.com>+ format.
+    # * <tt>:body</tt> -- Required if you have placeholders. YAML encoded replacements for any {placeholders} in your promotion.
+    #
+    # == Optional parameters are:
+    # * <tt>:subject</tt> -- The subject of the email. Will default to the +promotion_name+ if not supplied.
+    # * <tt>:from</tt> -- The from address. Just the email address or in +Display Name <email@domain.com>+ format.
+    # * <tt>:bcc</tt> -- An email address to BCC. Just the email address.
+    # * <tt>:raw_html</tt> -- The custom HTML to send. Can be used on its own or in conjunction with +raw_plain_text+.
+    # * <tt>:raw_plain_text</tt> -- The custom plain text to send. Can be used on its own or in conjunction with +raw_html+.
+    # * <tt>:check_suppressed</tt> -- Checks if the recipient is suppressed and does not send if so (default: on).
+    # * <tt>:track_links</tt> -- Enable or disable link tracking in HTML promotions (default: on).
+    # * <tt>:hidden</tt> -- Creates the promotion as a hidden promotion so as not to clutter up your web interface (default: off).
+    #
+    # See {Sending transactional email with the Mailer API}[http://madmimi.com/developer/mailer/transactional]
+    def mail(options = {})
+      options[:check_suppressed] ||= true
+      post("/mailer", options, true, true)
+    end
+  end
+end

data/lib/mad_mimi/request.rb

@@ -8,13 +8,13 @@ module MadMimi
       request(:get, path, options, raw)
     end
 
-    def post(path, options={}, raw = false)
-      request(:post, path, options, raw)
+    def post(path, options={}, raw = false, ssl = false)
+      request(:post, path, options, raw, ssl)
     end
 
     private
-      def request(method, path, options, raw = false)
-        response = connection(raw).send(method) do |request|
+      def request(method, path, options, raw = false, ssl = false)
+        response = connection(raw, ssl).send(method) do |request|
           options = options.merge(MadMimi.authentication)
           case method
           when :get
@@ -27,11 +27,11 @@ module MadMimi
         raw ? response : response.body
       end
 
-      def connection(raw = false)
+      def connection(raw = false, ssl = false)
         options = {
           :headers => {'Accept' => "application/xml", 'User-Agent' => 'MadMimi Gem'},
           :ssl => { :verify => false },
-          :url => MadMimi.api_url
+          :url => MadMimi.api_url(ssl)
         }
 
         Faraday::Connection.new(options) do |builder|

data/lib/mad_mimi/version.rb

@@ -1,3 +1,3 @@
 module MadMimi
-  VERSION = "0.0.1" unless defined?(::MadMimi::VERSION)
+  VERSION = "0.0.2" unless defined?(::MadMimi::VERSION)
 end

data/mad_mimi.gemspec

@@ -13,12 +13,12 @@ Gem::Specification.new do |s|
 
   s.summary     = %q{Manage your MadMimi audience}
 
-  s.required_rubygems_version = Gem::Requirement.new('>= 1.3.7') if s.respond_to? :required_rubygems_version=
+  s.required_rubygems_version = Gem::Requirement.new('>= 1.3.6') if s.respond_to? :required_rubygems_version=
 
-  s.add_runtime_dependency 'faraday',     '0.5.4'
+  s.add_runtime_dependency 'faraday',     '0.5.5'
 
-  s.add_dependency 'faraday_middleware',  '0.3.1'
-  s.add_dependency 'multi_xml',           '0.2.0'
+  s.add_dependency 'faraday_middleware',  '0.3.2'
+  s.add_dependency 'multi_xml',           '0.2.1'
 
   s.add_development_dependency 'rspec',   '~> 2.4.0'
   s.add_development_dependency 'webmock', '~> 1.6.2'

data/spec/fixtures/audience_search.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<audience>
+  <member suppressed="false">
+    <first_name>Ozéias</first_name>
+    <last_name>Sant'ana</last_name>
+    <email>oz.santana@gmail.com</email>
+    <created_at>Tue Jan 24 11:05:25 -0400 2011</created_at>
+    <title>Mrs</title>
+    <country>BR</country>
+    <confirmed/>
+    <twitter>@ozeias</twitter>
+    <friend_name>Oz</friend_name>
+    <lists>
+      <list>dev</list>
+    </lists>
+  </member>
+  <member suppressed="false">
+    <first_name>Mad</first_name>
+    <last_name>Mimi</last_name>
+    <email>support@madmimi.com</email>
+    <created_at>Tue Apr 20 14:30:25 -0400 2010</created_at>
+    <city/>
+    <phone/>
+    <company>Mad Mimi</company>
+    <title>Mrs</title>
+    <address/>
+    <state/>
+    <zip/>
+    <country>US</country>
+    <confirmed/>
+    <birthday/>
+    <categories/>
+    <friend_name>Marc</friend_name>
+    <lists>
+      <list>test</list>
+    </lists>
+  </member>
+</audience>

data/spec/fixtures/audience_search_query.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<audience>
+  <member suppressed="false">
+    <first_name>Ozéias</first_name>
+    <last_name>Sant'ana</last_name>
+    <email>oz.santana@gmail.com</email>
+    <created_at>Tue Jan 24 11:05:25 -0400 2011</created_at>
+    <title>Mrs</title>
+    <country>BR</country>
+    <confirmed/>
+    <twitter>@ozeias</twitter>
+    <friend_name>Oz</friend_name>
+    <lists>
+      <list>dev</list>
+    </lists>
+  </member>
+</audience>

data/spec/mad_mimi/audience_spec.rb

@@ -14,6 +14,29 @@ describe MadMimi::Audience do
     connection.should == "http://api.madmimi.com/"
   end
 
+  describe ".search" do
+    before do
+      stub_get('/audience_members/search.xml').
+        with(:headers => {'Accept'=>'application/xml', 'User-Agent'=>'MadMimi Gem'}).
+        to_return(:status => 200, :body => fixture("audience_search.xml"), :headers => {:content_type => "application/xml; charset=utf-8"})
+
+      stub_get('/audience_members/search.xml', { :query => 'oz.santana@gmail.com'}).
+        with(:headers => {'Accept'=>'application/xml', 'User-Agent'=>'MadMimi Gem'}).
+        to_return(:status => 200, :body => fixture("audience_search_query.xml"), :headers => {:content_type => "application/xml; charset=utf-8"})
+    end
+
+    it "should get all audience members" do
+      MadMimi.audience.search.should == [
+        { "created_at"=>"Tue Jan 24 11:05:25 -0400 2011", "confirmed"=>nil, "country"=>"BR", "title"=>"Mrs", "suppressed"=>"false", "lists"=>{"list"=>"dev"}, "friend_name"=>"Oz", "last_name"=>"Sant'ana", "twitter"=>"@ozeias", "email"=>"oz.santana@gmail.com", "first_name"=>"Ozéias" },
+        { "address"=>nil, "company"=>"Mad Mimi", "city"=>nil, "zip"=>nil, "created_at"=>"Tue Apr 20 14:30:25 -0400 2010", "confirmed"=>nil, "country"=>"US", "title"=>"Mrs", "suppressed"=>"false", "lists"=>{"list"=>"test"}, "friend_name"=>"Marc", "birthday"=>nil, "phone"=>nil, "last_name"=>"Mimi", "categories"=>nil, "state"=>nil, "email"=>"support@madmimi.com", "first_name"=>"Mad" }
+      ]
+    end
+
+    it "should set the query" do
+      MadMimi.audience.search({:query => 'oz.santana@gmail.com'}).should == { "created_at"=>"Tue Jan 24 11:05:25 -0400 2011", "confirmed"=>nil, "country"=>"BR", "title"=>"Mrs", "suppressed"=>"false", "lists"=>{"list"=>"dev"}, "friend_name"=>"Oz", "last_name"=>"Sant'ana", "twitter"=>"@ozeias", "email"=>"oz.santana@gmail.com", "first_name"=>"Ozéias" }
+    end
+  end
+
   describe ".members" do
     before do
       stub_get('/audience_members').

data/spec/mad_mimi/mailer_spec.rb

@@ -0,0 +1,27 @@
+require 'spec/spec_helper'
+
+describe MadMimi::Mailer do
+  before (:all) do
+    MadMimi.configure do |config|
+      config.username = "email@example.com"
+      config.api_key  = "api_key"
+    end
+  end
+
+  describe ".mail" do
+    before do
+      stub_post('/mailer', true).
+        with(:headers => {'Accept'=>'application/xml', 'Content-Type'=>'application/x-www-form-urlencoded', 'User-Agent'=>'MadMimi Gem'}).
+        to_return(:status => 200, :body => "2875078090", :headers => {:content_type => "text/html; charset=utf-8"})
+    end
+
+    it "should remove audience list membership" do
+      MadMimi.mailer.mail({ :promotion_name => "Welcome to Acme Widgets", :recipients => "Ozéias Sant'Ana <oz.santana@gmail.com>" })
+
+      a_post('/mailer', true).
+        with(:body => 'username=email%40example.com&promotion_name=Welcome+to+Acme+Widgets&recipients=Oz%C3%A9ias+Sant%27Ana+%3Coz.santana%40gmail.com%3E&api_key=api_key&check_suppressed=true').
+        with(:headers => {'Accept'=>'application/xml', 'Content-Type'=>'application/x-www-form-urlencoded', 'User-Agent'=>'MadMimi Gem'}).
+        should have_been_made
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -4,17 +4,17 @@ require 'rspec'
 require 'webmock/rspec'
 include WebMock::API
 
-def a_post(path)
-  a_request(:post, MadMimi.api_url + path)
+def a_post(path, ssl = false)
+  a_request(:post, MadMimi.api_url(ssl) + path)
 end
 
-def stub_get(path)
-  path = path + '?' + parameterize(MadMimi.authentication)
+def stub_get(path, options = {})
+  path = path + '?' + parameterize(options.merge(MadMimi.authentication))
   stub_request(:get, MadMimi.api_url + path)
 end
 
-def stub_post(path)
-  stub_request(:post, MadMimi.api_url + path)
+def stub_post(path, ssl = false)
+  stub_request(:post, MadMimi.api_url(ssl) + path)
 end
 
 def fixture_path

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mad_mimi
 version: !ruby/object:Gem::Version 
-  hash: 29
-  prerelease: false
+  hash: 27
+  prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - "Oz\xC3\xA9ias Sant'ana"
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-23 00:00:00 -02:00
+date: 2011-02-11 00:00:00 -02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,12 +26,12 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        hash: 3
+        hash: 1
         segments: 
         - 0
         - 5
-        - 4
-        version: 0.5.4
+        - 5
+        version: 0.5.5
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -42,12 +42,12 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        hash: 17
+        hash: 23
         segments: 
         - 0
         - 3
-        - 1
-        version: 0.3.1
+        - 2
+        version: 0.3.2
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
@@ -58,12 +58,12 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        hash: 23
+        hash: 21
         segments: 
         - 0
         - 2
-        - 0
-        version: 0.2.0
+        - 1
+        version: 0.2.1
   type: :runtime
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
@@ -117,12 +117,16 @@ files:
 - lib/mad_mimi.rb
 - lib/mad_mimi/audience.rb
 - lib/mad_mimi/config.rb
+- lib/mad_mimi/mailer.rb
 - lib/mad_mimi/request.rb
 - lib/mad_mimi/version.rb
 - mad_mimi.gemspec
 - spec/fixtures/audience_lists.xml
 - spec/fixtures/audience_members.xml
+- spec/fixtures/audience_search.xml
+- spec/fixtures/audience_search_query.xml
 - spec/mad_mimi/audience_spec.rb
+- spec/mad_mimi/mailer_spec.rb
 - spec/mad_mimi_spec.rb
 - spec/spec_helper.rb
 has_rdoc: true
@@ -148,22 +152,25 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 21
+      hash: 23
       segments: 
       - 1
       - 3
-      - 7
-      version: 1.3.7
+      - 6
+      version: 1.3.6
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.4.2
 signing_key: 
 specification_version: 3
 summary: Manage your MadMimi audience
 test_files: 
 - spec/fixtures/audience_lists.xml
 - spec/fixtures/audience_members.xml
+- spec/fixtures/audience_search.xml
+- spec/fixtures/audience_search_query.xml
 - spec/mad_mimi/audience_spec.rb
+- spec/mad_mimi/mailer_spec.rb
 - spec/mad_mimi_spec.rb
 - spec/spec_helper.rb