mailgun-ruby 1.1.9 → 1.2.13

data/lib/mailgun/messages/message_builder.rb

@@ -1,3 +1,4 @@
+require 'mime/types'
 require 'time'
 
 module Mailgun
@@ -124,7 +125,7 @@ module Mailgun
       add_file(:attachment, attachment, filename)
     end
 
-    # Adds an inline image to the mesage object.
+    # Adds an inline image to the message 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.
@@ -197,7 +198,9 @@ module Mailgun
     # @param [Boolean] tracking Boolean true or false.
     # @return [void]
     def track_opens(mode)
-      set_multi_simple('o:tracking-opens', bool_lookup(mode))
+      value = bool_lookup(mode)
+      set_single('o:tracking-opens', value)
+      set_multi_simple('o:tracking', value)
     end
 
     # Deprecated: 'set_open_tracking' is deprecated. Please use 'track_opens' instead.
@@ -211,7 +214,9 @@ module Mailgun
     # @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))
+      value = bool_lookup(mode)
+      set_single('o:tracking-clicks', value)
+      set_multi_simple('o:tracking', value)
     end
 
     # Depreciated: 'set_click_tracking. is deprecated. Please use 'track_clicks' instead.
@@ -269,8 +274,12 @@ module Mailgun
     # @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)
+      begin
+        jsondata = make_json data
+        set_single("v:#{name}", jsondata)
+      rescue Mailgun::ParameterError
+        set_single("v:#{name}", data)
+      end
     end
 
     # Add custom parameter to the message. A custom parameter is any parameter that
@@ -303,6 +312,38 @@ module Mailgun
       message_id data
     end
 
+    # Set name of a template stored via template API. See Templates for more information
+    # https://documentation.mailgun.com/en/latest/api-templates.html
+    #
+    # @param [String] tag A defined template name to use. Passing nil or
+    #   empty string will delete template key and value from @message hash.
+    # @return [void]
+    def template(template_name = nil)
+      key = 'template'
+      return @message.delete(key) if template_name.to_s.empty?
+      set_single(key, template_name)
+    end
+
+    # Set specific template version.
+    #
+    # @param [String] tag A defined template name to use. Passing nil or
+    #   empty string will delete template key and value from @message hash.
+    # @return [void]
+    def template_version(version = nil)
+      key = 't:version'
+      return @message.delete(key) if version.to_s.empty?
+      set_single(key, version)
+    end
+
+    # Turn off or on template rendering in the text part
+    # of the message in case of template sending.
+    #
+    # @param [Boolean] tracking Boolean true or false.
+    # @return [void]
+    def template_text(mode)
+      set_single('t:text', bool_lookup(mode))
+    end
+
     private
 
     # Sets a single value in the message hash where "multidict" features are not needed.
@@ -342,6 +383,7 @@ module Mailgun
     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
+      warn 'WARN: for bool type actions next values are preferred: true yes yep | false no nope | htmlonly'
       value
     end
 
@@ -364,7 +406,7 @@ module Mailgun
     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
+      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
@@ -387,9 +429,9 @@ module Mailgun
         full_name = vars['full_name']
       elsif vars['first'] || vars['last']
         full_name = "#{vars['first']} #{vars['last']}".strip
-      end 
+      end
 
-      return "'#{full_name}' <#{address}>" if defined?(full_name)
+      return "'#{full_name}' <#{address}>" if full_name
       address
     end
 
@@ -409,6 +451,12 @@ module Mailgun
         'Unable to access attachment file object.'
       ) unless attachment.respond_to?(:read)
 
+      if attachment.respond_to?(:path) && !attachment.respond_to?(:content_type)
+        mime_types = MIME::Types.type_for(attachment.path)
+        content_type = mime_types.empty? ? 'application/octet-stream' : mime_types[0].content_type
+        attachment.instance_eval "def content_type; '#{content_type}'; end"
+      end
+
       unless filename.nil?
         attachment.instance_variable_set :@original_filename, filename
         attachment.instance_eval 'def original_filename; @original_filename; end'

data/lib/mailgun/response.rb

