letter-mx 1.0.0

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3-p429

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in letter-mx.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,47 @@
+PATH
+  remote: .
+  specs:
+    letter-mx (1.0.0)
+      activeresource
+      httparty
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (4.0.0)
+      activesupport (= 4.0.0)
+      builder (~> 3.1.0)
+    activeresource (4.0.0)
+      activemodel (~> 4.0)
+      activesupport (~> 4.0)
+      rails-observers (~> 0.1.1)
+    activesupport (4.0.0)
+      i18n (~> 0.6, >= 0.6.4)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    atomic (1.1.14)
+    builder (3.1.4)
+    httparty (0.12.0)
+      json (~> 1.8)
+      multi_xml (>= 0.5.2)
+    i18n (0.6.5)
+    json (1.8.1)
+    minitest (4.7.5)
+    multi_json (1.8.2)
+    multi_xml (0.5.5)
+    rails-observers (0.1.2)
+      activemodel (~> 4.0)
+    rake (10.1.0)
+    thread_safe (0.1.3)
+      atomic
+    tzinfo (0.3.38)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  letter-mx!
+  rake

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Bjoern B. Dorra
+
+MIT License
+
+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.md

@@ -0,0 +1,269 @@
+# Letter::Mx
+
+The Letter-MX-GEM is a lightweight GEM for accessing the Letter.MX subscriber REST web services.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+`gem 'letter-mx'`
+
+And then execute:
+
+`$ bundle`
+
+Or install it yourself as:
+
+`$ gem install letter-mx`
+
+## Usage
+
+### Basics
+
+```
+# Instantiate the API that is ready to make calls to Letter.mx
+lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
+
+# Call one of the provided methods (e.g. list_subscribers)
+response = lettermx.list_subscribers(query: {offset: 0, limit: 3})
+
+# Get data from the response
+subscribers = response.data
+
+# Print useful http informations
+puts "--- HTTP -----------------------------------------------------------------------"
+puts "Status: #{response.http_status}"
+puts "Body:"
+puts response.http_body
+puts
+
+# Iterate over the result and print details of each subscriber
+subscribers.each do |subscriber|
+  puts "--- Subscriber -----------------------------------------------------------------"
+  puts "ID.................: #{subscriber["id"]}"
+  puts "User ID............: #{subscriber["user_id"]}"
+  puts "Key................: #{subscriber["key"]}"
+  puts "Email..............: #{subscriber["email"]}"
+  puts "Firstname..........: #{subscriber["first_name"]}"
+  puts "Lastname...........: #{subscriber["last_name"]}"
+  puts "Optional 1.........: #{subscriber["optional_1"]}"
+  puts "Optional 2.........: #{subscriber["optional_2"]}"
+  puts "Optional 3.........: #{subscriber["optional_3"]}"
+  puts "Status.............: #{subscriber["status"]}"
+  puts "Created At.........: #{subscriber["created_at"]}"
+  puts "Updated At.........: #{subscriber["updated_at"]}"
+  puts "Soft Bounce Count..: #{subscriber["soft_bounce_count"]}"
+  puts
+end
+```
+
+### Get Subscribers (`GET /api/contacts`)
+
+```
+lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
+response = lettermx.list_subscribers
+puts response.data
+```
+
+```
+[
+  {
+    "id"=>100, 
+    "user_id"=>1, 
+    "key"=>"ojgcrmjs", 
+    "email"=>"email1@example.com", 
+    "first_name"=>nil, 
+    "last_name"=>nil, 
+    "optional_1"=>nil, 
+    "optional_2"=>nil, 
+    "optional_3"=>nil, 
+    "status"=>"active", 
+    "created_at"=>"2013-11-09T07:43:48.000+01:00", 
+    "updated_at"=>"2013-11-09T07:43:48.000+01:00", 
+    "soft_bounce_count"=>0
+  }, 
+  {
+    "id"=>101, 
+    "user_id"=>1, 
+    "key"=>"jyyazhbl", 
+    "email"=>"email2@example.com", 
+    "first_name"=>nil, 
+    "last_name"=>nil, 
+    "optional_1"=>nil, 
+    "optional_2"=>nil, 
+    "optional_3"=>nil, 
+    "status"=>"active", 
+    "created_at"=>"2013-11-11T12:41:48.000+01:00", 
+    "updated_at"=>"2013-11-11T12:41:48.000+01:00", 
+    "soft_bounce_count"=>0
+  },
+  ...
+]
+```
+
+### Count Subscribers (`GET /api/contacts/count`)
+
+```
+lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
+response = lettermx.count_subscribers
+puts response.data
+```
+
+```
+{
+  "count"=>5
+}
+```
+
+### Get Subscriber (`GET /api/contacts/100`)
+
+```
+lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
+response = lettermx.get_subscribers(100)
+puts response.data
+```
+
+```
+{
+  "id"=>100, 
+  "user_id"=>1, 
+  "key"=>"ojgcrmjs", 
+  "email"=>"email1@example.com", 
+  "first_name"=>nil, 
+  "last_name"=>nil, 
+  "optional_1"=>nil, 
+  "optional_2"=>nil, 
+  "optional_3"=>nil, 
+  "status"=>"active", 
+  "created_at"=>"2013-11-09T07:43:48.000+01:00", 
+  "updated_at"=>"2013-11-09T07:43:48.000+01:00", 
+  "soft_bounce_count"=>0
+}
+```
+
+### Add Subscriber (`POST /api/contacts`)
+
+```
+lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
+
+new_subscriber = {
+  email: "john.doe@example.com",
+  first_name: "John",
+  last_name: "Doe"
+}
+
+response = lettermx.add_subscriber(new_subscriber)
+puts response.data
+```
+
+```
+{
+  "id": 110,
+  "user_id": 1,
+  "key": "tbythqbn",
+  "email": "john.doe@example.com",
+  "first_name": "John",
+  "last_name": "Doe",
+  "optional_1": null,
+  "optional_2": null,
+  "optional_3": null,
+  "status": "unconfirmed",
+  "created_at": "2013-11-14T15:01:48.000+01:00",
+  "updated_at": "2013-11-14T15:01:48.000+01:00",
+  "soft_bounce_count": 0
+}
+```
+
+### Update Subscriber (`PUT /api/contacts/100`)
+
+```
+lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
+
+existing_subscriber = {
+  first_name: "John",
+  last_name: "Doe"
+}
+
+response = lettermx.update_subscriber(100, existing_subscriber)
+puts response.data
+```
+
+```
+{
+  "id"=>100, 
+  "user_id"=>1, 
+  "key"=>"ojgcrmjs", 
+  "email"=>"email1@example.com", 
+  "first_name"=>"John", 
+  "last_name"=>"Doe", 
+  "optional_1"=>nil, 
+  "optional_2"=>nil, 
+  "optional_3"=>nil, 
+  "status"=>"active", 
+  "created_at"=>"2013-11-09T07:43:48.000+01:00", 
+  "updated_at"=>"2013-11-09T07:43:48.000+01:00", 
+  "soft_bounce_count"=>0
+}
+```
+
+### Remove Subscriber (`DELETE /api/contacts/100`)
+
+```
+lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
+response = lettermx.remove_subscriber(100)
+puts response.data
+```
+
+```
+{
+  "id"=>100, 
+  "user_id"=>1, 
+  "key"=>"ojgcrmjs", 
+  "email"=>"email1@example.com", 
+  "first_name"=>"John", 
+  "last_name"=>"Doe", 
+  "optional_1"=>nil, 
+  "optional_2"=>nil, 
+  "optional_3"=>nil, 
+  "status"=>"deleted", 
+  "created_at"=>"2013-11-09T07:43:48.000+01:00", 
+  "updated_at"=>"2013-11-09T07:43:48.000+01:00", 
+  "soft_bounce_count"=>0
+}
+```
+
+### Get API limit (default) (`GET /api/contacts/limit-default`)
+
+```
+lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
+response = lettermx.subscribers_api_limit_default
+puts response.data
+```
+
+```
+{
+  "limit_default"=>250
+}
+```
+
+### Get API limit (max) (`GET /api/contacts/limit-max`)
+
+```
+lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
+response = lettermx.subscribers_api_limit_max
+puts response.data
+```
+
+```
+{
+  "limit_max"=>3000
+}
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/RELEASING

@@ -0,0 +1,4 @@
+Releasing Letter.MX API GEM
+
+  $ gem build letter_mx.gemspec
+  $ gem push letter_mx-X.Y.Z.gem

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/letter_mx.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'letter_mx/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "letter-mx"
+  spec.version       = LetterMX::VERSION
+  spec.authors       = ["Bjoern B. Dorra", "Eduard Siebert"]
+  spec.description   = %q{The Letter-MX-GEM is a lightweight GEM for accessing the Letter.MX subscriber REST web services.}
+  spec.summary       = %q{The Letter-MX-GEM is a lightweight GEM for accessing the Letter.MX subscriber REST web services.}
+  spec.homepage      = "http://www.letter.mx"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/).delete_if{|e| e == "test.rb"}
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  # spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency("httparty")
+  spec.add_dependency("activeresource")
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/lib/letter_mx.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+require "letter_mx/version"
+require "letter_mx/api"
+require "letter_mx/subscriber"
+
+module LetterMX
+
+  class Error < StandardError; end
+  class SSLRequiredError < Error; end
+  class AuthenticationFailed < Error; end
+  class ListenFailed < Error; end
+
+end

data/lib/letter_mx/api.rb

@@ -0,0 +1,116 @@
+# encoding: utf-8
+
+require 'httparty'
+
+module LetterMX
+  #   connection = LetterMX::API.new( username: 'the_app_key', password: 'the_api_key' )
+  #   connection.add_subscriber( {
+  #                                 email: 'user@domain.com',
+  #                                 first_name: 'John',
+  #                                 last_name: 'Doe',
+  #                                 optional_1: 'Customer',
+  #                                 optional_2: 'Active',
+  #                                 optional_3: 'Male',
+  #                                 optin: false
+  #                             } )
+
+  class API
+
+    CONTENT_TYPES = {
+      json: "json",
+      # TODO: Implement XML
+      # xml: "xml"
+    }
+
+    # https://github.com/jnunemaker/httparty
+    include HTTParty
+    base_uri "www.letter.mx/api"
+
+    class ApiException < RuntimeError; end
+
+
+    def initialize(username, password, type=LetterMX::API::CONTENT_TYPES[:json])
+      raise ArgumentError, "First argument (username) must not be blank." if username.nil? || username.size == 0
+      raise ArgumentError, "Second argument (password) must not be blank." if password.nil? || password.size == 0
+      raise ArgumentError, "Third argument (type) must be on of #{LetterMX::API::CONTENT_TYPES.values}." unless LetterMX::API::CONTENT_TYPES.has_value?(type)
+
+      @auth = { username: username, password: password }
+      @type = type
+      @default_options = { basic_auth: @auth }
+
+      case @type
+      when LetterMX::API::CONTENT_TYPES[:json]
+        @default_options.merge!({
+          headers: {
+            "Accept" => "application/json",
+            "Content-Type" => "application/json; charset=utf-8"
+          }
+        })
+      # TODO: Implement XML
+      # when LetterMX::API::CONTENT_TYPES[:xml]
+      #   @default_options.merge!({
+      #     headers: {
+      #       "Accept" => "application/xml",
+      #       "Content-Type" => "application/xml"
+      #     }
+      #   })
+      end
+    end
+
+    def list_subscribers(options={})
+      options = @default_options.merge(options)
+      LetterMX::Subscriber.new(self.class.get("/contacts", options))
+    end
+
+    def count_subscribers(options={})
+      options = @default_options.merge(options)
+      LetterMX::Subscriber.new(self.class.get("/contacts/count", options))
+    end
+
+    def add_subscriber(subscriber={})
+      options = @default_options.clone
+      options.merge!(body: build_request_body({ contact: subscriber }))
+      LetterMX::Subscriber.new(self.class.post("/contacts", options))
+    end
+
+    def get_subscriber(id, options={})
+      options = @default_options.merge(options)
+      LetterMX::Subscriber.new(self.class.get("/contacts/#{id}", options))
+    end
+
+    def update_subscriber(id, subscriber={})
+      options = @default_options.clone
+      options.merge!(body: build_request_body({ contact: subscriber }))
+      LetterMX::Subscriber.new(self.class.put("/contacts/#{id}", options))
+    end
+
+    def remove_subscriber(id)
+      LetterMX::Subscriber.new(self.class.delete("/contacts/#{id}", @default_options))
+    end
+
+    def subscribers_api_limit_default(options={})
+      options = @default_options.merge(options)
+      LetterMX::Subscriber.new(self.class.get("/contacts/limit-default", options))
+    end
+
+    def subscribers_api_limit_max(options={})
+      options = @default_options.merge(options)
+      LetterMX::Subscriber.new(self.class.get("/contacts/limit-max", options))
+    end
+
+    private
+
+    def build_request_body(body)
+      if body
+        case @type
+        when LetterMX::API::CONTENT_TYPES[:json]
+          return body.to_json
+        # TODO: Implement XML
+        # when LetterMX::API::CONTENT_TYPES[:xml]
+        #   return body.to_xml
+        end
+      end
+    end
+  end
+
+end

data/lib/letter_mx/subscriber.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+module LetterMX
+  class Subscriber
+
+    attr_reader :http_response
+    attr_reader :http_status
+    attr_reader :http_body
+    attr_reader :data
+
+    def initialize(response)
+      @http_response = response
+
+      if @http_response
+        @http_status = @http_response.headers["status"] if @http_response.headers
+        @http_body = @http_response.body
+        @data = @http_response.parsed_response
+      end
+    end
+  end
+end

data/lib/letter_mx/version.rb

@@ -0,0 +1,4 @@
+# encoding: utf-8
+module LetterMX
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: letter-mx
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Bjoern B. Dorra
+- Eduard Siebert
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-11-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activeresource
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: The Letter-MX-GEM is a lightweight GEM for accessing the Letter.MX subscriber
+  REST web services.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .ruby-version
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- RELEASING
+- Rakefile
+- letter_mx.gemspec
+- lib/letter_mx.rb
+- lib/letter_mx/api.rb
+- lib/letter_mx/subscriber.rb
+- lib/letter_mx/version.rb
+homepage: http://www.letter.mx
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: The Letter-MX-GEM is a lightweight GEM for accessing the Letter.MX subscriber
+  REST web services.
+test_files: []