mailgun-ruby 1.1.8 → 1.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 03bb73706b0d179b3f48cfa58f68acc8b0d716e7
-  data.tar.gz: 3fc860e152511f367033a5954ba95720a474fd01
+SHA256:
+  metadata.gz: eeb68d33e0686c3074e829fa7c33c1a9300c31bd9db3b7fde74abfdbdd681a31
+  data.tar.gz: dc0cd7912abb804476731ba487186a362595f7806d88f50bbbe2296da8eb0b5b
 SHA512:
-  metadata.gz: 0d1f7e536083087eb9c2423c8cb3cd54624b5d0a7fbfb96eb8740b06c2947c14d94542e6ef22439d0f0711d9627b5219e09b9ccab7408b454e20ad1531a07d56
-  data.tar.gz: 9e03a0244f385c15497856fe9c421d3d330a38309798313c88f3139a86b6fc163cf6234654e15a1c1faceca40b70ad590ff5caf02c3cefc2d225a4eb3bc2b852
+  metadata.gz: 9469121fbdd8341af7cc6ee395d35d8f487f556b67d8b6a0d2b6cd874f4bb1828384f9aff7c6751377fa56182b7c890947e40444f09d583d97aca8f90c41c642
+  data.tar.gz: 2f2b70e53e187c28ea3fcf3d3abc3f208886baca01732af0bb233c154bd171565790279620fe392259f3fa74151276d4e281389606d35ce60047b6f9a922a7cf

data/.travis.yml

@@ -1,10 +1,11 @@
 language: ruby
 sudo: false
 rvm:
-- 2.0.0
-- 2.1
-- 2.2
-- 2.3.1
+- 2.2.2
+- 2.2.10
+- 2.3.7
+- 2.4.4
+- 2.5.1
 script:
 - bundle install
 - bundle exec rake spec
@@ -17,7 +18,7 @@ deploy:
   gemspec: mailgun.gemspec
   on:
     tags: true
-    condition: "$TRAVIS_RUBY_VERSION == 2.3.1"
+    condition: "$TRAVIS_RUBY_VERSION == 2.5.1"
 notifications:
   slack:
     rooms:

data/Gemfile

@@ -3,4 +3,4 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in mailgun.gemspec
 gemspec
 
-gem 'json', '~> 1.8', platform: :mri_19
+gem 'json', '~> 2.1', platform: :mri_19

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.1.6'
+gem 'mailgun-ruby', '~>1.2.5'
 ```
 
 Usage
@@ -27,7 +27,7 @@ Usage
 Here's how to send a message using the library:
 
 ```ruby
-require 'mailgun'
+require 'mailgun-ruby'
 
 # First, instantiate the Mailgun Client with your API key
 mg_client = Mailgun::Client.new 'your-api-key'
@@ -56,6 +56,12 @@ domain = 'example.com'
 result = mg_client.get("#{domain}/events", {:event => 'delivered'})
 ```
 
+If you're using the EU domains, make sure you specify it when creating the client:
+
+```
+mg_client = Mailgun::Client.new 'your-api-key', 'api.eu.mailgun.net'
+```
+
 Rails
 -----
 
@@ -74,9 +80,25 @@ and replace `api-myapikey` and `mydomain.com` with your secret API key and domai
   config.action_mailer.mailgun_settings = {
     api_key: 'api-myapikey',
     domain: 'mydomain.com',
+    # api_host: 'api.eu.mailgun.net'  # Uncomment this line for EU region domains
   }
 ```
 
+To specify Mailgun options such as campaign or tags:
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome_email
+    mail(to: params[:to], subject: "Welcome!").tap do |message|
+      message.mailgun_options = {
+        "tag" => ["abtest-option-a", "beta-user"],
+        "tracking-opens" => true,
+        "tracking-clicks" => "htmlonly"
+      }
+    end
+  end
+end   
+```
+
 To get the Mailgun `message_id` after ActionMailer has successfully delivered the email:
 
 ```ruby

data/docs/Webhooks.md

@@ -31,7 +31,7 @@ hook.create 'my.perfect.domain', 'deliver', 'https://the.webhook.url/'
 hook.remove 'my.perfect.domain', 'deliver'
 
 # Remove all webhooks for a domain