@@ -58,5 +58,12 @@ module Mailgun
     rescue => err
       raise ParseError.new(err), err
     end
+    
+    # Returns true if response code is 2xx
+    # 
+    # @return [Boolean] A boolean that binarizes the response code result.
+    def success?
+      (200..299).include?(code)
+    end
   end
 end

data/lib/mailgun/subaccounts/subaccounts.rb

@@ -0,0 +1,84 @@
+require 'mailgun/exceptions/exceptions'
+
+module Mailgun
+
+  # A Mailgun::Subaccounts object is a simple CRUD interface to Mailgun Subaccounts.
+  # Uses Mailgun
+  class Subaccounts
+    attr_reader :client
+
+    # Public: creates a new Mailgun::Subaccounts instance.
+    # Defaults to Mailgun::Client
+    def initialize(client = Mailgun::Client.new(Mailgun.api_key, Mailgun.api_host || 'api.mailgun.net', 'v5'))
+      @client = client
+    end
+
+    # Public: Get subaccounts
+    # options - [Hash] of
+    #     limit  - [Integer] Maximum number of records to return. (10 by default)
+    #     skip     [Integer] Number of records to skip
+    #     sort     [Array] “asc” or “desc”
+    #     enabled  [boolean] (Optional) Returns all enabled/disabled subaccounts, defaults to all if omitted
+    #     headers       - [String] (Optional) Key Value json dictionary of headers to be stored with the subaccount.
+    #                     ex.('{"Subject": "{{subject}}"}')
+    #
+    # Returns [Array] A list of subaccounts (hash)
+    def list(options = {})
+      client.get("accounts/subaccounts", options).to_h!
+    end
+    alias_method :get_subaccounts, :list
+
+    # Public: Get subaccount information
+    #
+    # subaccount_id - [String] subaccount name to lookup for
+    # options - [Hash] of
+    #     headers       - [String] (Optional) Key Value json dictionary of headers to be stored with the subaccount.
+    #                     ex.('{"Subject": "{{subject}}"}')
+    #
+    # Returns [Hash] Information on the requested subaccount.
+    def info(subaccount_id, options = {})
+      fail(ParameterError, 'No Id of subaccount specified', caller) unless subaccount_id
+      client.get("accounts/subaccounts/#{subaccount_id}", options).to_h!
+    end
+
+    # Public: Add Subaccount
+    #
+    # name  - [String] Name of the subaccount being created
+    # options - [Hash] of
+    #     name - [String] Name of the subaccount being created.
+    #     headers       - [String] (Optional) Key Value json dictionary of headers to be stored with the subaccount.
+    #                     ex.('{"Subject": "{{subject}}"}')
+    #
+    # Returns [Hash] of created subaccount
+    def create(name, options = {})
+      fail(ParameterError, 'No name given to create subaccount', caller) unless name
+      client.post("accounts/subaccounts", options.merge!(name: name)).to_h!
+    end
+
+    # Public: Disable a subaccount
+    #
+    # subaccount_id - [String] subaccount name to disable
+    # options - [Hash] of
+    #     headers       - [String] (Optional) Key Value json dictionary of headers to be stored with the subaccount.
+    #                     ex.('{"Subject": "{{subject}}"}')
+    #
+    # Returns [Hash] Information on the requested subaccount.
+    def disable(subaccount_id, options = {})
+      fail(ParameterError, 'No Id of subaccount specified', caller) unless subaccount_id
+      client.post("accounts/subaccounts/#{subaccount_id}/disable", options).to_h!
+    end
+
+    # Public: Enable a subaccount
+    #
+    # subaccount_id - [String] subaccount name to enable
+    # options - [Hash] of
+    #     headers       - [String] (Optional) Key Value json dictionary of headers to be stored with the subaccount.
+    #                     ex.('{"Subject": "{{subject}}"}')
+    #
+    # Returns [Hash] Information on the requested subaccount.
+    def enable(subaccount_id, options = {})
+      fail(ParameterError, 'No Id of subaccount specified', caller) unless subaccount_id
+      client.post("accounts/subaccounts/#{subaccount_id}/enable", options).to_h!
+    end
+  end
+end

