mailgun-ruby 1.1.9 → 1.2.12

data/docs/railgun/Parameters.md

@@ -0,0 +1,83 @@
+Parameters
+==========
+
+When sending messages via Railgun, it is often useful to set options, headers, and variables
+that should be added to the `POST` request against the messages endpoint.
+
+
+## Options
+
+See [Mailgun Docs | Sending](https://documentation.mailgun.com/en/latest/api-sending.html#sending) for available options.
+
+---
+
+To set options on a message:
+
+```ruby
+# app/controllers/some_controller.rb
+
+message = YourMailer.your_message(@args)
+
+message.mailgun_options ||= {
+  "tracking-opens" => "true",
+  "tracking-clicks" => "htmlonly",
+  "tag" => "some,tags",
+}
+```
+
+
+## Variables
+
+See [Mailgun Docs | Attaching Data to Messages](https://documentation.mailgun.com/en/latest/user_manual.html#attaching-data-to-messages) for more information.
+
+---
+
+To set variables on a message:
+
+```ruby
+# app/controllers/some_controller.rb
+
+message = YourMailer.your_message(@args)
+
+message.mailgun_variables ||= {
+  "user_info" => {"id" => "1", "name" => "tstark"},
+}
+```
+
+
+## Headers
+
+See [Mailgun Docs | Sending](https://documentation.mailgun.com/en/latest/api-sending.html#sending) for more information.
+
+---
+
+To set headers on a message *from a controller*:
+
+```ruby
+# app/controllers/some_controller.rb
+
+message = YourMailer.your_message(@args)
+
+message.mailgun_headers ||= {
+  "X-Sent-From-Rails" => "true",
+}
+```
+
+To set headers on a message *from a mailer*:
+
+```ruby
+# app/mailers/your_mailer.rb
+
+class YourMailer < ApplicationMailer
+  # ...
+
+  def your_message(args)
+    headers({
+      "X-Sent-From-Rails" => "true",
+    })
+
+    mail to: "some-address@example.org", ...
+  end
+
+end
+```

data/docs/railgun/Templates.md

@@ -0,0 +1,92 @@
+Mailgun - Templates
+====================
+
+This is the Mailgun Ruby *Templates* utilities.
+
+The below assumes you've already installed the Mailgun Ruby SDK in to your
+project. If not, go back to the master README for instructions.
+
+Usage - Templates
+-----------------------
+
+**Build a message with a template:**
+
+```ruby
+mb_obj = Mailgun::MessageBuilder.new
+
+mb_obj.from("sender@example.com")
+mb_obj.add_recipient("to", "recipient@example.com")
+mb_obj.subject ("This is the subject!")
+message.template('example.template.name')
+message.template_version('example.tag')
+
+mg_client.send_message "sending_domain.com", mb_obj
+```
+
+**Rails Example. Build a message with a template:**
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome_email
+    message = mail(
+    	from: "sender@example.com",
+    	to: "recipient@example.com",
+    	subject: "This is the subject!",
+    	template: 'example.template.name'
+    ) do |format|
+      format.text { render plain: "Test!" }
+    end
+    message.tap do |message|
+      message.mailgun_template_variables ||= {
+       'version' => 'example.tag'
+      }
+    end
+  end
+end
+```
+
+Template Handlebars
+-------------------------
+
+```
+{{#if english}}
+<p>This text is in the English language.</p>
+{{else if spanish}}
+<p>Este texto está en idioma español.</p>
+{{else if french}}
+<p>Ce texte est en langue française.</p>
+{{/if}}
+```
+
+In order to send the spanish version, for example:
+
+```ruby
+message.variable('spanish', 'true')
+```
+
+Also, Rails example:
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome_email
+    message = mail(
+    	from: "sender@example.com",
+    	to: "recipient@example.com",
+    	subject: "This is the subject!",
+    	template: 'example.template.name'
+    ) do |format|
+      format.text { render plain: "Test!" }
+    end
+    message.tap do |message|
+      message.mailgun_variables ||= {
+       'spanish' => 'true'
+      }
+    end
+  end
+end
+```
+
+More Documentation
+------------------
+See the official [Mailgun Templates Docs](https://documentation.mailgun.com/en/latest/api-templates.html)
+for more information

data/lib/mailgun/address.rb

@@ -4,45 +4,20 @@ module Mailgun
 
   # Mailgun::Address is a simple interface to the Email Validation API.
   class Address
-
-    # @param [String] api_key Mailgun API - public key
-    def initialize(api_key = "")
-      if api_key == "" then
-        fail ParameterError.new('Public API key is required for Mailgun::Address.initialize()', nil)
-      end
-
-      @api_key = api_key
-      @client = Mailgun::Client.new(api_key = api_key)
+    def initialize
+      @client = Mailgun::Client.new(Mailgun.api_key, Mailgun.api_host || 'api.mailgun.net', 'v4')
     end
 
     # Given an arbitrary address, validates it based on defined checks.
     #
     # @param [String] address Email address to validate (max 512 chars.)
     def validate(address, mailbox_verification = false)
-      params = {:address => address}
+      params = {address:  address}
       params[:mailbox_verification] = true if mailbox_verification
 
       res = @client.get "address/validate", params
       return res.to_h!
     end
-
-    # Parses a delimiter separated list of email addresses into two lists:
-    # parsed addresses and unparsable portions. The parsed addresses are a
-    # list of addresses that are syntactically valid (and optionally have
-    # DNS and ESP specific grammar checks) the unparsable list is a list
-    # of characters sequences that the parser was not able to understand.
-    # These often align with invalid email addresses, but not always.
-    # Delimiter characters are comma (,) and semicolon (;).
-    #
-    # @param [Array] addresses Addresses to parse
-    # @param [TrueClass|FalseClass] syntax_only Perform only syntax checks
-    def parse(addresses, syntax_only = true)
-      validate_addrs = addresses.join(";")
-
-      res = @client.get "address/parse", {:addresses => validate_addrs,
-                                          :syntax_only => syntax_only.to_s}
-      return res.to_h!
-    end
   end
 
 end

data/lib/mailgun/client.rb

@@ -11,16 +11,23 @@ module Mailgun
   class Client
 
     def initialize(api_key = Mailgun.api_key,
-                   api_host = 'api.mailgun.net',
-                   api_version = 'v3',
+                   api_host = Mailgun.api_host || 'api.mailgun.net',
+                   api_version = Mailgun.api_version  || 'v3',
                    ssl = true,
-                   test_mode = false)
+                   test_mode = false,
+                   timeout = nil,
+                   proxy_url = Mailgun.proxy_url)
+
+      rest_client_params = {
+        user: 'api',
+        password: api_key,
+        user_agent: "mailgun-sdk-ruby/#{Mailgun::VERSION}"
+      }
+      rest_client_params[:timeout] = timeout if timeout
 
       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}")
+      RestClient.proxy = proxy_url
+      @http_client = RestClient::Resource.new(endpoint, rest_client_params)
       @test_mode = test_mode
     end
 
@@ -38,6 +45,11 @@ module Mailgun
       @test_mode = false
     end
 
+    # Change API key
+    def set_api_key(api_key)
+      @http_client.options[:password] = api_key
+    end
+
     # Client is in test mode?
     #
     # @return [Boolean] Is the client set in test mode?
@@ -59,11 +71,13 @@ module Mailgun
     # containing required parameters for the requested resource.
     # @return [Mailgun::Response] A Mailgun::Response object.
     def send_message(working_domain, data)
+      perform_data_validation(working_domain, data)
+
       if test_mode? then
         Mailgun::Client.deliveries << data
         return Response.from_hash(
           {
-            :body => '{"id": "test-mode-mail@localhost", "message": "Queued. Thank you."}',
+            :body => "{\"id\": \"test-mode-mail-#{SecureRandom.uuid}@localhost\", \"message\": \"Queued. Thank you.\"}",
             :code => 200,
           }
         )
@@ -191,9 +205,30 @@ module Mailgun
     #
     # @param [StandardException] e upstream exception object
     def communication_error(e)
-      return CommunicationError.new(e.message, e.response) if e.respond_to? :response
+      if e.respond_to?(:response) && e.response
+        return case e.response.code
+        when Unauthorized::CODE
+          Unauthorized.new(e.message, e.response)
+        when BadRequest::CODE
+          BadRequest.new(e.message, e.response)
+        else
+          CommunicationError.new(e.message, e.response)
+        end
+      end
       CommunicationError.new(e.message)
     end
 
+    def perform_data_validation(working_domain, data)
+      message = data.respond_to?(:message) ? data.message : data
+      fail ParameterError.new('Missing working domain', working_domain) unless working_domain
+      fail ParameterError.new(
+        'Missing `to` recipient, message should contain at least 1 recipient',
+        working_domain
+      ) if message.fetch('to', []).empty? && message.fetch(:to, []).empty?
+      fail ParameterError.new(
+        'Missing a `from` sender, message should contain at least 1 `from` sender',
+        working_domain
+      ) if message.fetch('from', []).empty? && message.fetch(:from, []).empty?
+    end
   end
 end

data/lib/mailgun/domains/domains.rb

@@ -53,9 +53,10 @@ module Mailgun
     # domain  - [String] Name of the domain (ex. domain.com)
     # options - [Hash] of
     #     smtp_password - [String] Password for SMTP authentication
-    #     spam_action   - [String] disabled or tag
+    #     spam_action   - [String] disabled, blocked or tag
     #       Disable, no spam filtering will occur for inbound messages.
-    #       Tag, messages will be tagged wtih a spam header. See Spam Filter.
+    #       Block, inbound spam messages will not be delivered.
+    #       Tag, messages will be tagged with a spam header. See Spam Filter.
     #     wildcard      - [Boolean] true or false Determines whether the domain will accept email for sub-domains.
     #
     # Returns [Hash] of created domain
@@ -80,5 +81,22 @@ module Mailgun
     alias_method :delete, :remove
     alias_method :delete_domain, :remove
 
+    # Public: Update domain
+    #
+    # domain  - [String] Name of the domain (ex. domain.com)
+    # options - [Hash] of
+    #     spam_action   - [String] disabled, blocked or tag
+    #       Disable, no spam filtering will occur for inbound messages.
+    #       Block, inbound spam messages will not be delivered.
+    #       Tag, messages will be tagged wtih a spam header. See Spam Filter.
+    #     web_scheme    - [String] http or https
+    #       Set your open, click and unsubscribe URLs to use http or https
+    #     wildcard      - [Boolean] true or false Determines whether the domain will accept email for sub-domains.
+    #
+    # Returns [Hash] of updated domain
+    def update(domain, options = {})
+      fail(ParameterError, 'No domain given to add on Mailgun', caller) unless domain
+      @client.put("domains/#{domain}", options).to_h
+    end
   end
 end

data/lib/mailgun/events/events.rb

@@ -88,7 +88,7 @@ module Mailgun
     # 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
+      next_page_url     = paging && paging['next']      # gives nil when any one of the keys doesn'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)
@@ -101,7 +101,7 @@ module Mailgun
     # 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]
+      URI.parse(url).path[/\/v[\d]\/#{@domain}\/events\/(.+)/,1]
     rescue URI::InvalidURIError
       nil
     end

data/lib/mailgun/exceptions/exceptions.rb

@@ -34,6 +34,7 @@ module Mailgun
 
     # Public: fallback if there is no response code on the object
     NOCODE = 000
+    FORBIDDEN = 'Forbidden'
 
     # Public: initialization of new error given a message and/or object
     #
@@ -42,7 +43,11 @@ module Mailgun
     #
     def initialize(message = nil, response = nil)
       @response = response
-      @code = response.code || NOCODE
+      @code = if response.nil?
+                NOCODE
+              else
+                response.code
+              end
 
       begin
         api_message = JSON.parse(response.body)['message']
@@ -50,6 +55,8 @@ module Mailgun
         api_message = response.body
       rescue NoMethodError
         api_message = "Unknown API error"
+      rescue
+        api_message = 'Unknown API error'
       end
 
       message = message || ''
@@ -60,6 +67,26 @@ module Mailgun
       @code = NOCODE
       super(message, response)
     end
+  end
+
+  # Public: Class for managing unauthorized 401 errors
+  # Inherits from Mailgun::CommunicationError
+  class Unauthorized < CommunicationError
+    CODE = 401
 
+    def initialize(error_message, response)
+      error_message = error_message + ' - Invalid Domain or API key'
+      super(error_message, response)
+    end
+  end
+
+  # Public: Class for managing bad request 400 errors
+  # Inherits from Mailgun::CommunicationError
+  class BadRequest < CommunicationError
+    CODE = 400
+
+    def initialize(error_message, response)
+      super(error_message, response)
+    end
   end
 end

data/lib/mailgun/messages/batch_message.rb

@@ -111,6 +111,7 @@ module Mailgun
     # This method resets the message object to prepare for the next batch
     # of recipients.
     def reset_message
+      @recipient_variables = {}
       @message.delete('recipient-variables')
       @message.delete(:to)
       @message.delete(:cc)

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/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