mailgun-ruby 1.1.0 → 1.2.5

data/lib/mailgun/response.rb

@@ -1,3 +1,5 @@
+require 'ostruct'
+
 module Mailgun
   # A Mailgun::Response object is instantiated for each response generated
   # by the Client request. The Response object supports deserialization of
@@ -10,6 +12,11 @@ module Mailgun
     #   slightly different
     attr_accessor :body, :code
 
+    def self.from_hash(h)
+      # Create a "fake" response object with the data passed from h
+      self.new OpenStruct.new(h)
+    end
+
     def initialize(response)
       @body = response.body
       @code = response.code

data/lib/mailgun/suppressions.rb

@@ -0,0 +1,273 @@
+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.
+          # However, unsubscribes contain an array of tags
+          if v.is_a? Array
+            unsubscribe[k] = v.map(&:to_s)
+          elsif !v.is_a? String
+            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.0'
+  VERSION = '1.2.5'
 end

data/lib/mailgun/webhooks/webhooks.rb

@@ -46,7 +46,7 @@ module Mailgun
     # Returns a Boolean of whether the webhook was created
     def create(domain, action, url = '')
       res = @client.post("domains/#{domain}/webhooks", id: action, url: url)
-      res.to_h['webhook'] == url && res.to_h[message] == 'Webhook has been created'
+      res.to_h['webhook']['url'] == url && res.to_h['message'] == 'Webhook has been created'
     end
     alias_method :add, :create
     alias_method :add_webhook, :create

data/lib/mailgun-ruby.rb

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

data/lib/mailgun.rb

@@ -7,6 +7,7 @@ require 'mailgun/version'
 require 'mailgun/client'
 require 'mailgun/response'
 require 'mailgun/chains'
+require 'mailgun/address'
 require 'mailgun/lists/opt_in_handler'
 require 'mailgun/messages/batch_message'
 require 'mailgun/messages/message_builder'

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

data/lib/railgun/mailer.rb

