mailgun-ruby 1.1.2 → 1.1.6

data/lib/mailgun/messages/message_builder.rb

@@ -23,17 +23,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 +60,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 +92,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 +106,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 +117,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 +126,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 +160,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 +176,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 +188,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 +197,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_multi_simple('o:tracking-opens', bool_lookup(mode))
     end
 
     # Deprecated: 'set_open_tracking' is deprecated. Please use 'track_opens' instead.
@@ -183,7 +211,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_multi_simple('o:tracking-clicks', bool_lookup(mode))
     end
 
     # Depreciated: 'set_click_tracking. is deprecated. Please use 'track_clicks' instead.
@@ -201,7 +229,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 +246,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 +260,19 @@ 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?
+      jsondata = make_json data
+      set_single("v:#{name}", jsondata)
+    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 +281,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 +294,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 +305,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 +331,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 +362,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
@@ -334,7 +389,7 @@ module Mailgun
     # 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]
     #
@@ -351,7 +406,7 @@ module Mailgun
         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
 

data/lib/mailgun/suppressions.rb

@@ -0,0 +1,270 @@
+require 'uri'
+
+require 'mailgun/exceptions/exceptions'
+
+module Mailgun
+
+  # The Mailgun::Suppressions object makes it easy to manage "suppressions"
+  # attached to an account. "Suppressions" means bounces, unsubscribes, and complaints.
+  class Suppressions
+
+    # @param [Mailgun::Client] client API client to use for requests
+    # @param [String] domain Domain name to use for the suppression endpoints.
+    def initialize(client, domain)
+      @client = client
+      @domain = domain
+
+      @paging_next = nil
+      @paging_prev = nil
+    end
+
+    ####
+    # Paging operations
+    ####
+
+    def next
+      response = get_from_paging @paging_next[:path], @paging_next[:params]
+      extract_paging response
+      response
+    end
+
+    def prev
+      response = get_from_paging @paging_prev[:path], @paging_prev[:params]
+      extract_paging response
+      response
+    end
+
+    ####
+    # Bounces Endpoint (/v3/:domain/bounces)
+    ####
+
+    def list_bounces(params = {})
+      response = @client.get("#{@domain}/bounces", params)
+      extract_paging response
+      response
+    end
+
+    def get_bounce(address)
+      @client.get("#{@domain}/bounces/#{address}", nil)
+    end
+
+    def create_bounce(params = {})
+      @client.post("#{@domain/bounces}", params)
+    end
+
+    # Creates multiple bounces on the Mailgun API.
+    # If a bounce does not have a valid structure, it will be added to a list of unsendable bounces.
+    # The list of unsendable bounces will be returned at the end of this operation.
+    #
+    # If more than 999 bounce entries are provided, the list will be split and recursive calls will be made.
+    #
+    # @param [Array] data Array of bounce hashes
+    # @return [Response] Mailgun API response
+    # @return [Array] Return values from recursive call for list split.
+    def create_bounces(data)
+      # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
+      split_return = []
+      if data.length >= 1000 then
+        resp, resp_l = create_bounces data[999..-1]
+        split_return.push(resp)
+        split_return.concat(resp_l)
+        data = data[0..998]
+      elsif data.length == 0 then
+        return nil, []
+      end
+
+      valid = []
+      # Validate the bounces given
+      # NOTE: `data` could potentially be very large (1000 elements) so it is
+      # more efficient to pop from data and push into a different array as
+      # opposed to possibly copying the entire array to another array.
+      while not data.empty? do
+        bounce = data.pop
+        # Bounces MUST contain a `address` key.
+        if not bounce.include? :address then
+          raise Mailgun::ParameterError.new "Bounce MUST include a :address key: #{bounce}"
+        end
+
+        bounce.each do |k, v|
+          # Hash values MUST be strings.
+          if not v.is_a? String then
+            bounce[k] = v.to_s
+          end
+        end
+
+        valid.push bounce
+      end
+
+      response = @client.post("#{@domain}/bounces", valid.to_json, { "Content-Type" => "application/json" })
+      return response, split_return
+    end
+
+    def delete_bounce(address)
+      @client.delete("#{@domain}/bounces/#{address}")
+    end
+
+    def delete_all_bounces
+      @client.delete("#{@domain}/bounces")
+    end
+
+    ####
+    # Unsubscribes Endpoint (/v3/:domain/unsubscribes)
+    ####
+
+    def list_unsubscribes(params = {})
+      response = @client.get("#{@domain}/unsubscribes", params)
+      extract_paging response
+      response
+    end
+
+    def get_unsubscribe(address)
+      @client.get("#{@domain}/unsubscribes/#{address}")
+    end
+
+    def create_unsubscribe(params = {})
+      @client.post("#{@domain}/unsubscribes", params)
+    end
+
+    # Creates multiple unsubscribes on the Mailgun API.
+    # If an unsubscribe does not have a valid structure, it will be added to a list of unsendable unsubscribes.
+    # The list of unsendable unsubscribes will be returned at the end of this operation.
+    #
+    # If more than 999 unsubscribe entries are provided, the list will be split and recursive calls will be made.
+    #
+    # @param [Array] data Array of unsubscribe hashes
+    # @return [Response] Mailgun API response
+    # @return [Array] Return values from recursive call for list split.
+    def create_unsubscribes(data)
+      # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
+      split_return = []
+      if data.length >= 1000 then
+        resp, resp_l = create_unsubscribes data[999..-1]
+        split_return.push(resp)
+        split_return.concat(resp_l)
+        data = data[0..998]
+      elsif data.length == 0 then
+        return nil, []
+      end
+
+      valid = []
+      # Validate the unsubscribes given
+      while not data.empty? do
+        unsubscribe = data.pop
+        # unsubscribes MUST contain a `address` key.
+        if not unsubscribe.include? :address then
+          raise Mailgun::ParameterError.new "Unsubscribe MUST include a :address key: #{unsubscribe}"
+        end
+
+        unsubscribe.each do |k, v|
+          # Hash values MUST be strings.
+          if not v.is_a? String then
+            unsubscribe[k] = v.to_s
+          end
+        end
+
+        valid.push unsubscribe
+      end
+
+      response = @client.post("#{@domain}/unsubscribes", valid.to_json, { "Content-Type" => "application/json" })
+      return response, split_return
+    end
+
+    def delete_unsubscribe(address, params = {})
+      @client.delete("#{@domain}/unsubscribes/#{address}")
+    end
+
+    ####
+    # Complaints Endpoint (/v3/:domain/complaints)
+    ####
+
+    def list_complaints(params = {})
+      response = @client.get("#{@domain}/complaints", params)
+      extract_paging response
+      response
+    end
+
+    def get_complaint(address)
+      @client.get("#{@domain}/complaints/#{address}", nil)
+    end
+
+    def create_complaint(params = {})
+      @client.post("#{@domain}/complaints", params)
+    end
+
+    # Creates multiple complaints on the Mailgun API.
+    # If a complaint does not have a valid structure, it will be added to a list of unsendable complaints.
+    # The list of unsendable complaints will be returned at the end of this operation.
+    #
+    # If more than 999 complaint entries are provided, the list will be split and recursive calls will be made.
+    #
+    # @param [Array] data Array of complaint hashes
+    # @return [Response] Mailgun API response
+    # @return [Array] Return values from recursive call for list split.
+    def create_complaints(data)
+      # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
+      split_return = []
+      if data.length >= 1000 then
+        resp, resp_l = create_complaints data[999..-1]
+        split_return.push(resp)
+        split_return.concat(resp_l)
+        data = data[0..998]
+      elsif data.length == 0 then
+        return nil, []
+      end
+
+      valid = []
+      # Validate the complaints given
+      while not data.empty? do
+        complaint = data.pop
+        # complaints MUST contain a `address` key.
+        if not complaint.include? :address then
+          raise Mailgun::ParameterError.new "Complaint MUST include a :address key: #{complaint}"
+        end
+
+        complaint.each do |k, v|
+          # Hash values MUST be strings.
+          if not v.is_a? String then
+            complaint[k] = v.to_s
+          end
+        end
+
+        valid.push complaint
+      end
+
+      response = @client.post("#{@domain}/complaints", valid.to_json, { "Content-Type" => "application/json" })
+      return response, split_return
+    end
+
+    def delete_complaint(address)
+      @client.delete("#{@domain}/complaints/#{address}")
+    end
+
+    private
+
+    def get_from_paging(uri, params = {})
+      @client.get(uri, params)
+    end
+
+    def extract_paging(response)
+      rhash = response.to_h
+      return nil unless rhash.include? "paging"
+
+      page_info = rhash["paging"]
+
+      # Build the `next` endpoint
+      page_next = URI.parse(page_info["next"])
+      @paging_next = {
+        :path => page_next.path[/\/v[\d](.+)/, 1],
+        :params => Hash[URI.decode_www_form page_next.query],
+      }
+
+      # Build the `prev` endpoint
+      page_prev = URI.parse(page_info["previous"])
+      @paging_prev = {
+        :path => page_prev.path[/\/v[\d](.+)/, 1],
+        :params => Hash[URI.decode_www_form page_prev.query],
+      }
+    end
+
+  end
+end