data/lib/mailgun/suppressions.rb

@@ -45,11 +45,11 @@ module Mailgun
     end
 
     def get_bounce(address)
-      @client.get("#{@domain}/bounces/#{address}", nil)
+      @client.get("#{@domain}/bounces/#{escape_address(address)}", nil)
     end
 
     def create_bounce(params = {})
-      @client.post("#{@domain/bounces}", params)
+      @client.post("#{@domain}/bounces", params)
     end
 
     # Creates multiple bounces on the Mailgun API.
@@ -100,7 +100,7 @@ module Mailgun
     end
 
     def delete_bounce(address)
-      @client.delete("#{@domain}/bounces/#{address}")
+      @client.delete("#{@domain}/bounces/#{escape_address(address)}")
     end
 
     def delete_all_bounces
@@ -118,7 +118,7 @@ module Mailgun
     end
 
     def get_unsubscribe(address)
-      @client.get("#{@domain}/unsubscribes/#{address}")
+      @client.get("#{@domain}/unsubscribes/#{escape_address(address)}")
     end
 
     def create_unsubscribe(params = {})
@@ -157,7 +157,10 @@ module Mailgun
 
         unsubscribe.each do |k, v|
           # Hash values MUST be strings.
-          if not v.is_a? String then
+          # 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
@@ -170,7 +173,7 @@ module Mailgun
     end
 
     def delete_unsubscribe(address, params = {})
-      @client.delete("#{@domain}/unsubscribes/#{address}")
+      @client.delete("#{@domain}/unsubscribes/#{escape_address(address)}")
     end
 
     ####
@@ -184,7 +187,7 @@ module Mailgun
     end
 
     def get_complaint(address)
-      @client.get("#{@domain}/complaints/#{address}", nil)
+      @client.get("#{@domain}/complaints/#{escape_address(address)}", nil)
     end
 
     def create_complaint(params = {})
@@ -236,11 +239,15 @@ module Mailgun
     end
 
     def delete_complaint(address)
-      @client.delete("#{@domain}/complaints/#{address}")
+      @client.delete("#{@domain}/complaints/#{escape_address(address)}")
     end
 
     private
 
+    def escape_address(address)
+      CGI.escape address
+    end
+
     def get_from_paging(uri, params = {})
       @client.get(uri, params)
     end

data/lib/mailgun/templates/templates.rb

