mailgun-ruby 1.0.0

data/lib/mailgun.rb

@@ -0,0 +1,227 @@
+require 'tempfile'
+require 'rest_client'
+require 'yaml'
+require 'json'
+
+require "mailgun/version"
+require "mailgun/lists/opt_in_handler"
+require "mailgun/messages/batch_message"
+require "mailgun/messages/message_builder"
+require "mailgun/exceptions/exceptions"
+
+module Mailgun
+
+  # A Mailgun::Client object is used to communicate with the Mailgun API. It is a 
+  # wrapper around RestClient so you don't have to worry about the HTTP aspect 
+  # of communicating with our API. 
+  #
+  # See the Github documentation for full examples.
+
+  class Client
+
+    def initialize(api_key,
+                   api_host="api.mailgun.net",
+                   api_version="v2",
+                   ssl=true)
+
+      endpoint = endpoint_generator(api_host, api_version, ssl)
+      @http_client = RestClient::Resource.new(endpoint,
+                                              :user => "api",
+                                              :password => api_key,
+                                              :user_agent => "mailgun-sdk-ruby/#{Mailgun::VERSION}")
+    end
+
+    # Simple Message Sending
+    #
+    # @param [String] working_domain This is the domain you wish to send from.
+    # @param [Hash] data This should be a standard Hash or Multimap
+    # containing required parameters for the requested resource.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+
+    def send_message(working_domain, data)
+      case data
+      when Hash, Multimap
+        if data.has_key?(:message)
+          if data[:message].is_a?(String)
+            data[:message] = convert_string_to_file(data[:message])
+          end
+          post("#{working_domain}/messages.mime", data)
+        else
+          post("#{working_domain}/messages", data)
+        end
+      when MessageBuilder
+        post("#{working_domain}/messages", data.message)
+      else
+        raise ParameterError.new("Unknown data type for data parameter.", data)
+      end
+    end
+
+    # Generic Mailgun POST Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @param [Hash] data This should be a standard Hash or Multimap
+    # containing required parameters for the requested resource.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+
+    def post(resource_path, data)
+      begin
+        response = @http_client[resource_path].post(data)
+        Response.new(response)
+      rescue Exception => e
+        raise CommunicationError.new(e), e.response
+      end
+    end
+
+    # Generic Mailgun GET Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @param [Hash] query_string This should be a standard Hash or Multimap
+    # containing required parameters for the requested resource.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+
+    def get(resource_path, params=nil)
+      begin
+        if params
+          response = @http_client[resource_path].get(:params => params)
+        else
+          response = @http_client[resource_path].get()
+        end
+        Response.new(response)
+      rescue Exception => e
+        raise CommunicationError.new(e), e.response
+      end
+    end
+
+    # Generic Mailgun PUT Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @param [Hash] data This should be a standard Hash or Multimap
+    # containing required parameters for the requested resource.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+
+    def put(resource_path, data)
+      begin
+        response = @http_client[resource_path].put(data)
+        Response.new(response)
+      rescue Exception => e
+        raise CommunicationError.new(e), e.response
+      end
+    end
+
+    # Generic Mailgun DELETE Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+
+    def delete(resource_path)
+      begin
+        response = @http_client[resource_path].delete()
+        Response.new(response)
+      rescue Exception => e
+        raise CommunicationError.new(e), e.response
+      end
+    end
+
+    private
+
+    # Converts MIME string to file for easy uploading to API
+    #
+    # @param [String] string MIME string to post to API
+    # @return [File] File object
+
+    def convert_string_to_file(string)
+      file = Tempfile.new('MG_TMP_MIME')
+      file.write(string)
+      file
+    end
+
+    # Generates the endpoint URL to for the API. Allows overriding 
+    # API endpoint, API versions, and toggling SSL.
+    #
+    # @param [String] api_host URL endpoint the library will hit
+    # @param [String] api_version The version of the API to hit
+    # @param [Boolean] ssl True, SSL. False, No SSL.
+    # @return [string] concatenated URL string
+
+    def endpoint_generator(api_host, api_version, ssl)
+      ssl ? scheme = 'https' : scheme = 'http'
+      if api_version
+        "#{scheme}://#{api_host}/#{api_version}"
+      else
+        "#{scheme}://#{api_host}"
+      end
+    end
+  end
+
+  # A Mailgun::Response object is instantiated for each response generated
+  # by the Client request. The Response object supports deserialization of
+  # the JSON result. Or, if you prefer JSON or YAML formatting, call the
+  # method for conversion. 
+  #
+  # See the Github documentation for full examples.
+
+  class Response
+
+    attr_accessor :body
+    attr_accessor :code
+
+    def initialize(response)
+      @body = response.body
+      @code = response.code
+    end
+
+    # Return response as Ruby Hash
+    #
+    # @return [Hash] A standard Ruby Hash containing the HTTP result.
+
+    def to_h
+      begin
+        JSON.parse(@body)
+      rescue Exception => e
+        raise ParseError.new(e), e
+      end
+    end
+
+    # Replace @body with Ruby Hash
+    #
+    # @return [Hash] A standard Ruby Hash containing the HTTP result.
+
+    def to_h!
+      begin
+        @body = JSON.parse(@body)
+      rescue Exception => e
+        raise ParseError.new(e), e
+      end
+    end
+
+    # Return response as Yaml
+    #
+    # @return [String] A string containing response as YAML
+
+    def to_yaml
+      begin
+        YAML::dump(JSON.parse(@body))
+      rescue Exception => e
+        raise ParseError.new(e), e
+      end
+    end
+
+    # Replace @body with YAML
+    #
+    # @return [String] A string containing response as YAML
+
+    def to_yaml!
+      begin
+        @body = YAML::dump(JSON.parse(@body))
+      rescue Exception => e
+        raise ParseError.new(e), e
+      end
+    end
+
+  end
+  
+end

