mailup 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b2954259506053f8acefde3cf2d6d9bfff76ffdc
+  data.tar.gz: b506fb4efd45263932edd677e6f155c761000401
+SHA512:
+  metadata.gz: b9463e8d8a5e7de85161f34ca75280b60ea46e3b1b72a81b994224147be3d7f0c20de7b4c563e7fc04659dd25979c4adb93f7dcd804ef9c54b51fb227e37560b
+  data.tar.gz: 5d59ab00556ffbc4a98da5da3fc57b4b8e9333f1113266e078f0f52b6a33bba782a8aea12292ecf1a5af29eab918c534ceef02a4f14a8c70b7f43334a66cc25e

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.ruby-version
+.rbenv-gemsets
+.rbenv-vars
+.rspec
+credentials.txt

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Brian Getting
+
+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,79 @@
+# Mailup Ruby
+
+A Ruby gem for interacting with the MailUp REST API.
+
+## Installation
+
+Install the gem directly:
+
+```ruby
+gem install mailup
+```
+
+Or, add this line to your application's Gemfile:
+
+```ruby
+gem 'mailup'
+```
+
+## Usage
+
+Be sure that you have OAuth2 tokens for the MailUp REST API before using this gem. If you are using [Omniauth](https://github.com/intridea/omniauth), there is a [MailUp strategy](https://github.com/tatemae-consultancy/omniauth-mailup) available.
+
+### Credentials
+
+Once you've gone through the OAuth process, and you have obtained your tokens, you need to provide your `client_id`, `client_secret` and OAuth2 tokens in a `credentials` hash to get started.
+
+```ruby
+require 'mailup'
+
+credentials = {
+  client_id: ENV['MAILUP_CLIENT_ID'],
+  client_secret: ENV['MAILUP_CLIENT_SECRET'],
+  oauth: {
+    token: "...",
+    refresh_token: "...",
+    expires_at: 1234567890
+  }
+}
+
+mailup = MailUp::Api.new(credentials)
+```
+
+### Console Methods
+
+Check out the [console methods API documentation](http://help.mailup.com/display/mailupapi/Console+methods+v1.1) for more information.
+
+```ruby
+lists = mailup.console.user.lists
+lists['Items'].first['Name']
+# => "Test List"
+list_id = lists['Items'].first['idList'].to_i
+# => 1
+list = mailup.console.list(list_id)
+groups = list.groups(pageNumber: 1, pageSize: 25)
+groups['IsPaginated']
+# => true
+groups['PageNumber']
+# => 1
+groups['PageSize']
+# => 25
+groups['Skipped']
+# => 25
+groups['TotalElementsCount']
+# => 35
+groups['Items'].size
+# => 10
+```
+
+### Email Statistics Methods
+
+Check out the [email statistics API documentation](http://help.mailup.com/display/mailupapi/Email+statistics+methods+v1.1) for more information.
+
+```ruby
+views_count = mailup.stats.message(17).views_count
+# => 250
+
+fields = mailup.stats.recipient(5).fields
+# => {"IsPaginated"=>true, "Items"=>[{"Description"=>"AllOrderedProductIDs", "Id"=>26}, ...], ...}
+```

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+# If you want to make this the default task
+#task default: :spec

data/lib/mailup.rb

@@ -0,0 +1,206 @@
+require 'oauth2'
+require 'multi_json'
+
+require 'mailup/version'
+require 'mailup/errors'
+require 'mailup/console/base'
+require 'mailup/console/email'
+require 'mailup/console/group'
+require 'mailup/console/images'
+require 'mailup/console/import'
+require 'mailup/console/list'
+require 'mailup/console/recipient'
+require 'mailup/console/user'
+require 'mailup/public/base'
+require 'mailup/public/console'
+require 'mailup/stats/base'
+require 'mailup/stats/message'
+require 'mailup/stats/recipient'
+
+module MailUp
+  class API
+    attr_accessor :access_token, :debug, :host, :path
+
+    # Initialize a new (thread-safe) API instance.
+    #
+    # @param [Hash] credentials for connecting to the MailUp API.
+    #   * client_id [String]
+    #   * client_secret [String]
+    #   * oauth [Hash]
+    #     * token [String]
+    #     * refresh_token [String]
+    #     * expires_at [Integer]
+    # @param [Boolean] debug whether or not to raise errors.
+    #
+    # @example
+    #
+    #   credentials = {
+    #     client_id: "1324567890",
+    #     client_secret: "123abc456def",
+    #     oauth: {
+    #       token: "1324567890",
+    #       refresh_token: "1324567890",
+    #       expires_at: 123456789,
+    #     }
+    #   }
+    #   mailup = MailUp::API.new(credentials)
+    #
+    def initialize(credentials=nil, debug=false)
+      @debug = debug
+      @host = 'https://services.mailup.com'
+      @path = ''
+
+      # Validate the credentials
+      raise Error.new, 'MailUp credentials missing' if credentials.nil? or !credentials.is_a?(Hash)
+      [:client_id, :client_secret, :oauth].each do |key|
+        raise Error.new, "MailUp credentials must include a #{key.to_s} key" unless credentials.has_key?(key)
+      end
+      raise Error.new, 'MailUp credentials :oauth must be a hash' unless credentials[:oauth].is_a?(Hash)
+      [:token, :refresh_token, :expires_at].each do |key|
+        raise Error.new, "MailUp credentials :oauth hash must include a #{key.to_s} key" unless credentials[:oauth].has_key?(key)
+      end
+
+      # Create a OAuth2 client instance
+      client = OAuth2::Client.new(
+        credentials[:client_id],
+        credentials[:client_secret],
+        site: @host,
+        authorize_url: "/Authorization/OAuth/LogOn",
+        token_url: "/Authorization/OAuth/Token",
+        raise_errors: @debug
+      )
+
+      # Create an access_token instance
+      @access_token = OAuth2::AccessToken.new(
+        client,
+        credentials[:oauth][:token],
+        {
+          refresh_token: credentials[:oauth][:refresh_token],
+          expires_at: credentials[:oauth][:expires_at]
+        }
+      )
+    end
+
+    # Make a request with the Access Token.
+    #
+    # @param [Symbol] verb the HTTP request method
+    # @param [String] path the HTTP URL path of the request
+    # @param [Hash] opts the options to make the request with
+    #
+    def request(method, path, opts={}, &block) # :nodoc:
+      unless @access_token == nil
+        # Refresh token if needed
+        @access_token = @access_token.refresh! if @access_token.expired?
+        # Ensure the body is JSON
+        opts[:body] = MultiJson.dump(opts[:body]) if opts[:body]
+        # Set the headers
+        opts[:headers] ||= {}
+        opts[:headers].merge!(headers)
+        # Make the request
+        req = @access_token.send(method, path, opts)
+        # Handle the response
+        handle_response(req)
+      end
+    end
+
+    # Make a GET request with the Access Token
+    # @see #request
+    #
+    def get(path, opts={}, &block) # :nodoc:
+      request(:get, path, opts, &block)
+    end
+
+    # Make a POST request with the Access Token
+    # @see #request
+    #
+    def post(path, opts={}, &block) # :nodoc:
+      request(:post, path, opts, &block)
+    end
+
+    # Make a PUT request with the Access Token
+    # @see #request
+    #
+    def put(path, opts={}, &block) # :nodoc:
+      request(:put, path, opts, &block)
+    end
+
+    # Make a PATCH request with the Access Token
+    # @see #request
+    #
+    def patch(path, opts={}, &block) # :nodoc:
+      request(:patch, path, opts, &block)
+    end
+
+    # Make a DELETE request with the Access Token
+    # @see #request
+    #
+    def delete(path, opts={}, &block) # :nodoc:
+      request(:delete, path, opts, &block)
+    end
+
+    # Handle the response of a request
+    def handle_response(response) # :nodoc:
+      case response.status
+      when 400
+        raise BadRequest.new response.parsed
+      when 401
+        raise Unauthorized.new
+      when 404
+        raise NotFound.new
+      when 400...500
+        raise ClientError.new response.parsed
+      when 500...600
+        raise ServerError.new
+      else
+        case response.body
+        when ''
+          true
+        when is_a?(Integer)
+          response.body
+        else
+          response.parsed
+        end
+      end
+    end
+
+    # Set the request headers
+    def headers # :nodoc:
+      {
+        'User-Agent' => "mailup-ruby-#{VERSION}",
+        'Content-Type' => 'application/json; charset=utf-8',
+        'Accept' => 'application/json'
+      }
+    end
+
+    # Access the console API methods
+    #
+    # @example
+    #
+    #   lists = mailup.console.user.lists
+    #
+    def console
+      Console::Base.new self
+    end
+
+    # Access the public API methods
+    #
+    # @example
+    #
+    #   activation = mailup.public.activation.new(...)
+    #
+    def public
+      Public::Base.new self
+    end
+
+    # Access the email statistics API methods
+    #
+    # @example
+    #
+    #   views = mailup.stats.message.views_count(1)
+    #
+    def stats
+      Stats::Base.new self
+    end
+
+  end
+end

data/lib/mailup/console/base.rb

@@ -0,0 +1,115 @@
+module MailUp
+  module Console
+    class Base
+      attr_accessor :api
+
+      def initialize(api) # :nodoc:
+          @api = api
+          @api.path = "/API/v#{MailUp::API_VERSION}/Rest/ConsoleService.svc/Console"
+      end
+
+      # Create an email object
+      #
+      # @return [MailUp::Console::Email] 
+      #
+      # @example
+      #
+      #   email = mailup.console.email
+      #
+      def email
+        Email.new @api
+      end
+
+      # Create a group object
+      # 
+      # @param [Integer] id The group_id of the group to access.
+      #
+      # @return [MailUp::Console::Group] 
+      #
+      # @example
+      #
+      #   group = mailup.console.group(1)
+      #
+      def group(id)
+        Group.new id, @api
+      end
+
+      # Create an images object
+      #
+      # @return [MailUp::Console::Images] 
+      #
+      # @example
+      #
+      #   images = mailup.console.images
+      #
+      def images
+        Images.new @api
+      end
+      
+      # Create an import object
+      # 
+      # @param [Integer] idImport The ID of the import process.
+      #
+      # @return [MailUp::Console::Import] 
+      #
+      # @example
+      #
+      #   import = mailup.console.import(9)
+      #
+      def import(id)
+        Import.new id, @api
+      end
+
+      # Create a list object
+      # 
+      # @param [Integer] id The list_id of the list to access.
+      #
+      # @return [MailUp::Console::List] 
+      #
+      # @example
+      #
+      #   list = mailup.console.list(2)
+      #
+      def list(id)
+        List.new id, @api
+      end
+
+      # Create a public methods object
+      #
+      # @return [MailUp::Console::List] 
+      #
+      # @example
+      #
+      #   list = mailup.console.list(2)
+      #
+      def public
+        Public.new @api
+      end
+
+      # Create a recipient object
+      #
+      # @return [MailUp::Console::Recipient] 
+      #
+      # @example
+      #
+      #   recipient = mailup.console.recipient
+      #
+      def recipient
+        Recipient.new @api
+      end
+
+      # Create a user object
+      #
+      # @return [MailUp::Console::User] 
+      #
+      # @example
+      #
+      #   user = mailup.console.user
+      #
+      def user
+        User.new @api
+      end
+
+    end
+  end
+end