data/lib/mailgun/version.rb

@@ -1,4 +1,4 @@
 # It's the version. Yeay!
 module Mailgun
-  VERSION = '1.1.2'
+  VERSION = '1.1.6'
 end

data/lib/mailgun-ruby.rb

@@ -1 +1,2 @@
-require 'mailgun'
+require 'mailgun'
+require 'railgun' if defined?(Rails)

data/lib/railgun/attachment.rb

@@ -0,0 +1,56 @@
+module Railgun
+
+  class Attachment < StringIO
+
+    attr_reader :filename, :content_type, :path,
+                :original_filename, :overwritten_filename
+
+    def initialize(attachment, *args)
+      @path = ''
+      @inline = args.detect { |opt| opt[:inline] }
+
+      if @inline
+        @filename = attachment.cid
+      else
+        @filename = attachment.filename
+      end
+
+      @original_filename = @filename
+
+      if args.detect { |opt| opt[:filename] }
+        @filename = opt[:filename]
+      end
+
+      @overwritten_filename = @filename
+
+      @content_type = attachment.content_type.split(';')[0]
+
+      super attachment.body.decoded
+    end
+
+    def inline?
+      @inline
+    end
+
+    def is_original_filename
+      @original_filename == @overwritten_filename
+    end
+
+    def source_filename
+      @filename
+    end
+
+    def attach_to_message!(mb)
+      if mb.nil?
+        nil
+      end
+
+      if inline?
+        mb.add_inline_image self, @filename
+      else
+        mb.add_attachment self, @filename
+      end
+    end
+
+  end
+end

data/lib/railgun/errors.rb

@@ -0,0 +1,27 @@
+module Railgun
+
+  class Error < StandardError
+
+    attr_reader :object
+
+    def initialize(message = nil, object = nil)
+      super(message)
+
+      @object = object
+    end
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class InternalError < Error
+
+    attr_reader :source_exception
+
+    def initialize(source_exc, message = nil, object = nil)
+      super(message, object)
+
+      @source_exception = source_exc
+    end
+  end
+end