mailgun-ruby 1.1.2 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7191c12a6dc2a08445f7cb623f10608e9208c9d2
-  data.tar.gz: 5033b5cd5eb92f6ce5c2d678222f8c7d9d118c78
+  metadata.gz: a0e2728bd22128bd8d8209b0b5b1f6c941501f5a
+  data.tar.gz: b8f2c9a4cccdccd328142fae44a14be8154cb9d6
 SHA512:
-  metadata.gz: 38dd19ded277a5566d738c88368b811607762ee258eaca48f7f1afe069b6fd84672bef1e6fb9637b028c06762c840dbd84b7a722ec2e6b7bd51828f99eedd406
-  data.tar.gz: a87aab066601ca346f897d551ff37165b862654d378c156df84b9443714c0795b9bb7299e16e0bce5666511d28900b0d0d7677ffe7ff826b2681d1d9c96ea7cc
+  metadata.gz: 779520a0342a79b09dbd433f516d969234636b7585d14ab3f7f827a08071611b55b2fc1b81c7aa6215a7ac6fb08535f95a792109a309557e5e612c6be5d02dc1
+  data.tar.gz: 0ad45cd374509486f177649b7d6dd3f3e3df7b14b3c40643657699670f6acb6e0b710200bc1df19a1bc7710795fe654dd6efcd1590e05650de00460898aca0e0

data/README.md

@@ -27,6 +27,8 @@ Usage
 Here's how to send a message using the library:
 
 ```ruby
+require 'mailgun' 
+
 # First, instantiate the Mailgun Client with your API key
 mg_client = Mailgun::Client.new 'your-api-key'
 
@@ -139,8 +141,8 @@ For usage examples on each API endpoint, head over to our official documentation
 pages. Or the [Snippets](Snippets.md) file.
 
 This SDK includes the following components:
-- [Message Builder](Messages.md)
-- [Batch Message](Messages.md)
+- [Message Builder](MessageBuilder.md)
+- [Batch Message](MessageBuilder.md)
 - [Opt-In Handler](OptInHandler.md)
 - [Domains](Domains.md)
 - [Webhooks](Webhooks.md)

data/Snippets.md

@@ -41,8 +41,7 @@ mg_client.send_message "sending_domain.com", data
 
 ```ruby
 # Don't include a file, pull the file to a string
-mime_string = '
-From: Bob Sample <example@example.com>
+mime_string = 'From: Bob Sample <example@example.com>
 MIME-Version: 1.0
 Content-Type: multipart/mixed;
 boundary="--boundary-goes-here--"

data/lib/mailgun/client.rb

@@ -82,9 +82,10 @@ module Mailgun
     # with. Be sure to include your domain, where necessary.
     # @param [Hash] data This should be a standard Hash
     # containing required parameters for the requested resource.
+    # @param [Hash] headers Additional headers to pass to the resource.
     # @return [Mailgun::Response] A Mailgun::Response object.
-    def post(resource_path, data)
-      response = @http_client[resource_path].post(data)
+    def post(resource_path, data, headers = {})
+      response = @http_client[resource_path].post(data, headers)
       Response.new(response)
     rescue => err
       raise communication_error err
@@ -94,8 +95,9 @@ module Mailgun
     #
     # @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
+    # @param [Hash] params This should be a standard Hash
     # containing required parameters for the requested resource.
+    # @param [String] accept Acceptable Content-Type of the response body.
     # @return [Mailgun::Response] A Mailgun::Response object.
     def get(resource_path, params = nil, accept = '*/*')
       if params

data/lib/mailgun/messages/message_builder.rb

@@ -23,11 +23,18 @@ 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
@@ -53,6 +60,19 @@ 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 simple_setter 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)
+      @message["h:reply-to"] = compiled_address
+    end
+
     # Set a subject for the message object
     #
     # @param [String] subject The subject for the email.

data/lib/mailgun/suppressions.rb

@@ -0,0 +1,267 @@
+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] Array of invalid bounce hashes.
+    # @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
+        split_return = create_bounces data[999..-1]
+        data = data[0..998]
+      elsif data.length == 0 then
+        []
+      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] Array of invalid unsubscribe hashes.
+    # @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
+        split_return = create_unsubscribes data[999..-1]
+        data = data[0..998]
+      elsif data.length == 0 then
+        []
+      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] Array of invalid complaint hashes.
+    # @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
+        split_return = create_complaints data[999..-1]
+        data = data[0..998]
+      elsif data.length == 0 then
+        []
+      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.3'
 end

data/lib/railgun.rb

@@ -0,0 +1,10 @@
+require 'action_mailer'
+require 'active_support/rescuable'
+
+require 'railgun/attachment'
+require 'railgun/errors'
+require 'railgun/mailer'
+require 'railgun/message'
+
+module Railgun
+end

data/lib/railgun/attachment.rb

@@ -0,0 +1,21 @@
+module Railgun
+
+  class Attachment < StringIO
+
+    attr_reader :source_filename, :content_type, :path
+
+    def initialize(attachment, *args)
+      @path = ''
+      if args.detect { |opt| opt[:inline] }
+        basename = @source_filename = attachment.cid
+      else
+        basename = @source_filename = attachment.filename
+      end
+
+      @content_type = attachment.content_type.split(';')[0]
+
+      super attachment.body.decoded
+    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,162 @@
+require 'action_mailer'
+require 'mailgun'
+require 'rails'
+require 'railgun/errors'
+
+module Railgun
+
+  # Railgun::Mailer is an ActionMailer provider for sending mail through
+  # Mailgun.
+  class Mailer
+
+    # [Hash] config ->
+    #   Requires *at least* `api_key` and `domain` keys.
+    attr_accessor :config, :domain
+
+    # 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("Config requires `#{k}` key", @config) unless @config.has_key? k
+      end
+
+      @mg_client = Mailgun::Client.new(config[:api_key])
+      @domain = @config[:domain]
+
+      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_message = Railgun.transform_for_mailgun(mail)
+      response = @mg_client.send_message(@domain, mg_message)
+
+      if response.code == 200 then
+        mg_id = response.body['id']
+        mail.message_id = mg_id
+      end
+      response
+    end
+
+    def mailgun_client
+      @mg_obj
+    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.
+  #
+  # @param [Mail::Message] mail message to transform
+  #
+  # @return [Hash] transformed message hash
+  def transform_for_mailgun(mail)
+    message = build_message_object(mail)
+
+    # v:* attributes (variables)
+    mail.mailgun_variables.try(:each) do |k, v|
+      message["v:#{k}"] = v
+    end
+
+    # o:* attributes (options)
+    mail.mailgun_options.try(:each) do |k, v|
+      message["o:#{k}"] = v
+    end
+
+    # h:* attributes (headers)
+    mail.mailgun_headers.try(:each) do |k, v|
+      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|
+      v.nil? or (v.respond_to?(:empty) and 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.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
+
+    return mb.message if mail.attachments.empty?
+
+    mail.attachments.each do |attach|
+      if attach.inline?
+        mb.add_inline_image Attachment.new(attach, encoding: 'ascii-8bit', inline: true)
+      else
+        mb.add_attachment Attachment.new(attach, encoding: 'ascii-8bit')
+      end
+    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
+      (mail.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
+      (mail.text_part || mail).body.decoded || nil
+    rescue
+      nil
+    end
+  end
+
+end
+
+ActionMailer::Base.add_delivery_method :mailgun, Railgun::Mailer