mailgun-ruby 1.0.3 → 1.1.0

data/lib/mailgun/chains.rb

@@ -0,0 +1,16 @@
+module Mailgun
+
+  # Public constants used throughout
+  class Chains
+
+    # maximum campaign ids per message
+    MAX_CAMPAIGN_IDS = 3
+
+    # maximum tags per message
+    MAX_TAGS = 3
+
+    # maximum recipients per message or batch
+    MAX_RECIPIENTS = 1000
+
+  end
+end

data/lib/mailgun/client.rb

@@ -0,0 +1,143 @@
+require 'mailgun/chains'
+require 'mailgun/exceptions/exceptions'
+
+module Mailgun
+  # A Mailgun::Client object is used to communicate with the Mailgun API. It is a
+  # wrapper around RestClient so you don't have to worry about the HTTP aspect
+  # of communicating with our API.
+  #
+  # See the Github documentation for full examples.
+  class Client
+
+    def initialize(api_key = Mailgun.api_key,
+                   api_host = 'api.mailgun.net',
+                   api_version = 'v3',
+                   ssl = true)
+
+      endpoint = endpoint_generator(api_host, api_version, ssl)
+      @http_client = RestClient::Resource.new(endpoint,
+                                              user: 'api',
+                                              password: api_key,
+                                              user_agent: "mailgun-sdk-ruby/#{Mailgun::VERSION}")
+    end
+
+    # Simple Message Sending
+    #
+    # @param [String] working_domain This is the domain you wish to send from.
+    # @param [Hash] data This should be a standard Hash
+    # containing required parameters for the requested resource.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+    def send_message(working_domain, data)
+      case data
+      when Hash
+        if data.key?(:message)
+          if data[:message].is_a?(String)
+            data[:message] = convert_string_to_file(data[:message])
+          end
+          return post("#{working_domain}/messages.mime", data)
+        end
+        post("#{working_domain}/messages", data)
+      when MessageBuilder
+        post("#{working_domain}/messages", data.message)
+      else
+        fail ParameterError.new('Unknown data type for data parameter.', data)
+      end
+    end
+
+    # Generic Mailgun POST Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @param [Hash] data This should be a standard Hash
+    # containing required parameters for the requested resource.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+    def post(resource_path, data)
+      response = @http_client[resource_path].post(data)
+      Response.new(response)
+    rescue => err
+      raise communication_error err
+    end
+
+    # Generic Mailgun GET Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @param [Hash] query_string This should be a standard Hash
+    # containing required parameters for the requested resource.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+    def get(resource_path, params = nil, accept = '*/*')
+      if params
+        response = @http_client[resource_path].get(params: params, accept: accept)
+      else
+        response = @http_client[resource_path].get(accept: accept)
+      end
+      Response.new(response)
+    rescue => err
+      raise communication_error err
+    end
+
+    # Generic Mailgun PUT Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @param [Hash] data This should be a standard Hash
+    # containing required parameters for the requested resource.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+    def put(resource_path, data)
+      response = @http_client[resource_path].put(data)
+      Response.new(response)
+    rescue => err
+      raise communication_error err
+    end
+
+    # Generic Mailgun DELETE Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+    def delete(resource_path)
+      response = @http_client[resource_path].delete
+      Response.new(response)
+    rescue => err
+      raise communication_error err
+    end
+
+    private
+
+    # Converts MIME string to file for easy uploading to API
+    #
+    # @param [String] string MIME string to post to API
+    # @return [File] File object
+    def convert_string_to_file(string)
+      file = Tempfile.new('MG_TMP_MIME')
+      file.write(string)
+      file.rewind
+      file
+    end
+
+    # Generates the endpoint URL to for the API. Allows overriding
+    # API endpoint, API versions, and toggling SSL.
+    #
+    # @param [String] api_host URL endpoint the library will hit
+    # @param [String] api_version The version of the API to hit
+    # @param [Boolean] ssl True, SSL. False, No SSL.
+    # @return [string] concatenated URL string
+    def endpoint_generator(api_host, api_version, ssl)
+      ssl ? scheme = 'https' : scheme = 'http'
+      if api_version
+        "#{scheme}://#{api_host}/#{api_version}"
+      else
+        "#{scheme}://#{api_host}"
+      end
+    end
+
+    # Raises CommunicationError and stores response in it if present
+    #
+    # @param [StandardException] e upstream exception object
+    def communication_error(e)
+      return CommunicationError.new(e.message, e.response) if e.respond_to? :response
+      CommunicationError.new(e.message)
+    end
+
+  end
+end

