wj-mailgun-ruby 1.1.7

data/lib/mailgun/events/events.rb

@@ -0,0 +1,120 @@
+require 'mailgun/exceptions/exceptions'
+
+module Mailgun
+
+  # A Mailgun::Events object makes it really simple to consume
+  #   Mailgun's events from the Events endpoint.
+  #
+  # This is not yet comprehensive.
+  #
+  # Examples
+  #
+  #    See the Github documentation for full examples.
+  class Events
+    include Enumerable
+
+    # Public: event initializer
+    #
+    # client - an instance of Mailgun::Client
+    # domain - the domain to build queries
+    def initialize(client, domain)
+      @client = client
+      @domain = domain
+      @paging_next = nil
+      @paging_previous = nil
+    end
+
+    # 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)
+      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(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(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
+
+    # 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            = 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[/api.mailgun.net\/v[\d]\/#{@domain}\/events\/(.+)/,1]
+    rescue URI::InvalidURIError
+      nil
+    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

@@ -0,0 +1,65 @@
+module Mailgun
+
+  # 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
+
+    # 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
+  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
+    # response - a RestClient::Response object
+    #
+    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
+
+      message = message || ''
+      message = message + ': ' + api_message
+
+      super(message, response)
+    rescue NoMethodError, JSON::ParserError
+      @code = NOCODE
+      super(message, response)
+    end
+
+  end
+end

data/lib/mailgun/lists/opt_in_handler.rb

@@ -0,0 +1,58 @@
+require 'uri'
+require 'base64'
+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
+    # all the necessary data in the URL.
+    #
+    # @param [String] mailing_list The mailing list the user should be subscribed to.
+    # @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)
+      inner_payload = { 'l' => mailing_list, 'r' => recipient_address }
+
+      inner_payload_encoded = Base64.encode64(JSON.generate(inner_payload))
+
+      sha1_digest = OpenSSL::Digest.new('sha1')
+      digest = OpenSSL::HMAC.hexdigest(sha1_digest, secret_app_id, inner_payload_encoded)
+
+      outer_payload = { 'h' => digest, 'p' => inner_payload_encoded }
+
+      outer_payload_encoded = Base64.encode64(JSON.generate(outer_payload))
+
+      CGI.escape(outer_payload_encoded)
+    end
+
+    # Validates the hash provided from the generate_hash method.
+    #
+    # @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)
+      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, outer_payload['p'])
+
+      inner_payload = JSON.parse(Base64.decode64(CGI.unescape(outer_payload['p'])))
+
+      hash_provided = outer_payload['h']
+
+      if generated_hash == hash_provided
+        return { 'recipient_address' => inner_payload['r'], 'mailing_list' => inner_payload['l'] }
+      end
+      false
+    end
+
+  end
+
+end

data/lib/mailgun/messages/batch_message.rb

@@ -0,0 +1,125 @@
+require 'mailgun/messages/message_builder'
+
+module Mailgun
+
+  # A Mailgun::BatchMessage object is used to create a valid payload
+  # for Batch Sending. Batch Sending can be difficult to implement, therefore
+  # this code makes it dead simple to send millions of messages in batches of
+  # 1,000 recipients per HTTP call.
+  #
+  # For the curious, the class simply keeps track of recipient data (count,
+  # user variables), and fires the API payload on the 1,000th addition of a recipient.
+  #
+  # The best way to use this class is:
+  # 1. Build your message using the Message Builder methods.
+  # 2. Query your source and create an iterable list.
+  # 3. Iterate through your source data, and add your recipients using the
+  #    add_recipient() method.
+  # 4. Call finalize() to flush any remaining recipients and obtain/store
+  #    the message_ids for tracking purposes.
+  #
+  # See the Github documentation for full examples.
+  class BatchMessage < MessageBuilder
+
+    attr_reader :message_ids, :domain, :recipient_variables
+
+    # Public: Creates a new BatchMessage object.
+    def initialize(client, domain)
+      @client = client
+      @recipient_variables = {}
+      @domain = domain
+      @message_ids = {}
+      @message = Hash.new { |hash, key| hash[key] = [] }
+
+      @counters = {
+        recipients: { to: 0, cc: 0, bcc: 0 },
+        attributes: { attachment: 0, campaign_id: 0, custom_option: 0, tag: 0 }
+      }
+    end
+
+    # Adds a specific type of recipient to the batch message object.
+    #
+    # @param [String] recipient_type The type of recipient. "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)
+      # send the message when we have 1000, not before
+      send_message if @counters[:recipients][recipient_type] == Mailgun::Chains::MAX_RECIPIENTS
+
+      compiled_address = parse_address(address, variables)
+      set_multi_complex(recipient_type, compiled_address)
+
+      store_recipient_variables(recipient_type, address, variables) if recipient_type != :from
+
+      @counters[:recipients][recipient_type] += 1 if @counters[:recipients].key?(recipient_type)
+    end
+
+    # Always call this function after adding recipients. If less than 1000 are added,
+    # this function will ensure the batch is sent.
+    #
+    # @return [Hash] A hash of {'Message ID' => '# of Messages Sent'}
+    def finalize
+      send_message if any_recipients_left?
+      @message_ids
+    end
+
+    private
+
+    # This method determines if it's necessary to send another batch.
+    #
+    # @return [Boolean]
+    def any_recipients_left?
+      return true if @counters[:recipients][:to] > 0
+      return true if @counters[:recipients][:cc] > 0
+      return true if @counters[:recipients][:bcc] > 0
+      false
+    end
+
+    # This method initiates a batch send to the API. It formats the recipient
+    # variables, posts to the API, gathers the message IDs, then flushes that data
+    # to prepare for the next batch. This method implements the Mailgun Client, thus,
+    # an exception will be thrown if a communication error occurs.
+    #
+    # @return [Boolean]
+    def send_message
+      rkey = '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!
+      message_id = response['id'].gsub(/\>|\</, '')
+      @message_ids[message_id] = count_recipients
+      reset_message
+    end
+
+    # This method stores recipient variables for each recipient added, if
+    # variables exist.
+    def store_recipient_variables(recipient_type, address, variables)
+      variables = { id: @counters[:recipients][recipient_type] } unless variables
+      @recipient_variables[address] = variables
+    end
+
+    # This method stores recipient variables for each recipient added, if
+    # variables exist.
+    def count_recipients
+      count = 0
+      @counters[:recipients].each_value { |cnt| count += cnt }
+      count
+    end
+
+    # This method resets the message object to prepare for the next batch
+    # of recipients.
+    def reset_message
+      @message.delete('recipient-variables')
+      @message.delete(:to)
+      @message.delete(:cc)
+      @message.delete(:bcc)
+      @counters[:recipients][:to] = 0
+      @counters[:recipients][:cc] = 0
+      @counters[:recipients][:bcc] = 0
+    end
+
+  end
+
+end

data/lib/mailgun/messages/message_builder.rb

@@ -0,0 +1,413 @@
+require 'time'
+
+module Mailgun
+
+  # A Mailgun::MessageBuilder object is used to create a valid payload
+  # for the Mailgun API messages endpoint. If you prefer step by step message
+  # generation through your code, this class is for you.
+  #
+  # See the Github documentation for full examples.
+  class MessageBuilder
+
+    attr_reader :message, :counters
+
+    # Public: Creates a new MessageBuilder object.
+    def initialize
+      @message = Hash.new { |hash, key| hash[key] = [] }
+
+      @counters = {
+        recipients: { to: 0, cc: 0, bcc: 0 },
+        attributes: { attachment: 0, campaign_id: 0, custom_option: 0, tag: 0 }
+      }
+    end
+
+    # 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)
+      set_multi_complex(recipient_type, compiled_address)
+
+      @counters[:recipients][recipient_type] += 1 if @counters[:recipients].key?(recipient_type)
+    end
+
+    # Sets the from address for the message
+    #
+    # @param [String] address The address of the sender.
+    # @param [Hash] variables A hash of the variables associated with the recipient. We recommend "first" and "last" at a minimum!
+    # @return [void]
+    def from(address, vars = nil)
+      add_recipient(:from, address, vars)
+    end
+
+    # Deprecated: please use 'from' instead.
+    def set_from_address(address, variables = nil)
+      warn 'DEPRECATION: "set_from_address" is deprecated. Please use "from" instead.'
+      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)
+      set_multi_simple(:subject, subj)
+    end
+
+    # Deprecated: Please use "subject" instead.
+    def set_subject(subj = nil)
+      warn 'DEPRECATION: "set_subject" is deprecated. Please use "subject" instead.'
+      subject(subj)
+    end
+
+    # Set a text body for the message object
+    #
+    # @param [String] text_body The text body for the email.
+    # @return [void]
+    def body_text(text_body = nil)
+      set_multi_simple(:text, text_body)
+    end
+
+    # Deprecated: Please use "body_text" instead.
+    def set_text_body(text_body = nil)
+      warn 'DEPRECATION: "set_text_body" is deprecated. Please use "body_text" instead.'
+      body_text(text_body)
+    end
+
+    # Set a html body for the message object
+    #
+    # @param [String] html_body The html body for the email.
+    # @return [void]
+    def body_html(html_body = nil)
+      set_multi_simple(:html, html_body)
+    end
+
+    # Deprecated: Please use "body_html" instead.
+    def set_html_body(html_body = nil)
+      warn 'DEPRECATION: "set_html_body" is deprecated. Please use "body_html" instead.'
+      body_html(html_body)
+    end
+
+    # Adds a series of attachments, when called upon.
+    #
+    # @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)
+      add_file(:attachment, attachment, filename)
+    end
+
+    # Adds an inline image to the mesage object.
+    #
+    # @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)
+      set_multi_simple('o:testmode', bool_lookup(mode))
+    end
+
+    # Deprecated: 'set_test_mode' is depreciated. Please use 'test_mode' instead.
+    def set_test_mode(mode)
+      warn 'DEPRECATION: "set_test_mode" is deprecated. Please use "test_mode" instead.'
+      test_mode(mode)
+    end
+
+    # Turn DKIM on or off per message
+    #
+    # @param [Boolean] mode The boolean or string value(will fix itself)
+    # @return [void]
+    def dkim(mode)
+      set_multi_simple('o:dkim', bool_lookup(mode))
+    end
+
+    # Deprecated: 'set_dkim' is deprecated. Please use 'dkim' instead.
+    def set_dkim(mode)
+      warn 'DEPRECATION: "set_dkim" is deprecated. Please use "dkim" instead.'
+      dkim(mode)
+    end
+
+    # Add campaign IDs to message. Limit of 3 per message.
+    #
+    # @param [String] campaign_id A defined campaign ID to add to the message.
+    # @return [void]
+    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
+
+      set_multi_complex('o:campaign', campaign_id)
+      @counters[:attributes][:campaign_id] += 1
+    end
+
+    # Add tags to message. Limit of 3 per message.
+    #
+    # @param [String] tag A defined campaign ID to add to the message.
+    # @return [void]
+    def add_tag(tag)
+      if @counters[:attributes][:tag] >= Mailgun::Chains::MAX_TAGS
+        fail Mailgun::ParameterError, 'Too many tags added to message.', tag
+      end
+      set_multi_complex('o:tag', tag)
+      @counters[:attributes][:tag] += 1
+    end
+
+    # Turn Open Tracking on and off, on a per message basis.
+    #
+    # @param [Boolean] tracking Boolean true or false.
+    # @return [void]
+    def track_opens(mode)
+      set_multi_simple('o:tracking-opens', bool_lookup(mode))
+    end
+
+    # Deprecated: 'set_open_tracking' is deprecated. Please use 'track_opens' instead.
+    def set_open_tracking(tracking)
+      warn 'DEPRECATION: "set_open_tracking" is deprecated. Please use "track_opens" instead.'
+      track_opens(tracking)
+    end
+
+    # Turn Click Tracking on and off, on a per message basis.
+    #
+    # @param [String] mode True, False, or HTML (for HTML only tracking)
+    # @return [void]
+    def track_clicks(mode)
+      set_multi_simple('o:tracking-clicks', bool_lookup(mode))
+    end
+
+    # Depreciated: 'set_click_tracking. is deprecated. Please use 'track_clicks' instead.
+    def set_click_tracking(tracking)
+      warn 'DEPRECATION: "set_click_tracking" is deprecated. Please use "track_clicks" instead.'
+      track_clicks(tracking)
+    end
+
+    # Enable Delivery delay on message. Specify an RFC2822 date, and Mailgun
+    # will not deliver the message until that date/time. For conversion
+    # options, see Ruby "Time". Example: "October 25, 2013 10:00PM CST" will
+    # be converted to "Fri, 25 Oct 2013 22:00:00 -0600".
+    #
+    # @param [String] timestamp A date and time, including a timezone.
+    # @return [void]
+    def deliver_at(timestamp)
+      time_str = DateTime.parse(timestamp)
+      set_multi_simple('o:deliverytime', time_str.rfc2822)
+    end
+
+    # Deprecated: 'set_delivery_time' is deprecated. Please use 'deliver_at' instead.
+    def set_delivery_time(timestamp)
+      warn 'DEPRECATION: "set_delivery_time" is deprecated. Please use "deliver_at" instead.'
+      deliver_at timestamp
+    end
+
+    # Add custom data to the message. The data should be either a hash or JSON
+    # encoded. The custom data will be added as a header to your message.
+    #
+    # @param [string] name A name for the custom data. (Ex. X-Mailgun-<Name of Data>: {})
+    # @param [Hash] data Either a hash or JSON string.
+    # @return [void]
+    def header(name, data)
+      fail(Mailgun::ParameterError, 'Header name for message must be specified') if name.to_s.empty?
+      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.
+    def set_custom_data(name, data)
+      warn 'DEPRECATION: "set_custom_data" is deprecated. Please use "header" instead.'
+      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.
+    #
+    # @param [string] name A name for the custom parameter.
+    # @param [string] data A string of data for the parameter.
+    # @return [void]
+    def add_custom_parameter(name, data)
+      set_multi_complex(name, data)
+    end
+
+    # Set the Message-Id header to a custom value. Don't forget to enclose the
+    # Message-Id in angle brackets, and ensure the @domain is present. Doesn't
+    # use simple or complex setters because it should not set value in an array.
+    #
+    # @param [string] data A string of data for the parameter. Passing nil or
+    #   empty string will delete h:Message-Id key and value from @message hash.
+    # @return [void]
+    def message_id(data = nil)
+      key = 'h:Message-Id'
+      return @message.delete(key) if data.to_s.empty?
+      set_single(key, data)
+    end
+
+    # Deprecated: 'set_message_id' is deprecated. Use 'message_id' instead.
+    def set_message_id(data = nil)
+      warn 'DEPRECATION: "set_message_id" is deprecated. Please use "message_id" instead.'
+      message_id data
+    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 set_multi_simple(parameter, value)
+      @message[parameter] = value ? [value] : ['']
+    end
+
+    # Sets values within the multidict, however, allows
+    # duplicate values for keys.
+    #
+    # @param [String] parameter The message object parameter name.
+    # @param [String] value The value of the parameter.
+    # @return [void]
+    def set_multi_complex(parameter, value)
+      @message[parameter] << (value || '')
+    end
+
+    # Converts boolean type to string
+    #
+    # @param [String] value The item to convert
+    # @return [void]
+    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
+      value
+    end
+
+    # Validates whether the input is JSON.
+    #
+    # @param [String] json_ The suspected JSON string.
+    # @return [void]
+    def valid_json?(json_)
+      JSON.parse(json_)
+      return true
+    rescue JSON::ParserError
+      false
+    end
+
+    # Private: given an object attempt to make it into JSON
+    #
+    # obj - an object. Hopefully a JSON string or Hash
+    #
+    # Returns a JSON object or raises ParameterError
+    def make_json(obj)
+      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
+
+    # Parses the address and gracefully handles any
+    # missing parameters. The result should be something like:
+    # "'First Last' <person@domain.com>"
+    #
+    # @param [String] address The email address to parse.
+    # @param [Hash] variables A list of recipient variables.
+    # @return [void]
+    def parse_address(address, vars)
+      return address unless vars.is_a? Hash
+      fail(Mailgun::ParameterError, 'Email address not specified') unless address.is_a? String
+
+      full_name = "#{vars['first']} #{vars['last']}".strip
+
+      return "'#{full_name}' <#{address}>" if defined?(full_name)
+      address
+    end
+
+    # Private: Adds a file to the message.
+    #
+    # @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)
+      attachment = File.open(filedata, 'r') if filedata.is_a?(String)
+      attachment = filedata.dup unless attachment
+
+      fail(Mailgun::ParameterError,
+        'Unable to access attachment file object.'
+      ) unless attachment.respond_to?(:read)
+
+      unless filename.nil?
+        attachment.instance_variable_set :@original_filename, filename
+        attachment.instance_eval 'def original_filename; @original_filename; end'
+      end
+      set_multi_complex(disposition, attachment)
+    end
+  end
+
+end