mailgun-ruby 1.1.2 → 1.2.4

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/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,3 +1,4 @@
+require 'mime/types'
 require 'time'
 
 module Mailgun
@@ -23,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
@@ -53,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.
@@ -72,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.
@@ -86,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.
@@ -97,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)
@@ -106,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.
@@ -132,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.
@@ -148,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
 
@@ -160,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
 
@@ -169,7 +198,7 @@ module Mailgun
     # @param [Boolean] tracking Boolean true or false.
     # @return [void]
     def track_opens(mode)
-      simple_setter('o:tracking-opens', bool_lookup(mode))
+      set_single('o:tracking-opens', bool_lookup(mode))
     end
 
     # Deprecated: 'set_open_tracking' is deprecated. Please use 'track_opens' instead.
@@ -183,7 +212,7 @@ 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))
+      set_single('o:tracking-clicks', bool_lookup(mode))
     end
 
     # Depreciated: 'set_click_tracking. is deprecated. Please use 'track_clicks' instead.
@@ -201,7 +230,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.
@@ -218,8 +247,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.
@@ -228,6 +261,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.
@@ -236,7 +286,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
@@ -249,7 +299,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.
@@ -260,13 +310,23 @@ module Mailgun
 
     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
 
@@ -276,7 +336,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
 
@@ -307,9 +367,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
@@ -324,17 +384,24 @@ 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.
     #
     # @param [Symbol] disposition The type of file: :attachment or :inline
-    # @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]
     #
@@ -347,11 +414,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