data/lib/mailgun/exceptions/exceptions.rb

@@ -0,0 +1,27 @@
+module Mailgun
+
+  class ParameterError < RuntimeError
+    attr_reader :object
+
+    def initialize(message=nil, object=nil)
+      @object = object
+    end
+  end
+
+  class CommunicationError < RuntimeError
+    attr_reader :object
+
+    def initialize(message=nil, object=nil)
+      @object = object
+    end
+  end
+
+  class ParseError < RuntimeError
+    attr_reader :object
+
+    def initialize(message=nil, object=nil)
+      @object = object
+    end
+  end
+
+end

data/lib/mailgun/lists/opt_in_handler.rb

@@ -0,0 +1,46 @@
+require 'digest'
+require 'json'
+require 'uri'
+require 'base64'
+
+module Mailgun
+
+  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)
+      hash = {'s' => Digest::MD5.hexdigest("#{secret_app_id}#{recipient_address}"),
+              'l' => mailing_list,
+              'r' => recipient_address}
+
+      URI.escape(Base64.encode64(JSON.generate(hash)))
+    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)
+      url_parameters = JSON.parse(Base64.decode64(URI.unescape(unique_hash)))
+      generated_hash = Digest::MD5.hexdigest("#{secret_app_id}#{url_parameters['r']}")
+      hash_provided = url_parameters['s']
+
+      if(generated_hash == hash_provided)
+        return {'recipient_address' => url_parameters['r'], 'mailing_list' => url_parameters['l']}
+      else
+        return false
+      end
+    end
+
+  end
+  
+end

data/lib/mailgun/messages/batch_message.rb