@@ -0,0 +1,253 @@
+require 'action_mailer'
+require 'json'
+require 'mailgun'
+require 'rails'
+require 'railgun/errors'
+
+module Railgun
+
+  # Railgun::Mailer is an ActionMailer provider for sending mail through
+  # Mailgun.
+  class Mailer
+
+    # List of the headers that will be ignored when copying headers from `mail.header_fields`
+    IGNORED_HEADERS = %w[ to from subject reply-to mime-version template ]
+
+    # [Hash] config ->
+    #   Requires *at least* `api_key` and `domain` keys.
+    attr_accessor :config, :domain, :settings
+
+    # Initialize the Railgun mailer.
+    #
+    # @param [Hash] config Hash of config values, typically from `app_config.action_mailer.mailgun_config`
+    def initialize(config)
+      @config = config
+
+      [:api_key, :domain].each do |k|
+        raise Railgun::ConfigurationError.new("Config requires `#{k}` key", @config) unless @config.has_key?(k)
+      end
+
+      @mg_client = Mailgun::Client.new(
+        config[:api_key],
+        config[:api_host] || 'api.mailgun.net',
+        config[:api_version] || 'v3',
+        config[:api_ssl].nil? ? true : config[:api_ssl],
+        false,
+        config[:timeout],
+      )
+      @domain = @config[:domain]
+
+      # To avoid exception in mail gem v2.6
+      @settings = { return_response: true }
+
+      if (@config[:fake_message_send] || false)
+        Rails.logger.info "NOTE: fake message sending has been enabled for mailgun-ruby!"
+        @mg_client.enable_test_mode!
+      end
+    end
+
+    def deliver!(mail)
+      @mg_domain = set_mg_domain(mail)
+      mail[:domain] = nil if mail[:domain].present?
+
+      mg_message = Railgun.transform_for_mailgun(mail)
+      response = @mg_client.send_message(@mg_domain, mg_message)
+
+      if response.code == 200 then
+        mg_id = response.to_h['id']
+        mail.message_id = mg_id
+      end
+      response
+    end
+
+    def mailgun_client
+      @mg_client
+    end
+
+    private
+
+    # Set @mg_domain from mail[:domain] header if present, then remove it to prevent being sent.
+    def set_mg_domain(mail)
+      return mail[:domain].value if mail[:domain]
+      domain
+    end
+
+  end
+
+  module_function
+
+  # Performs a series of transformations on the `mailgun*` attributes.
+  # After prefixing them with the proper option type, they are added to
+  # the message hash where they will then be sent to the API as JSON.
+  #
+  # It is important to note that headers set in `mailgun_headers` on the message
+  # WILL overwrite headers set via `mail.headers()`.
+  #
+  # @param [Mail::Message] mail message to transform
+  #
+  # @return [Hash] transformed message hash
+  def transform_for_mailgun(mail)
+    message = build_message_object(mail)
+
+    # o:* attributes (options)
+    mail.mailgun_options.try(:each) do |k, v|
+      message["o:#{k}"] = v.dup
+    end
+
+    # t:* attributes (options)
+    mail.mailgun_template_variables.try(:each) do |k, v|
+      message["t:#{k}"] = v.dup
+    end
+
+    # support for using ActionMailer's `headers()` inside of the mailer
+    # note: this will filter out parameters such as `from`, `to`, and so forth
+    #       as they are accepted as POST parameters on the message endpoint.
+
+    msg_headers = Hash.new
+
+    # h:* attributes (headers)
+
+    # Let's set all of these headers on the [Mail::Message] so that
+    # the are created inside of a [Mail::Header] instance and processed there.
+    mail.headers(mail.mailgun_headers || {})
+    mail.header_fields.each do |field|
+      header = field.name.downcase
+      if msg_headers.include? header
+        msg_headers[header] = [msg_headers[header], field.value].flatten
+      else
+        msg_headers[header] = field.value
+      end
+    end
+
+    msg_headers.each do |k, v|
+      if Railgun::Mailer::IGNORED_HEADERS.include? k.downcase
+        Rails.logger.debug("[railgun] ignoring header (using envelope instead): #{k}")
+        next
+      end
+
+      # Cover cases like `cc`, `bcc` where parameters are valid
+      # headers BUT they are submitted as separate POST params
+      # and already exist on the message because of the call to
+      # `build_message_object`.
+      if message.include? k.downcase
+        Rails.logger.debug("[railgun] ignoring header (already set): #{k}")
+        next
+      end
+
+      message["h:#{k}"] = v
+    end
+
+    # recipient variables
+    message['recipient-variables'] = mail.mailgun_recipient_variables.to_json if mail.mailgun_recipient_variables
+
+    # reject blank values
+    message.delete_if do |k, v|
+      return true if v.nil?
+
+      # if it's an array remove empty elements
+      v.delete_if { |i| i.respond_to?(:empty?) && i.empty? } if v.is_a?(Array)
+
+      v.respond_to?(:empty?) && v.empty?
+    end
+
+    return message
+  end
+
+  # Acts on a Rails/ActionMailer message object and uses Mailgun::MessageBuilder
+  # to construct a new message.
+  #
+  # @param [Mail::Message] mail message to transform
+  #
+  # @returns [Hash] Message hash from Mailgun::MessageBuilder
+  def build_message_object(mail)
+    mb = Mailgun::MessageBuilder.new
+
+    mb.from mail[:from]
+    mb.reply_to(mail[:reply_to].to_s) if mail[:reply_to].present?
+    mb.template(mail[:template].to_s) if mail[:template].present?
+    mb.subject mail.subject
+    mb.body_html extract_body_html(mail)
+    mb.body_text extract_body_text(mail)
+
+    [:to, :cc, :bcc].each do |rcpt_type|
+      addrs = mail[rcpt_type] || nil
+      case addrs
+      when String
+        # Likely a single recipient
+        mb.add_recipient rcpt_type.to_s, addrs
+      when Array
+        addrs.each do |addr|
+          mb.add_recipient rcpt_type.to_s, addr
+        end
+      when Mail::Field
+        mb.add_recipient rcpt_type.to_s, addrs.to_s
+      end
+    end
+
+    # v:* attributes (variables)
+    mail.mailgun_variables.try(:each) do |name, value|
+      mb.variable(name, value)
+    end
+
+    return mb.message if mail.attachments.empty?
+
+    mail.attachments.each do |attach|
+      attach = Attachment.new(attach, encoding: 'ascii-8bit', inline: attach.inline?)
+      attach.attach_to_message! mb
+    end
+
+    return mb.message
+  end
+
+  # Returns the decoded HTML body from the Mail::Message object if available,
+  # otherwise nil.
+  #
+  # @param [Mail::Message] mail message to transform
+  #
+  # @return [String]
+  def extract_body_html(mail)
+    begin
+      retrieve_html_part(mail).body.decoded || nil
+    rescue
+      nil
+    end
+  end
+
+  # Returns the decoded text body from the Mail::Message object if it is available,
+  # otherwise nil.
+  #
+  # @param [Mail::Message] mail message to transform
+  #
+  # @return [String]
+  def extract_body_text(mail)
+    begin
+      retrieve_text_part(mail).body.decoded || nil
+    rescue
+      nil
+    end
+  end
+
+  # Returns the mail object from the Mail::Message object if text part exists,
+  # (decomposing multipart into individual format if necessary)
+  # otherwise nil.
+  #
+  # @param [Mail::Message] mail message to transform
+  #
+  # @return [Mail::Message] mail message with its content-type = text/plain
+  def retrieve_text_part(mail)
+    return mail.text_part if mail.multipart?
+    (mail.mime_type =~ /^text\/plain$/i) && mail
+  end
+
+  # Returns the mail object from the Mail::Message object if html part exists,
+  # (decomposing multipart into individual format if necessary)
+  # otherwise nil.
+  #
+  # @param [Mail::Message] mail message to transform
+  #
+  # @return [Mail::Message] mail message with its content-type = text/html
+  def retrieve_html_part(mail)
+    return mail.html_part if mail.multipart?
+    (mail.mime_type =~ /^text\/html$/i) && mail
+  end
+end

data/lib/railgun/message.rb

@@ -0,0 +1,18 @@
+require 'mail'
+require 'mailgun/messages/message_builder'
+require 'railgun/attachment'
+require 'railgun/errors'
+
+module Mail
+
+  class Message
+
+    # Attributes to hold Mailgun-specific information
+    attr_accessor :mailgun_variables,
+                  :mailgun_options,
+                  :mailgun_recipient_variables,
+                  :mailgun_headers,
+                  :mailgun_template_variables
+
+  end
+end

data/lib/railgun/railtie.rb

@@ -0,0 +1,10 @@
+require 'railgun/mailer'
+
+module Railgun
+  class Railtie < ::Rails::Railtie
+    ActiveSupport.on_load(:action_mailer) do
+      add_delivery_method :mailgun, Railgun::Mailer
+      ActiveSupport.run_load_hooks(:mailgun_mailer, Railgun::Mailer)
+    end
+  end
+end

data/lib/railgun.rb

@@ -0,0 +1,8 @@
+require 'railgun/railtie'
+require 'railgun/attachment'
+require 'railgun/errors'
+require 'railgun/mailer'
+require 'railgun/message'
+
+module Railgun
+end