mailgun-ruby 1.1.0 → 1.2.5

data/lib/mailgun/client.rb

@@ -1,4 +1,5 @@
 require 'mailgun/chains'
+require 'mailgun/suppressions'
 require 'mailgun/exceptions/exceptions'
 
 module Mailgun
@@ -12,13 +13,50 @@ module Mailgun
     def initialize(api_key = Mailgun.api_key,
                    api_host = 'api.mailgun.net',
                    api_version = 'v3',
-                   ssl = true)
+                   ssl = true,
+                   test_mode = false,
+                   timeout = nil,
+                   proxy_url = nil)
+
+      rest_client_params = {
+        user: 'api',
+        password: api_key,
+        user_agent: "mailgun-sdk-ruby/#{Mailgun::VERSION}"
+      }
+      rest_client_params[:timeout] = timeout if timeout
 
       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}")
+      RestClient.proxy = proxy_url
+      @http_client = RestClient::Resource.new(endpoint, rest_client_params)
+      @test_mode = test_mode
+    end
+
+    # Enable test mode
+    #
+    # Prevents sending of any messages.
+    def enable_test_mode!
+      @test_mode = true
+    end
+
+    # Disable test mode
+    #
+    # Reverts the test_mode flag and allows the client to send messages.
+    def disable_test_mode!
+      @test_mode = false
+    end
+
+    # Client is in test mode?
+    #
+    # @return [Boolean] Is the client set in test mode?
+    def test_mode?
+      @test_mode
+    end
+
+    # Provides a store of all the emails sent in test mode so you can check them.
+    #
+    # @return [Hash]
+    def self.deliveries
+      @@deliveries ||= []
     end
 
     # Simple Message Sending
@@ -28,8 +66,25 @@ module Mailgun
     # containing required parameters for the requested resource.
     # @return [Mailgun::Response] A Mailgun::Response object.
     def send_message(working_domain, data)
+      perform_data_validation(working_domain, data)
+
+      if test_mode? then
+        Mailgun::Client.deliveries << data
+        return Response.from_hash(
+          {
+            :body => "{\"id\": \"test-mode-mail-#{SecureRandom.uuid}@localhost\", \"message\": \"Queued. Thank you.\"}",
+            :code => 200,
+          }
+        )
+      end
+
       case data
       when Hash
+        # Remove nil values from the data hash
+        # Submitting nils to the API will likely cause an error.
+        #  See also: https://github.com/mailgun/mailgun-ruby/issues/32
+        data = data.select { |k, v| v != nil }
+
         if data.key?(:message)
           if data[:message].is_a?(String)
             data[:message] = convert_string_to_file(data[:message])
@@ -50,9 +105,10 @@ module Mailgun
     # 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.
+    # @param [Hash] headers Additional headers to pass to the resource.
     # @return [Mailgun::Response] A Mailgun::Response object.
-    def post(resource_path, data)
-      response = @http_client[resource_path].post(data)
+    def post(resource_path, data, headers = {})
+      response = @http_client[resource_path].post(data, headers)
       Response.new(response)
     rescue => err
       raise communication_error err
@@ -62,8 +118,9 @@ module Mailgun
     #
     # @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
+    # @param [Hash] params This should be a standard Hash
     # containing required parameters for the requested resource.
+    # @param [String] accept Acceptable Content-Type of the response body.
     # @return [Mailgun::Response] A Mailgun::Response object.
     def get(resource_path, params = nil, accept = '*/*')
       if params
@@ -102,6 +159,14 @@ module Mailgun
       raise communication_error err
     end
 
+    # Constructs a Suppressions client for the given domain.
+    #
+    # @param [String] domain Domain which suppressions requests will be made for
+    # @return [Mailgun::Suppressions]
+    def suppressions(domain)
+      Suppressions.new(self, domain)
+    end
+
     private
 
     # Converts MIME string to file for easy uploading to API
@@ -139,5 +204,17 @@ module Mailgun
       CommunicationError.new(e.message)
     end
 