data/lib/mailgun/domains/domains.rb

@@ -0,0 +1,84 @@
+require 'mailgun/exceptions/exceptions'
+
+module Mailgun
+
+  # A Mailgun::Domains object is a simple CRUD interface to Mailgun Domains.
+  # Uses Mailgun
+  class Domains
+
+    # Public: creates a new Mailgun::Domains instance.
+    #   Defaults to Mailgun::Client
+    def initialize(client = Mailgun::Client.new)
+      @client = client
+    end
+
+    # Public: Get Domains
+    #
+    # limit - [Integer] Maximum number of records to return. (100 by default)
+    # skip  - [Integer] Number of records to skip. (0 by default)
+    #
+    # Returns [Array] A list of domains (hash)
+    def list(options = {})
+      @client.get('domains', options).to_h['items']
+    end
+    alias_method :get_domains, :list
+
+    # Public: Get domain information
+    #
+    # domain - [String] Domain name to lookup
+    #
+    # Returns [Hash] Information on the requested domains.
+    def info(domain)
+      fail(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
+      @client.get("domains/#{domain}").to_h!
+    end
+    alias_method :get, :info
+    alias_method :get_domain, :info
+
+    # Public: Verify domain, update domain records
+    #   Unknown status - this is not in the current Mailgun API
+    #   Do no rely on this being available in future releases.
+    #
+    # domain - [String] Domain name
+    #
+    # Returns [Hash] Information on the updated/verified domains
+    def verify(domain)
+      fail(ParameterError, 'No domain given to verify on Mailgun', caller) unless domain
+      @client.put("domains/#{domain}/verify", nil).to_h!
+    end
+    alias_method :verify_domain, :verify
+
+    # Public: Add domain
+    #
+    # domain  - [String] Name of the domain (ex. domain.com)
+    # options - [Hash] of
+    #     smtp_password - [String] Password for SMTP authentication
+    #     spam_action   - [String] disabled or tag
+    #       Disable, no spam filtering will occur for inbound messages.
+    #       Tag, messages will be tagged wtih a spam header. See Spam Filter.
+    #     wildcard      - [Boolean] true or false Determines whether the domain will accept email for sub-domains.
+    #
+    # Returns [Hash] of created domain
+    def create(domain, options = {})
+      fail(ParameterError, 'No domain given to add on Mailgun', caller) unless domain
+      options = { smtp_password: nil, spam_action: 'disabled', wildcard: false }.merge(options)
+      options[:name] = domain
+      @client.post('domains', options).to_h
+    end
+    alias_method :add, :create
+    alias_method :add_domain, :create
+
+    # Public: Delete Domain
+    #
+    # domain - [String] domain name to delete (ex. domain.com)
+    #
+    # Returns [Boolean] if successful or not
+    def remove(domain)
+      fail(ParameterError, 'No domain given to remove on Mailgun', caller) unless domain
+      @client.delete("domains/#{domain}").to_h['message'] == 'Domain has been deleted'
+    end
+    alias_method :delete, :remove
+    alias_method :delete_domain, :remove
+
+  end
+end

data/lib/mailgun/events/events.rb

@@ -1,17 +1,21 @@
-require 'mailgun'
-require "mailgun/exceptions/exceptions"
-
+require 'mailgun/exceptions/exceptions'
 
 module Mailgun
 
   # A Mailgun::Events object makes it really simple to consume
-  # Mailgun's events from the Events endpoint.
+  #   Mailgun's events from the Events endpoint.
   #
+  # This is not yet comprehensive.
   #
-  # See the Github documentation for full examples.
-
+  # Examples
+  #
+  #    See the Github documentation for full examples.
   class Events
 
+    # Public: event initializer
+    #
+    # client - an instance of Mailgun::Client
+    # domain - the domain to build queries
     def initialize(client, domain)
       @client = client
       @domain = domain
@@ -19,56 +23,70 @@ module Mailgun
       @paging_previous = nil
     end
 
-    # Issues a simple get against the client.
+    # Public: Issues a simple get against the client.
     #
-    # @param [Hash] params A hash of query options and/or filters.
-    # @return [Mailgun::Response] Mailgun Response object.
-
-    def get(params=nil)
-      _get(params)
+    # params - a Hash of query options and/or filters.
+    #
+    # Returns a Mailgun::Response object.
+    def get(params = nil)
+      get_events(params)
     end
 
-    # Using built in paging, obtains the next set of data.
+    # Public: Using built in paging, obtains the next set of data.
+    # If an events request hasn't been sent previously, this will send one
+    #   without parameters
     #
-    # @return [Mailgun::Response] Mailgun Response object.
-
-    def next()
-      _get(nil, @paging_next)
+    # Returns a Mailgun::Response object.
+    def next
+      get_events(nil, @paging_next)
     end
 
-    # Using built in paging, obtains the previous set of data.
+    # Public: Using built in paging, obtains the previous set of data.
+    # If an events request hasn't been sent previously, this will send one
+    #   without parameters
     #
-    # @return [Mailgun::Response] Mailgun Response object.
-
-    def previous()
-      _get(nil, @paging_previous)
+    # Returns Mailgun::Response object.
+    def previous
+      get_events(nil, @paging_previous)
     end
 
     private
 
-    def _get(params=nil, paging=nil)
+    # Internal: Makes and processes the event request through the client
+    #
+    # params - optional Hash of query options
+    # paging - the URL key used for previous/next requests
+    #
+    # Returns a Mailgun.Response object.
+    def get_events(params = nil, paging = nil)
       response = @client.get(construct_url(paging), params)
       extract_paging(response)
       response
     end
 
+    # Internal: given an event response, pull and store the paging keys
+    #
+    # response - a Mailgun::Response object
+    #
+    # Return is irrelevant.
     def extract_paging(response)
-      paging_next = response.to_h["paging"]["next"]
-      paging_previous = response.to_h["paging"]["previous"]
-
       # This is pretty hackish. But the URL will never change in API v2.
-      @paging_next = paging_next.split("/")[6]
-      @paging_previous = paging_previous.split("/")[6]
+      @paging_next = response.to_h['paging']['next'].split('/')[6]
+      @paging_previous = response.to_h['paging']['previous'].split('/')[6]
+    rescue
+      @paging_next = nil
+      @paging_previous = nil
     end
 
-    def construct_url(paging=nil)
-      if paging
-        "#{@domain}/events/#{paging}"
-      else
-        "#{@domain}/events"
-      end
+    # Internal: construct the event path to be used by the client
+    #
+    # paging - the URL key for previous/next set of results
+    #
+    # Returns a String of the partial URI
+    def construct_url(paging = nil)
+      return "#{@domain}/events/#{paging}" if paging
+      "#{@domain}/events"
     end
 
   end
-
 end

data/lib/mailgun/exceptions/exceptions.rb

@@ -1,20 +1,53 @@
 module Mailgun
 
-  class Error < RuntimeError
+  # Public: A basic class for mananging errors.
+  # Inherits from StandardError (previously RuntimeError) as not all errors are
+  # runtime errors.
+  class Error < StandardError
+
+    # Public: get an object an error is instantiated with
     attr_reader :object
 
-    def initialize(message=nil, object=nil)
-      @message = message
+    # Public: initialize a Mailgun:Error object
+    #
+    # message - a String describing the error
+    # object  - an object with details about the error
+    def initialize(message = nil, object = nil)
+      super(message)
       @object = object
     end
-
-    def to_s
-      @message || self.class.to_s
-    end
   end
 
-  class ParameterError     < Error; end
-  class CommunicationError < Error; end
-  class ParseError         < Error; end
+  # Public: Class for managing parameter errors, with a pretty name.
+  # Inherits from Mailgun::Error
+  class ParameterError < Error; end
+
+  # Public: Class for managing parsing errors, with a pretty name.
+  # Inherits from Mailgun::Error
+  class ParseError < Error; end
+
+  # Public: Class for managing communications (eg http) response errors
+  # Inherits from Mailgun::Error
+  class CommunicationError < Error
+    # Public: gets HTTP status code
+    attr_reader :code
 
+    # Public: fallback if there is no response code on the object
+    NOCODE = 000
+
+    # Public: initialization of new error given a message and/or object
+    #
+    # message - a String detailing the error
+    # object  - a RestClient::Reponse object
+    #
+    def initialize(message = nil, object = nil)
+      @object = object
+      @code = object.http_code || NOCODE
+      super(JSON.parse(object.body)['message'])
+    rescue NoMethodError, JSON::ParserError
+      @code = NOCODE
+      super(message)
+    end
+
+  end
 end

data/lib/mailgun/lists/opt_in_handler.rb

@@ -5,6 +5,10 @@ require 'openssl'
 
 module Mailgun
 
+  # Public: Provides methods for creating and handling opt-in URLs,
+  #   particularlly for mailing lists.
+  #
+  # See: https://github.com/mailgun/mailgun-ruby/blob/master/OptInHandler.md
   class OptInHandler
 
     # Generates a hash that can be used to validate opt-in recipients. Encodes
@@ -14,22 +18,19 @@ module Mailgun
     # @param [String] secret_app_id A secret passphrase used as a constant for the hash.
     # @param [Hash] recipient_address The address of the user that should be subscribed.
     # @return [String] A url encoded URL suffix hash.
-
     def self.generate_hash(mailing_list, secret_app_id, recipient_address)
-      innerPayload = {'l' => mailing_list,
-                      'r' => recipient_address}
+      inner_payload = { 'l' => mailing_list, 'r' => recipient_address }
 
-      innerPayloadEncoded = Base64.encode64(JSON.generate(innerPayload))
+      inner_payload_encoded = Base64.encode64(JSON.generate(inner_payload))
 
       sha1_digest = OpenSSL::Digest.new('sha1')
-      digest = OpenSSL::HMAC.hexdigest(sha1_digest, secret_app_id, innerPayloadEncoded)
+      digest = OpenSSL::HMAC.hexdigest(sha1_digest, secret_app_id, inner_payload_encoded)
 
-      outerPayload = {'h' => digest,
-                      'p' => innerPayloadEncoded}
+      outer_payload = { 'h' => digest, 'p' => inner_payload_encoded }
 
-      outerPayloadEncoded = Base64.encode64(JSON.generate(outerPayload))
+      outer_payload_encoded = Base64.encode64(JSON.generate(outer_payload))
 
-      URI.escape(outerPayloadEncoded)
+      CGI.escape(outer_payload_encoded)
     end
 
     # Validates the hash provided from the generate_hash method.
@@ -37,24 +38,22 @@ module Mailgun
     # @param [String] secret_app_id A secret passphrase used as a constant for the hash.
     # @param [Hash] unique_hash The hash from the user. Likely via link click.
     # @return [Hash or Boolean] A hash with 'recipient_address' and 'mailing_list', if validates. Otherwise, boolean false.
-
     def self.validate_hash(secret_app_id, unique_hash)
-      outerPayload = JSON.parse(Base64.decode64(URI.unescape(unique_hash)))
+      outer_payload = JSON.parse(Base64.decode64(CGI.unescape(unique_hash)))
 
       sha1_digest = OpenSSL::Digest.new('sha1')
-      generated_hash = OpenSSL::HMAC.hexdigest(sha1_digest, secret_app_id, outerPayload['p'])
+      generated_hash = OpenSSL::HMAC.hexdigest(sha1_digest, secret_app_id, outer_payload['p'])
 
-      innerPayload = JSON.parse(Base64.decode64(URI.unescape(outerPayload['p'])))
+      inner_payload = JSON.parse(Base64.decode64(CGI.unescape(outer_payload['p'])))
 
-      hash_provided = outerPayload['h']
+      hash_provided = outer_payload['h']
 
-      if(generated_hash == hash_provided)
-        return {'recipient_address' => innerPayload['r'], 'mailing_list' => innerPayload['l']}
-      else
-        return false
+      if generated_hash == hash_provided
+        return { 'recipient_address' => inner_payload['r'], 'mailing_list' => inner_payload['l'] }
       end
+      false
     end
 
   end
-  
+
 end