-hook.remove 'my.perfect.domain'
+hook.remove_all 'my.perfect.domain'
 ```
 
 More Documentation

data/docs/railgun/Overview.md

@@ -0,0 +1,11 @@
+Overview
+========
+
+Railgun is a Rails add-on that allows ActionMailer to send via the Mailgun API.
+
+See [railgun-sample](https://github.com/pirogoeth/railgun-sample/) for examples of integrating Railgun with your Rails app.
+
+
+## Table of Contents
+
+- [Parameters](/docs/railgun/Parameters.md)

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/lib/mailgun/client.rb

@@ -14,13 +14,20 @@ module Mailgun
                    api_host = 'api.mailgun.net',
                    api_version = 'v3',
                    ssl = true,
-                   test_mode = false)
+                   test_mode = false,
+                   timeout = nil,
+                   proxy_url = nil)
+
+      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
 
@@ -59,11 +66,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,
           }
         )
@@ -195,5 +204,17 @@ module Mailgun
       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 containg at least 1 recipient',
+        working_domain
+      ) if message.fetch('to', []).empty? && message.fetch(:to, []).empty?
+      fail ParameterError.new(
+        'Missing a `from` sender, message should containg at least 1 `from` sender',
+        working_domain
+      ) if message.fetch('from', []).empty? && message.fetch(:from, []).empty?
+    end
   end
 end

data/lib/mailgun/events/events.rb

@@ -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
     #
@@ -51,6 +52,7 @@ module Mailgun
       rescue NoMethodError
         api_message = "Unknown API error"
       end
+      api_message = api_message + ' - Invalid Domain or API key' if api_message == FORBIDDEN
 
       message = message || ''
       message = message + ': ' + api_message

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
@@ -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 prefered: true yes yep | false no nope | htmlonly'
       value
     end
 
@@ -379,10 +421,17 @@ module Mailgun
     def parse_address(address, vars)
       return address unless vars.is_a? Hash
       fail(Mailgun::ParameterError, 'Email address not specified') unless address.is_a? String
+      if vars['full_name'] != nil && (vars['first'] != nil || vars['last'] != nil)
+        fail(Mailgun::ParameterError, 'Must specify at most one of full_name or first/last. Vars passed: #{vars}')
+      end
 
-      full_name = "#{vars['first']} #{vars['last']}".strip
+      if vars['full_name']
+        full_name = vars['full_name']
+      elsif vars['first'] || vars['last']
+        full_name = "#{vars['first']} #{vars['last']}".strip
+      end 
 
-      return "'#{full_name}' <#{address}>" if defined?(full_name)
+      return "'#{full_name}' <#{address}>" if full_name
       address
     end
 
@@ -402,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/suppressions.rb

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

data/lib/mailgun/version.rb

@@ -1,4 +1,4 @@
 # It's the version. Yeay!
 module Mailgun
-  VERSION = '1.1.8'
+  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'] == 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/railgun/mailer.rb

@@ -1,4 +1,5 @@
 require 'action_mailer'
+require 'json'
 require 'mailgun'
 require 'rails'
 require 'railgun/errors'
@@ -9,6 +10,9 @@ module Railgun
   # 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
@@ -23,7 +27,14 @@ module Railgun
         raise Railgun::ConfigurationError.new("Config requires `#{k}` key", @config) unless @config.has_key?(k)
       end
 
-      @mg_client = Mailgun::Client.new(config[:api_key])
+      @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
@@ -36,8 +47,11 @@ module Railgun
     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(@domain, mg_message)
+      response = @mg_client.send_message(@mg_domain, mg_message)
 
       if response.code == 200 then
         mg_id = response.to_h['id']
@@ -47,7 +61,15 @@ module Railgun
     end
 
     def mailgun_client
-      @mg_obj
+      @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
@@ -58,24 +80,60 @@ module Railgun
   # 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)
 
-    # 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
+      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)
-    mail.mailgun_headers.try(:each) do |k, v|
+
+    # 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
 
@@ -84,7 +142,12 @@ module Railgun
 
     # reject blank values
     message.delete_if do |k, v|
-      v.nil? or (v.respond_to?(:empty) and v.empty?)
+      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
@@ -101,6 +164,7 @@ module Railgun
 
     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)
@@ -120,6 +184,11 @@ module Railgun
       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|
@@ -138,7 +207,7 @@ module Railgun
   # @return [String]
   def extract_body_html(mail)
     begin
-      (mail.html_part || mail).body.decoded || nil
+      retrieve_html_part(mail).body.decoded || nil
     rescue
       nil
     end
@@ -152,10 +221,33 @@ module Railgun
   # @return [String]
   def extract_body_text(mail)
     begin
-      (mail.text_part || mail).body.decoded || nil
+      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

@@ -11,7 +11,8 @@ module Mail
     attr_accessor :mailgun_variables,
                   :mailgun_options,
                   :mailgun_recipient_variables,
-                  :mailgun_headers
+                  :mailgun_headers,
+                  :mailgun_template_variables
 
   end
 end

data/lib/railgun/railtie.rb

@@ -2,8 +2,9 @@ require 'railgun/mailer'
 
 module Railgun
   class Railtie < ::Rails::Railtie
-    config.before_configuration do
-      ActionMailer::Base.add_delivery_method :mailgun, Railgun::Mailer
+    ActiveSupport.on_load(:action_mailer) do
+      add_delivery_method :mailgun, Railgun::Mailer
+      ActiveSupport.run_load_hooks(:mailgun_mailer, Railgun::Mailer)
     end
   end
 end