+    def perform_data_validation(working_domain, data)
+      message = data.respond_to?(:message) ? data.message : data
+      fail ParameterError.new('Missing working domain', working_domain) unless working_domain
+      fail ParameterError.new(
+        'Missing `to` recipient, message should containg at least 1 recipient',
+        working_domain
+      ) if message.fetch('to', []).empty? && message.fetch(:to, []).empty?
+      fail ParameterError.new(
+        'Missing a `from` sender, message should containg at least 1 `from` sender',
+        working_domain
+      ) if message.fetch('from', []).empty? && message.fetch(:from, []).empty?
+    end
   end
 end

data/lib/mailgun/events/events.rb

@@ -11,6 +11,7 @@ module Mailgun
   #
   #    See the Github documentation for full examples.
   class Events
+    include Enumerable
 
     # Public: event initializer
     #
@@ -23,31 +24,47 @@ module Mailgun
       @paging_previous = nil
     end
 
-    # Public: Issues a simple get against the client.
+    # Public: Issues a simple get against the client. Alias of `next`.
     #
     # params - a Hash of query options and/or filters.
     #
     # Returns a Mailgun::Response object.
     def get(params = nil)
-      get_events(params)
+      self.next(params)
     end
 
     # 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
     #
+    # params - a Hash of query options and/or filters.
+    #
     # Returns a Mailgun::Response object.
-    def next
-      get_events(nil, @paging_next)
+    def next(params = nil)
+      get_events(params, @paging_next)
     end
 
     # 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
     #
+    # params - a Hash of query options and/or filters.
+    #
     # Returns Mailgun::Response object.
-    def previous
-      get_events(nil, @paging_previous)
+    def previous(params = nil)
+      get_events(params, @paging_previous)
+    end
+
+    # Public: Allows iterating through all events and performs automatic paging.
+    #
+    # &block - Block to execute on items.
+    def each(&block)
+      items = self.next.to_h['items']
+
+      until items.empty?
+        items.each(&block)
+        items = self.next.to_h['items']
+      end
     end
 
     private
@@ -70,12 +87,23 @@ module Mailgun
     #
     # Return is irrelevant.
     def extract_paging(response)