@@ -0,0 +1,187 @@
+require 'mailgun/exceptions/exceptions'
+
+module Mailgun
+
+  # A Mailgun::Templates object is a simple CRUD interface to Mailgun Templates.
+  # Uses Mailgun
+  class Templates
+
+    # Public: creates a new Mailgun::Templates instance.
+    # Defaults to Mailgun::Client
+    def initialize(client = Mailgun::Client.new)
+      @client = client
+    end
+
+    # Public: Add template
+    #
+    # domain  - [String] Name of the domain for new template(ex. domain.com)
+    # options - [Hash] of
+    #     name - [String] Name of the template being stored.
+    #     description   - [String] Description of the template being stored
+    #     template      - [String] (Optional) Content of the template
+    #     tag           - [String] (Optional) Initial tag of the created version.
+    #     comment       - [String] (Optional) Version comment.
+    #     headers       - [String] (Optional) Key Value json dictionary of headers to be stored with the template.
+    #                     ex.('{"Subject": "{{subject}}"}')
+    #
+    # Returns [Hash] of created template
+    def create(domain, options = {})
+      fail(ParameterError, 'No domain given to store template on', caller) unless domain
+      @client.post("#{domain}/templates", options).to_h
+    end
+
+    # Public: Get template information
+    #
+    # domain        - [String] Domain name where template is stored
+    # template_name - [String] Template name to lookup for
+    # options - [Hash] of
+    #     active - [Boolean] (Optional) If this flag is set to yes the active version
+    #               of the template is included in the response.
+    #
+    # Returns [Hash] Information on the requested template.
+    def info(domain, template_name, options = {})
+      fail(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
+      fail(ParameterError, 'No template name given to find on provided domain', caller) unless template_name
+      @client.get("#{domain}/templates/#{template_name}", options).to_h!
+    end
+
+    # Public: Update the metadata information of the template
+    #
+    # domain        - [String] Domain name where template is stored
+    # template_name - [String] Template name to lookup for
+    # options - [Hash] of
+    #     description - [String] Updated description of the template
+    #
+    # Returns [Hash] of updated domain
+    def update(domain, template_name, options = {})
+      fail(ParameterError, 'No domain given to add on Mailgun', caller) unless domain
+      fail(ParameterError, 'No template name given to find on provided domain', caller) unless template_name
+      @client.put("#{domain}/templates/#{template_name}", options).to_h
+    end
+
+    # Public: Delete Template
+    # NOTE: This method deletes all versions of the specified template.
+    #
+    # domain        - [String] Domain name where template is stored
+    # template_name - [String] Template name to lookup for
+    #
+    # Returns [Boolean] if successful or not
+    def remove(domain, template_name)
+      fail(ParameterError, 'No domain given to remove on Mailgun', caller) unless domain
+      fail(ParameterError, 'No template name given to find on provided domain', caller) unless template_name
+      @client.delete("#{domain}/templates/#{template_name}").to_h['message'] == 'template has been deleted'
+    end
+    alias_method :delete, :remove
+    alias_method :delete_template, :remove
+
+    # Public: Get Templates
+    #
+    # domain - [String] Domain name where template is stored
+    # page   - [String] Name of a page to retrieve. first, last, next, prev
+    # limit  - [Integer] Maximum number of records to return. (100 by default)
+    # p      - [Integer] Pivot is used to retrieve records in chronological order
+    #
+    # Returns [Array] A list of templates (hash)
+    def list(domain, options = {})
+      fail(ParameterError, 'No domain given.', caller) unless domain
+      @client.get("#{domain}/templates", options).to_h['items']
+    end
+    alias_method :get_templates, :list
+
+    # Public: Delete Templates
+    # NOTE: This method deletes all stored templates for the domain.
+    #
+    # domain        - [String] Domain name where template is stored
+    #
+    # Returns [Boolean] if successful or not
+    def remove_all(domain)
+      fail(ParameterError, 'No domain given to remove on Mailgun', caller) unless domain
+      @client.delete("#{domain}/templates").to_h['message'] == 'templates have been deleted'
+    end
+    alias_method :delete_templates, :remove_all
+
+    # Public: Create a new version of a template
+    #
+    # domain        - [String] Name of the domain for new template(ex. domain.com)
+    # template_name - [String] Template name to lookup for
+    # options - [Hash] of
+    #     template      - [String] Content of the template
+    #     tag           - [String] Initial tag of the created version.
+    #     comment       - [String] (Optional) Version comment.
+    #     active        - [Boolean] (Optional) If this flag is set to yes, this version becomes active
+    #     headers       - [String] (Optional) Key Value json dictionary of headers to be stored with the template.
+    #                     ex.('{"Subject": "{{subject}}"}')
+    #
+    # Returns [Hash] of updated template
+    def create_version(domain, template_name, options = {})
+      fail(ParameterError, 'No domain given.', caller) unless domain
+      fail(ParameterError, 'No template name given.', caller) unless template_name
+      @client.post("#{domain}/templates/#{template_name}/versions", options).to_h
+    end
+
+    # Public: Get template version information
+    #
+    # domain        - [String] Domain name where template is stored
+    # template_name - [String] Template name to lookup for
+    # tag           - [String] Version tag to lookup for
+    #
+    # Returns [Hash] Information on the requested template + version.
+    def info_version(domain, template_name, tag)
+      fail(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
+      fail(ParameterError, 'No template name given to find on provided domain', caller) unless template_name
+      fail(ParameterError, 'No version tag given.', caller) unless tag
+      @client.get("#{domain}/templates/#{template_name}/versions/#{tag}").to_h!
+    end
+
+    # Public: Update the version of the template
+    #
+    # domain        - [String] Domain name where template is stored
+    # template_name - [String] Template name to lookup for
+    # tag           - [String] Version tag to lookup for
+    # options - [Hash] of
+    #     template      - [String] Content of the template
+    #     comment       - [String] (Optional) Version comment.
+    #     active        - [Boolean] (Optional) If this flag is set to yes, this version becomes active
+    #     headers       - [String] (Optional) Key Value json dictionary of headers to be stored with the template.
+    #                     ex.('{"Subject": "{{subject}}"}')
+    #
+    # Returns [Hash] of updated template's version
+    def update_version(domain, template_name, tag, options = {})
+      fail(ParameterError, 'No domain given.', caller) unless domain
+      fail(ParameterError, 'No template name given to find on provided domain.', caller) unless template_name
+      fail(ParameterError, 'No version tag given.', caller) unless tag
+      @client.put("#{domain}/templates/#{template_name}/versions/#{tag}", options).to_h
+    end
+
+    # Public: Delete the version of the template
+    #
+    # domain        - [String] Domain name where template is stored
+    # template_name - [String] Template name to lookup for
+    # tag           - [String] Version tag to lookup for
+    #
+    # Returns [Boolean] if successful or not
+    def delete_version(domain, template_name, tag)
+      fail(ParameterError, 'No domain given.', caller) unless domain
+      fail(ParameterError, 'No template name given to find on provided domain.', caller) unless template_name
+      fail(ParameterError, 'No version tag given.', caller) unless tag
+      @client.delete("#{domain}/templates/#{template_name}/versions/#{tag}")
+        .to_h['message'] == 'version has been deleted'
+    end
+
+    # Public: Get Template's Versions list
+    #
+    # domain        - [String] Domain name where template is stored
+    # template_name - [String] Template name to lookup for
+    # options - [Hash] of
+    # page   - [String] Name of a page to retrieve. first, last, next, prev
+    # limit  - [Integer] Maximum number of records to return. (100 by default)
+    # p      - [Integer] Pivot is used to retrieve records in chronological order
+    #
+    # Returns [Array] A list of template's versions (hash)
+    def template_versions_list(domain, template_name, options = {})
+      fail(ParameterError, 'No domain given.', caller) unless domain
+      fail(ParameterError, 'No template name given to find on provided domain.', caller) unless template_name
+      @client.get("#{domain}/templates/#{template_name}/versions", options).to_h
+    end
+  end
+end

data/lib/mailgun/version.rb

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

data/lib/mailgun/webhooks/webhooks.rb

@@ -58,7 +58,7 @@ module Mailgun
     #
     # Returns true or false
     def create_all(domain, url = '')
-      %w(bounce click deliver drop open spam unsubscribe).each do |action|
+      %w(accepted clicked complained delivered opened permanent_fail temporary_fail unsubscribed).each do |action|
         add_webhook domain, action, url
       end
       true
@@ -90,7 +90,7 @@ module Mailgun
     # Returns a Boolean on the success
     def remove_all(domain)
       fail Mailgun::ParameterError('Domain not provided to remove webhooks from') unless domain
-      %w(bounce click deliver drop open spam unsubscribe).each do |action|
+      %w(accepted clicked complained delivered opened permanent_fail temporary_fail unsubscribed).each do |action|
         delete_webhook domain, action
       end
     end

data/lib/mailgun-ruby.rb

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

data/lib/mailgun.rb

@@ -15,6 +15,8 @@ require 'mailgun/events/events'
 require 'mailgun/exceptions/exceptions'
 require 'mailgun/domains/domains'
 require 'mailgun/webhooks/webhooks'
+require 'mailgun/templates/templates'
+require 'mailgun/subaccounts/subaccounts'
 
 # Module for interacting with the sweet Mailgun API.
 #
@@ -22,10 +24,12 @@ require 'mailgun/webhooks/webhooks'
 module Mailgun
 
   class << self
-    attr_accessor :api_key,
+    attr_accessor :api_host,
+                  :api_key,
                   :api_version,
                   :protocol,
                   :mailgun_host,
+                  :proxy_url,
                   :test_mode,
                   :domain