@@ -0,0 +1,139 @@
+require 'mailgun/messages/message_builder'
+require 'mailgun'
+require "mailgun/exceptions/exceptions"
+
+
+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
+
+    def initialize(client, domain)
+      @client = client
+      @recipient_variables = {}
+      @domain = domain
+      @message_ids = {}
+      super()
+    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)
+      if (@counters[:recipients][recipient_type] == 1000)
+        send_message(@message)
+      end
+
+      compiled_address = parse_address(address, variables)
+      @message[recipient_type] = compiled_address
+      if recipient_type != :from
+        store_recipient_variables(recipient_type, address, variables)
+      end
+      if @counters[:recipients].has_key?(recipient_type)
+        @counters[:recipients][recipient_type] += 1
+      end
+    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()
+      if any_recipients_left?
+        send_message(@message)
+      end
+      @message_ids
+    end
+    
+    private
+
+    # This method determines if it's necessary to send another batch.
+    #
+    # @return [Boolean]
+
+    def any_recipients_left?
+      if @counters[:recipients][:to] > 0
+        return true
+      elsif @counters[:recipients][:cc] > 0
+        return true
+      elsif @counters[:recipients][:bcc] > 0
+        return true
+      else
+        return false
+      end
+    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(message)
+      @message["recipient-variables"] = JSON.generate(@recipient_variables)
+      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)
+      if not variables
+        variables = {:id => @counters[:recipients][recipient_type]}
+      end
+      @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 { |a| count = a[1] + count}
+      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,321 @@
+require 'multimap'
+require 'time'
+require 'json'
+
+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
+
+    def initialize()
+      @message = Multimap.new
+      @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.
+    #
+    # @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 (@counters[:recipients][recipient_type] == 1000)
+        raise ParameterError.new("Too many recipients added to message.", address)
+      end
+
+      compiled_address = parse_address(address, variables)
+      @message[recipient_type] = compiled_address
+
+      if @counters[:recipients].has_key?(recipient_type)
+        @counters[:recipients][recipient_type] += 1
+      end
+    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 set_from_address(address, variables=nil)
+      add_recipient("from", address, variables)
+    end
+
+    # Set a subject for the message object
+    #
+    # @param [String] subject The subject for the email.
+    # @return [void]
+
+    def set_subject(subject=nil)
+      simple_setter(:subject, subject)
+    end
+
+    # Set a text body for the message object
+    #
+    # @param [String] text_body The text body for the email.
+    # @return [void]
+
+    def set_text_body(text_body=nil)
+      simple_setter(: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 set_html_body(html_body=nil)
+      simple_setter(:html, html_body)
+    end
+
+    # Adds a series of attachments, when called upon.
+    #
+    # @param [String] 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)
+      if attachment.is_a?(String)
+        attachment = File.open(attachment, "r")
+      end
+      if !attachment.is_a?(File) || !attachment.respond_to?(:read)
+        raise ParameterError.new("Unable to access attachment file object.")
+      end
+      if !filename.nil?
+        attachment.instance_eval "def original_filename; '#{filename}'; end"
+      end
+      @message[:attachment] = attachment
+    end
+
+    # Adds an inline image to the mesage object.
+    #
+    # @param [String] 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)
+      if inline_image.is_a?(String)
+        inline_image = File.open(inline_image, "r")
+      end
+      if !inline_image.is_a?(File) || !inline_image.respond_to?(:read)
+        raise ParameterError.new("Unable to access attachment file object.")
+      end
+      if !filename.nil?
+        inline_image.instance_eval "def original_filename; '#{filename}'; end"
+      end
+      @message[:inline] = inline_image
+    end
+
+    # Send a message in test mode. (The message won't really be sent to the recipient)
+    #
+    # @param [Boolean] test_mode The boolean or string value (will fix itself)
+    # @return [void]
+
+    def set_test_mode(test_mode)
+      simple_setter("o:testmode", bool_lookup(test_mode))
+    end
+
+    # Turn DKIM on or off per message
+    #
+    # @param [Boolean] dkim The boolean or string value(will fix itself)
+    # @return [void]
+
+    def set_dkim(dkim)
+      simple_setter("o:dkim", bool_lookup(dkim))
+    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)
+      if (@counters[:attributes][:campaign_id] == 3)
+        raise ParameterError.new("Too many campaigns added to message.", campaign_id)
+      end
+      @message["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] == 3)
+        raise ParameterError.new("Too many tags added to message.", tag)
+      end
+      @message["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 set_open_tracking(tracking)
+      simple_setter("o:tracking-opens", bool_lookup(tracking))
+    end
+
+    # Turn Click Tracking on and off, on a per message basis.
+    #
+    # @param [String] tracking True, False, or HTML (for HTML only tracking)
+    # @return [void]
+
+    def set_click_tracking(tracking)
+      simple_setter("o:tracking-clicks", bool_lookup(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 set_delivery_time(timestamp)
+      time_str = DateTime.parse(timestamp)
+      simple_setter("o:deliverytime", time_str.rfc2822)
+    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 set_custom_data(name, data)
+      if data.is_a?(Hash)
+        data = data.to_json
+      elsif data.is_a?(String)
+        if not valid_json?(data)
+          begin
+            data = JSON.generate(data)
+          rescue
+            raise ParameterError.new("Failed to parse provided JSON.", data)
+          end
+        end
+      end
+      simple_setter("v:#{name}", data)
+    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 paramter.
+    # @return [void]
+
+    def add_custom_parameter(name, data)
+      @message[name] = data
+    end
+
+    private
+
+    # 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)
+      if value.nil?
+        if @message.include?(parameter)
+          @message.replace({parameter => ''})
+        else
+          @message[parameter] = ''
+        end
+      else
+        if @message.include?(parameter)
+          @message.replace({parameter => value})
+        else
+          @message[parameter] = value
+        end
+      end
+    end
+
+    # Converts boolean type to string
+    #
+    # @param [String] value The item to convert
+    # @return [void]
+
+    def bool_lookup(value)
+      if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        return value ? "yes" : "no"
+      elsif value.is_a?(String)
+        value.downcase!
+        if ['true', 'yes', 'yep'].include? value
+          return "yes"
+        elsif ['false', 'no', 'nope'].include? value 
+          return "no"
+        else
+          return value
+        end
+      else
+        return value
+      end
+    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
+      return false
+    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, variables)
+      if variables.nil?
+        return address
+      end
+      first, last = ''
+      if variables.has_key?('first')
+        first = variables['first']
+        if variables.has_key?('last')
+          last = variables['last']
+        end
+        full_name = "#{first} #{last}".strip
+      end
+      if defined?(full_name)
+        return "'#{full_name}' <#{address}>"
+      end
+      return address
+    end
+
+  end
+  
+end