-      # This is pretty hackish. But the URL will never change in API v2.
-      @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
+      paging            = response.to_h['paging']
+      next_page_url     = paging && paging['next']      # gives nil when any one of the keys doens't exist
+      previous_page_url = paging && paging['previous']  # can be replaced with Hash#dig for ruby >= 2.3.0
+      @paging_next      = extract_endpoint_from(next_page_url)
+      @paging_previous  = extract_endpoint_from(previous_page_url)
+    end
+
+    # Internal: given a paging URL, extract the endpoint
+    #
+    # response - the endpoint for the previous/next page
+    #
+    # Returns a String of the partial URI if the given url follows the regular API format
+    # Returns nil in other cases (e.g. when given nil, or an irrelevant url)
+    def extract_endpoint_from(url = nil)
+      URI.parse(url).path[/\/v[\d]\/#{@domain}\/events\/(.+)/,1]
+    rescue URI::InvalidURIError
+      nil
     end
 
     # Internal: construct the event path to be used by the client

data/lib/mailgun/exceptions/exceptions.rb

@@ -34,19 +34,33 @@ module Mailgun
 
     # Public: fallback if there is no response code on the object
     NOCODE = 000
+    FORBIDDEN = 'Forbidden'
 
     # Public: initialization of new error given a message and/or object
     #
-    # message - a String detailing the error
-    # object  - a RestClient::Reponse object
+    # message  - a String detailing the error
+    # response - a RestClient::Response object
     #
-    def initialize(message = nil, object = nil)
-      @object = object
-      @code = object.http_code || NOCODE
-      super(JSON.parse(object.body)['message'])
+    def initialize(message = nil, response = nil)
+      @response = response
+      @code = response.code || NOCODE
+
+      begin
+        api_message = JSON.parse(response.body)['message']
+      rescue JSON::ParserError
+        api_message = response.body
+      rescue NoMethodError
+        api_message = "Unknown API error"
+      end
+      api_message = api_message + ' - Invalid Domain or API key' if api_message == FORBIDDEN
+
+      message = message || ''
+      message = message + ': ' + api_message
+
+      super(message, response)
     rescue NoMethodError, JSON::ParserError
       @code = NOCODE
-      super(message)
+      super(message, response)
     end
 
   end

data/lib/mailgun/lists/opt_in_handler.rb

@@ -1,4 +1,3 @@
-require 'json'
 require 'uri'
 require 'base64'
 require 'openssl'

data/lib/mailgun/messages/batch_message.rb

@@ -48,7 +48,7 @@ module Mailgun
       send_message if @counters[:recipients][recipient_type] == Mailgun::Chains::MAX_RECIPIENTS
 
       compiled_address = parse_address(address, variables)
-      complex_setter(recipient_type, compiled_address)
+      set_multi_complex(recipient_type, compiled_address)
 
       store_recipient_variables(recipient_type, address, variables) if recipient_type != :from
 
@@ -84,7 +84,7 @@ module Mailgun
     # @return [Boolean]
     def send_message
       rkey = 'recipient-variables'
-      simple_setter rkey, JSON.generate(@recipient_variables)
+      set_multi_simple rkey, JSON.generate(@recipient_variables)
       @message[rkey] = @message[rkey].first if @message.key?(rkey)
 
       response = @client.send_message(@domain, @message).to_h!
@@ -111,6 +111,7 @@ module Mailgun
     # This method resets the message object to prepare for the next batch
     # of recipients.
     def reset_message
+      @recipient_variables = {}
       @message.delete('recipient-variables')
       @message.delete(:to)
       @message.delete(:cc)

data/lib/mailgun/messages/message_builder.rb

@@ -1,5 +1,5 @@
+require 'mime/types'
 require 'time'
-require 'json'
 
 module Mailgun
 
@@ -24,17 +24,24 @@ module Mailgun
 
     # Adds a specific type of recipient to the message object.
     #
+    # WARNING: Setting 'h:reply-to' with add_recipient() is deprecated! Use 'reply_to' instead.
+    #
     # @param [String] recipient_type The type of recipient. "to", "cc", "bcc" or "h:reply-to".
     # @param [String] address The email address of the recipient to add to the message object.
     # @param [Hash] variables A hash of the variables associated with the recipient. We recommend "first" and "last" at a minimum!
     # @return [void]
     def add_recipient(recipient_type, address, variables = nil)
+      if recipient_type == "h:reply-to"
+        warn 'DEPRECATION: "add_recipient("h:reply-to", ...)" is deprecated. Please use "reply_to" instead.'
+        return reply_to(address, variables)
+      end
+
       if (@counters[:recipients][recipient_type] || 0) >= Mailgun::Chains::MAX_RECIPIENTS
         fail Mailgun::ParameterError, 'Too many recipients added to message.', address
       end
 
       compiled_address = parse_address(address, variables)
-      complex_setter(recipient_type, compiled_address)
+      set_multi_complex(recipient_type, compiled_address)
 
       @counters[:recipients][recipient_type] += 1 if @counters[:recipients].key?(recipient_type)
     end
@@ -54,12 +61,25 @@ module Mailgun
       from(address, variables)
     end
 
+    # Set the message's Reply-To address.
+    #
+    # Rationale: According to RFC, only one Reply-To address is allowed, so it
+    # is *okay* to bypass the set_multi_simple and set reply-to directly.
+    #
+    # @param [String] address The email address to provide as Reply-To.
+    # @param [Hash] variables A hash of variables associated with the recipient.
+    # @return [void]
+    def reply_to(address, variables = nil)
+      compiled_address = parse_address(address, variables)
+      header("reply-to", compiled_address)
+    end
+
     # Set a subject for the message object
     #
     # @param [String] subject The subject for the email.
     # @return [void]
     def subject(subj = nil)
-      simple_setter(:subject, subj)
+      set_multi_simple(:subject, subj)
     end
 
     # Deprecated: Please use "subject" instead.
@@ -73,7 +93,7 @@ module Mailgun
     # @param [String] text_body The text body for the email.
     # @return [void]
     def body_text(text_body = nil)
-      simple_setter(:text, text_body)
+      set_multi_simple(:text, text_body)
     end
 
     # Deprecated: Please use "body_text" instead.
@@ -87,7 +107,7 @@ module Mailgun
     # @param [String] html_body The html body for the email.
     # @return [void]
     def body_html(html_body = nil)
-      simple_setter(:html, html_body)
+      set_multi_simple(:html, html_body)
     end
 
     # Deprecated: Please use "body_html" instead.
@@ -98,7 +118,7 @@ module Mailgun
 
     # Adds a series of attachments, when called upon.
     #
-    # @param [String] attachment A file object for attaching as an attachment.
+    # @param [String|File] attachment A file object for attaching as an attachment.
     # @param [String] filename The filename you wish the attachment to be.
     # @return [void]
     def add_attachment(attachment, filename = nil)
@@ -107,19 +127,27 @@ module Mailgun
 
     # Adds an inline image to the mesage object.
     #
-    # @param [String] inline_image A file object for attaching an inline image.
+    # @param [String|File] inline_image A file object for attaching an inline image.
     # @param [String] filename The filename you wish the inline image to be.
     # @return [void]
     def add_inline_image(inline_image, filename = nil)
       add_file(:inline, inline_image, filename)
     end
 
+    # Adds a List-Unsubscribe for the message header.
+    #
+    # @param [Array<String>] *variables Any number of url or mailto
+    # @return [void]
+    def list_unsubscribe(*variables)
+      set_single('h:List-Unsubscribe', variables.map { |var| "<#{var}>" }.join(','))
+    end
+
     # Send a message in test mode. (The message won't really be sent to the recipient)
     #
     # @param [Boolean] mode The boolean or string value (will fix itself)
     # @return [void]
     def test_mode(mode)
-      simple_setter('o:testmode', bool_lookup(mode))
+      set_multi_simple('o:testmode', bool_lookup(mode))
     end
 
     # Deprecated: 'set_test_mode' is depreciated. Please use 'test_mode' instead.
@@ -133,7 +161,7 @@ module Mailgun
     # @param [Boolean] mode The boolean or string value(will fix itself)
     # @return [void]
     def dkim(mode)
-      simple_setter('o:dkim', bool_lookup(mode))
+      set_multi_simple('o:dkim', bool_lookup(mode))
     end
 
     # Deprecated: 'set_dkim' is deprecated. Please use 'dkim' instead.
@@ -149,7 +177,7 @@ module Mailgun
     def add_campaign_id(campaign_id)
       fail(Mailgun::ParameterError, 'Too many campaigns added to message.', campaign_id) if @counters[:attributes][:campaign_id] >= Mailgun::Chains::MAX_CAMPAIGN_IDS
 
-      complex_setter('o:campaign', campaign_id)
+      set_multi_complex('o:campaign', campaign_id)
       @counters[:attributes][:campaign_id] += 1
     end
 
@@ -161,7 +189,7 @@ module Mailgun
       if @counters[:attributes][:tag] >= Mailgun::Chains::MAX_TAGS
         fail Mailgun::ParameterError, 'Too many tags added to message.', tag
       end
-      complex_setter('o:tag', tag)
+      set_multi_complex('o:tag', tag)
       @counters[:attributes][:tag] += 1
     end
 
@@ -170,7 +198,9 @@ module Mailgun
     # @param [Boolean] tracking Boolean true or false.
     # @return [void]
     def track_opens(mode)
-      simple_setter('o:tracking-opens', bool_lookup(mode))
+      value = bool_lookup(mode)
+      set_single('o:tracking-opens', value)
+      set_multi_simple('o:tracking', value)
     end
 
     # Deprecated: 'set_open_tracking' is deprecated. Please use 'track_opens' instead.
@@ -184,7 +214,9 @@ module Mailgun
     # @param [String] mode True, False, or HTML (for HTML only tracking)
     # @return [void]
     def track_clicks(mode)
-      simple_setter('o:tracking-clicks', bool_lookup(mode))
+      value = bool_lookup(mode)
+      set_single('o:tracking-clicks', value)
+      set_multi_simple('o:tracking', value)
     end
 
     # Depreciated: 'set_click_tracking. is deprecated. Please use 'track_clicks' instead.
@@ -202,7 +234,7 @@ module Mailgun
     # @return [void]
     def deliver_at(timestamp)
       time_str = DateTime.parse(timestamp)
-      simple_setter('o:deliverytime', time_str.rfc2822)
+      set_multi_simple('o:deliverytime', time_str.rfc2822)
     end
 
     # Deprecated: 'set_delivery_time' is deprecated. Please use 'deliver_at' instead.
@@ -219,8 +251,12 @@ module Mailgun
     # @return [void]
     def header(name, data)
       fail(Mailgun::ParameterError, 'Header name for message must be specified') if name.to_s.empty?
-      jsondata = make_json data
-      simple_setter("v:#{name}", jsondata)
+      begin
+        jsondata = make_json data
+        set_single("h:#{name}", jsondata)
+      rescue Mailgun::ParameterError
+        set_single("h:#{name}", data)
+      end
     end
 
     # Deprecated: 'set_custom_data' is deprecated. Please use 'header' instead.
@@ -229,6 +265,23 @@ module Mailgun
       header name, data
     end
 
+    # Attaches custom JSON data to the message. See the following doc page for more info.
+    # https://documentation.mailgun.com/user_manual.html#attaching-data-to-messages
+    #
+    # @param [String] name A name for the custom variable block.
+    # @param [String|Hash] data Either a string or a hash. If it is not valid JSON or
+    #                           can not be converted to JSON, ParameterError will be raised.
+    # @return [void]
+    def variable(name, data)
+      fail(Mailgun::ParameterError, 'Variable name must be specified') if name.to_s.empty?
+      begin
+        jsondata = make_json data
+        set_single("v:#{name}", jsondata)
+      rescue Mailgun::ParameterError
+        set_single("v:#{name}", data)
+      end
+    end
+
     # Add custom parameter to the message. A custom parameter is any parameter that
     # is not yet supported by the SDK, but available at the API. Note: No validation
     # is performed. Don't forget to prefix the parameter with o, h, or v.
@@ -237,7 +290,7 @@ module Mailgun
     # @param [string] data A string of data for the parameter.
     # @return [void]
     def add_custom_parameter(name, data)
-      complex_setter(name, data)
+      set_multi_complex(name, data)
     end
 
     # Set the Message-Id header to a custom value. Don't forget to enclose the
@@ -250,7 +303,7 @@ module Mailgun
     def message_id(data = nil)
       key = 'h:Message-Id'
       return @message.delete(key) if data.to_s.empty?
-      @message[key] = data
+      set_single(key, data)
     end
 
     # Deprecated: 'set_message_id' is deprecated. Use 'message_id' instead.
@@ -259,15 +312,57 @@ module Mailgun
       message_id data
     end
 
+    # Set name of a template stored via template API. See Templates for more information
+    # https://documentation.mailgun.com/en/latest/api-templates.html
+    #
+    # @param [String] tag A defined template name to use. Passing nil or
+    #   empty string will delete template key and value from @message hash.
+    # @return [void]
+    def template(template_name = nil)
+      key = 'template'
+      return @message.delete(key) if template_name.to_s.empty?
+      set_single(key, template_name)
+    end
+
+    # Set specific template version.
+    #
+    # @param [String] tag A defined template name to use. Passing nil or
+    #   empty string will delete template key and value from @message hash.
+    # @return [void]
+    def template_version(version = nil)
+      key = 't:version'
+      return @message.delete(key) if version.to_s.empty?
+      set_single(key, version)
+    end
+
+    # Turn off or on template rendering in the text part
+    # of the message in case of template sending.
+    #
+    # @param [Boolean] tracking Boolean true or false.
+    # @return [void]
+    def template_text(mode)
+      set_single('t:text', bool_lookup(mode))
+    end
+
     private
 
+    # Sets a single value in the message hash where "multidict" features are not needed.
+    # Does *not* permit duplicate params.
+    #
+    # @param [String] parameter The message object parameter name.
+    # @param [String] value The value of the parameter.
+    # @return [void]
+    def set_single(parameter, value)
+      @message[parameter] = value ? value : ''
+    end
+
     # Sets values within the multidict, however, prevents
     # duplicate values for keys.
     #
     # @param [String] parameter The message object parameter name.
     # @param [String] value The value of the parameter.
     # @return [void]
-    def simple_setter(parameter, value)
+    def set_multi_simple(parameter, value)
       @message[parameter] = value ? [value] : ['']
     end
 
@@ -277,7 +372,7 @@ module Mailgun
     # @param [String] parameter The message object parameter name.
     # @param [String] value The value of the parameter.
     # @return [void]
-    def complex_setter(parameter, value)
+    def set_multi_complex(parameter, value)
       @message[parameter] << (value || '')
     end
 
@@ -288,6 +383,7 @@ module Mailgun
     def bool_lookup(value)
       return 'yes' if %w(true yes yep).include? value.to_s.downcase
       return 'no' if %w(false no nope).include? value.to_s.downcase
+      warn 'WARN: for bool type actions next values are prefered: true yes yep | false no nope | htmlonly'
       value
     end
 
@@ -308,9 +404,9 @@ module Mailgun
     #
     # Returns a JSON object or raises ParameterError
     def make_json(obj)
-      return JSON.parse(obj).to_s if obj.is_a?(String)
-      return obj.to_s if obj.is_a?(Hash)
-      return JSON.generate(obj).to_s
+      return JSON.parse(obj).to_json if obj.is_a?(String)
+      return obj.to_json if obj.is_a?(Hash)
+      return JSON.generate(obj).to_json
     rescue
       raise Mailgun::ParameterError, 'Provided data could not be made into JSON. Try a JSON string or Hash.', obj
     end
@@ -325,19 +421,26 @@ module Mailgun
     def parse_address(address, vars)
       return address unless vars.is_a? Hash
       fail(Mailgun::ParameterError, 'Email address not specified') unless address.is_a? String
+      if vars['full_name'] != nil && (vars['first'] != nil || vars['last'] != nil)
+        fail(Mailgun::ParameterError, 'Must specify at most one of full_name or first/last. Vars passed: #{vars}')
+      end
 
-      full_name = "#{vars['first']} #{vars['last']}".strip
+      if vars['full_name']
+        full_name = vars['full_name']
+      elsif vars['first'] || vars['last']
+        full_name = "#{vars['first']} #{vars['last']}".strip
+      end 
 
-      return "'#{full_name}' <#{address}>" if defined?(full_name)
+      return "'#{full_name}' <#{address}>" if full_name
       address
     end
 
     # Private: Adds a file to the message.
     #
-    # disposition - a Symbol of either :inline or :attachment specifying how to
-    #   to set the file/image
-    # attachment  - either a file object or string which is a path to the file
-    # filename    - optional String signifying the filename
+    # @param [Symbol] disposition The type of file: :attachment or :inline
+    # @param [String|File] attachment A file object for attaching as an attachment.
+    # @param [String] filename The filename you wish the attachment to be.
+    # @return [void]
     #
     # Returns nothing
     def add_file(disposition, filedata, filename)
@@ -348,11 +451,17 @@ module Mailgun
         'Unable to access attachment file object.'
       ) unless attachment.respond_to?(:read)
 
+      if attachment.respond_to?(:path) && !attachment.respond_to?(:content_type)
+        mime_types = MIME::Types.type_for(attachment.path)
+        content_type = mime_types.empty? ? 'application/octet-stream' : mime_types[0].content_type
+        attachment.instance_eval "def content_type; '#{content_type}'; end"
+      end
+
       unless filename.nil?
         attachment.instance_variable_set :@original_filename, filename
         attachment.instance_eval 'def original_filename; @original_filename; end'
       end
-      complex_setter(disposition, attachment)
+      set_multi_complex(disposition, attachment)
     end
   end