mailgun-ruby 1.2.4 → 1.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64d4a0d5c1b85d58db90763fc5dbcd0f813f29bf30b328fdda6b7a019fbeb445
-  data.tar.gz: 2ddef97a1b88cd9d45c5e2d1b41df3b61e7b3a09a5dcbe4c3b0a62191335aeed
+  metadata.gz: 9dd7b99f66b317ffcbf86172b1534cdcb0ccf4b0b25a7b2e58599f20ef021f11
+  data.tar.gz: 8b130d3344fe905d20d4230cb8b178d29b092ffa6d21c3dbb085376aa53b50a0
 SHA512:
-  metadata.gz: 18df9ff784b8c39376420fcebe0b16a195318e63b70e6b6f5fb6139fd4cbd276ef1647844de6fd12c1e272906862ddfcdc85bb59ab29460dee6e0e02ec872ee8
-  data.tar.gz: 25547234506d03d471ea3f3bbfb46eb6c10e104147f6fc7cbe3b3228b966d31b5a3e53f423554c22f45360c119c5c015659b819559ef8d664c7c5ac47be09d00
+  metadata.gz: 34729e98ab4eb8cbfd04bdb5b7a090a30cb4a1961de9ef38e0adcab2d452e5873477d9b45de9703a6c5885b272a3d62429ece40ff6029bff2bbb0d8585a89410
+  data.tar.gz: 235e7aed52a937315019498bbb710e90b97128d9fdfad86bfb0995daf9d25f8185683769fd84b32e4eda4c64774b49a708a57da90ccd473e7d69f0e967eed581

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.2.4'
+gem 'mailgun-ruby', '~>1.2.6'
 ```
 
 Usage

data/docs/OptInHandler.md

@@ -100,4 +100,4 @@ Available Functions
 
 More Documentation
 ------------------
-See the official [Mailgun Docs](https://documentation.mailgun.com/api-sending.html) for more information.
+See the official [Mailgun Docs](https://documentation.mailgun.com/en/latest/api-sending.html) for more information.

data/lib/mailgun/client.rb

@@ -15,7 +15,8 @@ module Mailgun
                    api_version = 'v3',
                    ssl = true,
                    test_mode = false,
-                   timeout = nil)
+                   timeout = nil,
+                   proxy_url = nil)
 
       rest_client_params = {
         user: 'api',
@@ -25,6 +26,7 @@ module Mailgun
       rest_client_params[:timeout] = timeout if timeout
 
       endpoint = endpoint_generator(api_host, api_version, ssl)
+      RestClient.proxy = proxy_url
       @http_client = RestClient::Resource.new(endpoint, rest_client_params)
       @test_mode = test_mode
     end
@@ -64,13 +66,13 @@ module Mailgun
     # containing required parameters for the requested resource.
     # @return [Mailgun::Response] A Mailgun::Response object.
     def send_message(working_domain, data)
-      fail ParameterError.new('Missing working domain', working_domain) unless working_domain
+      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,
           }
         )
@@ -202,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/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,7 +55,10 @@ module Mailgun
         api_message = response.body
       rescue NoMethodError
         api_message = "Unknown API error"
+      rescue
+        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/message_builder.rb

@@ -198,7 +198,9 @@ module Mailgun
     # @param [Boolean] tracking Boolean true or false.
     # @return [void]
     def track_opens(mode)
-      set_single('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.
@@ -212,7 +214,9 @@ module Mailgun
     # @param [String] mode True, False, or HTML (for HTML only tracking)
     # @return [void]
     def track_clicks(mode)
-      set_single('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.
@@ -308,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.
@@ -347,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
 

data/lib/mailgun/version.rb

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

@@ -11,7 +11,7 @@ module Railgun
   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 ]
+    IGNORED_HEADERS = %w[ to from subject reply-to mime-version template ]
 
     # [Hash] config ->
     #   Requires *at least* `api_key` and `domain` keys.
@@ -47,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']
@@ -61,6 +64,14 @@ module Railgun
       @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
@@ -78,16 +89,16 @@ module Railgun
   def transform_for_mailgun(mail)
     message = build_message_object(mail)
 
-    # v:* attributes (variables)
-    mail.mailgun_variables.try(:each) do |k, v|
-      message["v:#{k}"] = JSON.dump(v)
-    end
-
     # 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.
@@ -153,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)
@@ -172,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|
@@ -233,5 +250,4 @@ module Railgun
     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/spec/integration/mailer_spec.rb

@@ -0,0 +1,67 @@
+require 'spec_helper'
+require 'json'
+require 'logger'
+require 'railgun'
+require 'mailgun'
+require 'mailgun/exceptions/exceptions'
+
+ActionMailer::Base.raise_delivery_errors = true
+Rails.logger = Logger.new('/dev/null')
+Rails.logger.level = Logger::DEBUG
+
+class UnitTestMailer < ActionMailer::Base
+  default from: 'unittest@example.org'
+
+  def plain_message(address, from, subject, headers)
+    headers(headers)
+    mail(to: address, from: from, subject: subject) do |format|
+      format.text { render plain: 'Test!' }
+      format.html { render html: '<p>Test!</p>'.html_safe }
+    end
+  end
+end
+
+vcr_opts = { :cassette_name => 'message_deliver' }
+
+describe 'Message deliver', vcr: vcr_opts do
+  let(:domain) { TESTDOMAIN }
+  let(:config) do
+    {
+      api_key: APIKEY,
+      domain: domain
+    }
+  end
+  let(:mail) { UnitTestMailer.plain_message("bob@#{domain}", "bob@#{domain}", 'subject', {}) }
+
+  it 'successfully delivers message' do
+    result = Railgun::Mailer.new(config).deliver!(mail)
+    result.to_h!
+
+    expect(result.body['message']).to eq('Queued. Thank you.')
+    expect(result.body).to include('id')
+    expect(result.code).to eq(200)
+  end
+end
+
+vcr_opts = { :cassette_name => 'mailer_invalid_domain' }
+
+describe 'Invalid domain', vcr: vcr_opts do
+  let(:domain) { 'not-our-doma.in' }
+  let(:config) do
+    {
+      api_key: APIKEY,
+      domain: domain
+    }
+  end
+  let(:mail) { UnitTestMailer.plain_message("bob@#{domain}", 'sally@not-our-doma.in' 'subject', {}) }
+
+  it 'raises expected error' do
+
+    Railgun::Mailer.new(config).deliver!(mail)
+  rescue Mailgun::CommunicationError => err
+    expect(err.message).to eq('401 Unauthorized: Forbidden - Invalid Domain or API key')
+  else
+    fail
+
+  end
+end

data/spec/integration/mailgun_spec.rb

@@ -63,6 +63,9 @@ describe 'The method send_message()', vcr: vcr_opts do
              :to => "bob@#{@domain}",
              :subject => "Test",
              :text => "Test Data" }
+    uuid = 'uuid'
+
+    allow(SecureRandom).to receive(:uuid).and_return(uuid)
 
     result = @mg_obj.send_message(@domain, data)
 
@@ -72,7 +75,7 @@ describe 'The method send_message()', vcr: vcr_opts do
     expect(result.body).to include("id")
 
     expect(result.code).to eq(200)
-    expect(result.body['id']).to eq("test-mode-mail@localhost")
+    expect(result.body['id']).to eq("test-mode-mail-#{uuid}@localhost")
     expect(result.body['message']).to eq("Queued. Thank you.")
   end
 

data/spec/unit/connection/test_client.rb

@@ -23,6 +23,7 @@ module Mailgun
     end
 
     def send_message(working_domain, data)
+      perform_data_validation(working_domain, data)
       case data
       when Hash
         if data.has_key?(:message)
@@ -45,7 +46,8 @@ module Mailgun
         Mailgun::Response.new(response_generator(@endpoint))
       rescue => e
         p e
-        raise CommunicationError.new(e), e.response
+        raise CommunicationError.new(e), e.response if e.respond_to? :response
+        raise CommunicationError.new(e.message)
       end
     end
 
@@ -75,6 +77,21 @@ module Mailgun
 
     private
 
+    def perform_data_validation(working_domain, data)
+      fail ParameterError.new('Missing working domain', working_domain) unless working_domain
+      return true unless data.is_a?(Hash) && data.present?
+      message = data.respond_to?(:message) ? data.message : data
+
+      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
+
     def response_generator(resource_endpoint)
       if resource_endpoint == "messages"
         t = Time.now

data/spec/unit/mailgun_spec.rb

@@ -37,8 +37,11 @@ describe 'The method send_message()' do
   end
 
   it 'opens the message MIME and sends the MIME message.' do
-    data = {'to' => 'joe@test.com',
-                    'message' => 'Sample Data/mime.txt'}
+    data = {
+      'to' => 'joe@test.com',
+      'message' => 'Sample Data/mime.txt',
+      'from' => 'joe@test.com'
+    }
     result = @mg_obj.send_message("testdomain.com", data)
 
     result.to_h!
@@ -46,6 +49,25 @@ describe 'The method send_message()' do
     expect(result.body).to include("message")
     expect(result.body).to include("id")
   end
+
+  context 'when domain is missing' do
+    it 'shows failure message' do
+      expect(@mg_obj).to receive(:fail)
+      @mg_obj.send_message(nil, {})
+    end
+  end
+
+  context 'when to is missing' do
+    it 'shows failure message' do
+    data = {
+      'to' => '',
+      'message' => 'Sample Data/mime.txt',
+      'from' => 'joe@test.com'
+    }
+    expect(@mg_obj).to receive(:fail)
+    @mg_obj.send_message("testdomain.com", data)
+    end
+  end
 end
 
 describe 'The method post()' do
@@ -65,6 +87,25 @@ describe 'The method post()' do
     expect(result.body).to include("message")
     expect(result.body).to include("id")
   end
+
+  context 'when Unknown API error is raised' do
+    before do
+      allow(Mailgun::Response).to receive(:new).and_raise(StandardError, "message")
+      allow(JSON).to receive(:parse).and_raise('Unknown')
+    end
+
+    it 'adds Unknown API error to message' do
+      data = {'from' => 'joe@test.com',
+                    'to' => 'bob@example.com',
+                    'subject' => 'Test',
+                    'text' => 'Test Data'}
+      @mg_obj.post("#{@domain}/messages", data)
+    rescue Mailgun::CommunicationError => err
+      expect(err.message).to eq('message: Unknown API error')
+    else
+      fail
+    end
+  end
 end
 
 describe 'The method put()' do

data/spec/unit/messages/batch_message_spec.rb

@@ -72,61 +72,76 @@ describe 'The method add_recipient' do
     @address_3   = 'sam@example.com'
     @variables_3 = {'first' => 'Sam', 'last' => 'Doe', 'tracking' => 'GHI123'}
   end
-
-  it 'adds 1,000 recipients to the message body and validates counter is incremented then reset' do
-    recipient_type = :to
-    1000.times do
-      @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
+  context 'when from is present' do
+    before(:each) do
+      @mb_obj.from('example@email.com')
     end
 
-    expect(@mb_obj.counters[:recipients][recipient_type]).to eq(1000)
-    
-    @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
-    
-    expect(@mb_obj.counters[:recipients][recipient_type]).to eq(1)
-  end
+    it 'adds 1,000 recipients to the message body and validates counter is incremented then reset' do
+      recipient_type = :to
+      1000.times do
+        @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
+      end
 
-  it 'adds recipients to the message, calls finalize, and cleans up' do
-    recipient_type = :to
-    1000.times do
+      expect(@mb_obj.counters[:recipients][recipient_type]).to eq(1000)
+      
       @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
+      
+      expect(@mb_obj.counters[:recipients][recipient_type]).to eq(1)
     end
 
-    expect(@mb_obj.counters[:recipients][recipient_type]).to eq(1000)
-    @mb_obj.finalize
+    it 'adds recipients to the message, calls finalize, and cleans up' do
+      recipient_type = :to
+      1000.times do
+        @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
+      end
 
-    expect(@mb_obj.recipient_variables).to eq({})
-    expect(@mb_obj.message['recipient-variables'].length).to eq(0)
-    expect(@mb_obj.message[:to].length).to eq(0)
-    expect(@mb_obj.counters[:recipients][recipient_type]).to eq(0)
-  end
+      expect(@mb_obj.counters[:recipients][recipient_type]).to eq(1000)
+      @mb_obj.finalize
 
-  it 'adds 5,005 recipients to the message body and validates we receive message_ids back' do
-    recipient_type = :to
-    5005.times do
-      @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
+      expect(@mb_obj.recipient_variables).to eq({})
+      expect(@mb_obj.message['recipient-variables'].length).to eq(0)
+      expect(@mb_obj.message[:to].length).to eq(0)
+      expect(@mb_obj.counters[:recipients][recipient_type]).to eq(0)
     end
-    @mb_obj.finalize
 
-    expect(@mb_obj.message_ids.length).to eq(6)
-  end
+    it 'adds 5,005 recipients to the message body and validates we receive message_ids back' do
+      recipient_type = :to
+      5005.times do
+        @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
+      end
+      @mb_obj.finalize
 
-  it 'sets recipient-variables, for batch expansion' do
-    recipient_type = :to
-    @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
+      expect(@mb_obj.message_ids.length).to eq(6)
+    end
 
-    expect(@mb_obj.recipient_variables[@address_1]).to eq(@variables_1)
+    it 'sets recipient-variables, for batch expansion' do
+      recipient_type = :to
+      @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
+
+      expect(@mb_obj.recipient_variables[@address_1]).to eq(@variables_1)
+    end
+
+    it 'sets multiple recipient-variables, for batch expansion' do
+      recipient_type = :to
+      @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
+      @mb_obj.add_recipient(recipient_type, @address_2, @variables_2)
+      @mb_obj.add_recipient(recipient_type, @address_3, @variables_3)
+      
+      expect(@mb_obj.recipient_variables[@address_1]).to eq(@variables_1)
+      expect(@mb_obj.recipient_variables[@address_2]).to eq(@variables_2)
+      expect(@mb_obj.recipient_variables[@address_3]).to eq(@variables_3)
+    end
   end
 
-  it 'sets multiple recipient-variables, for batch expansion' do
-    recipient_type = :to
-    @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
-    @mb_obj.add_recipient(recipient_type, @address_2, @variables_2)
-    @mb_obj.add_recipient(recipient_type, @address_3, @variables_3)
-    
-    expect(@mb_obj.recipient_variables[@address_1]).to eq(@variables_1)
-    expect(@mb_obj.recipient_variables[@address_2]).to eq(@variables_2)
-    expect(@mb_obj.recipient_variables[@address_3]).to eq(@variables_3)
+  context 'when from is empty' do
+    it 'shows error message' do
+      recipient_type = :to
+      @mb_obj.add_recipient(recipient_type, @address_1, @variables_1)
+      @mb_obj.add_recipient(recipient_type, @address_2, @variables_2)
+      expect(@mb_client).to receive(:fail)
+      @mb_obj.finalize
+    end
   end
 
 end

data/spec/unit/messages/message_builder_spec.rb

@@ -313,7 +313,7 @@ describe 'The method set_test_mode' do
   it 'warns of set_test_mode deprecation' do
     @mb_obj = Mailgun::MessageBuilder.new
     expect(@mb_obj).to receive :warn
-    @mb_obj.set_test_mode 'warn on set_test_mode'
+    @mb_obj.set_test_mode 'Yes'
   end
 end
 
@@ -355,7 +355,7 @@ describe 'The method set_dkim' do
   it 'warns of set_dkim deprecation' do
     @mb_obj = Mailgun::MessageBuilder.new
     expect(@mb_obj).to receive :warn
-    @mb_obj.set_dkim 'warn on set_dkim'
+    @mb_obj.set_dkim 'Yes'
   end
 end
 
@@ -449,7 +449,7 @@ describe 'The method set_open_tracking' do
   it 'warns of set_open_tracking deprecation' do
     @mb_obj = Mailgun::MessageBuilder.new
     expect(@mb_obj).to receive :warn
-    @mb_obj.set_open_tracking 'warn on set_open_tracking'
+    @mb_obj.set_open_tracking 'Yes'
   end
 end
 
@@ -461,6 +461,7 @@ describe 'The method track_opens' do
     @mb_obj.track_opens('Yes')
 
     expect(@mb_obj.message["o:tracking-opens"]).to eq("yes")
+    expect(@mb_obj.message["o:tracking"]).to eq(["yes"])
 
     @mb_obj.track_opens('No')
 
@@ -480,7 +481,7 @@ describe 'The method set_click_tracking' do
   it 'warns of set_click_tracking deprecation' do
     @mb_obj = Mailgun::MessageBuilder.new
     expect(@mb_obj).to receive :warn
-    @mb_obj.set_click_tracking 'warn on set_click_tracking'
+    @mb_obj.set_click_tracking 'Yes'
   end
 end
 
@@ -492,6 +493,7 @@ describe 'The method track_clicks' do
     @mb_obj.track_clicks('Yes')
 
     expect(@mb_obj.message["o:tracking-clicks"]).to eq("yes")
+    expect(@mb_obj.message["o:tracking"]).to eq(["yes"])
 
     @mb_obj.track_clicks('No')
 
@@ -509,6 +511,13 @@ describe 'The method track_clicks' do
 
     expect(@mb_obj.message["o:tracking-clicks"]).to eq("html")
   end
+
+  context 'when unexpected value is provided' do
+    it 'warns about prefered values' do
+      expect(@mb_obj).to receive :warn
+      @mb_obj.track_clicks('random')
+    end
+  end
 end
 
 describe 'The method set_delivery_time' do
@@ -621,3 +630,103 @@ describe 'The method message_id' do
     expect(@mb_obj.message.has_key?('h:Message-Id')).to eq(false)
   end
 end
+
+describe 'The method template' do
+  before(:each) do
+    @mb_obj = Mailgun::MessageBuilder.new
+  end
+  context 'when template name is passed' do
+    it 'sets `template` to the message' do
+      template_name = 'template.name'
+      @mb_obj.template(template_name)
+
+      expect(@mb_obj.message['template']).to eq(template_name)
+    end
+  end
+
+  context 'when multiple values are passed' do
+    it 'sets the last value as message template' do
+      template_name_1 = 'template.name_1'
+      template_name_2 = 'template.name_2'
+
+      @mb_obj.template(template_name_1)
+      @mb_obj.template(template_name_2)
+
+      expect(@mb_obj.message['template']).to eq(template_name_2)
+    end
+  end
+
+  context 'when template name is not passed' do
+    it 'it deletes `template` key from the message' do
+      @mb_obj.template('template.name')
+
+      expect(@mb_obj.message.has_key?('template')).to eq(true)
+
+      @mb_obj.template
+
+      expect(@mb_obj.message.has_key?('template')).to eq(false)
+    end
+  end
+end
+
+describe 'The method template_version' do
+  before(:each) do
+    @mb_obj = Mailgun::MessageBuilder.new
+  end
+  context 'when template version is passed' do
+    it 'adds `t:version` key value to the message' do
+      version = 'version_1'
+      @mb_obj.template_version(version)
+
+      expect(@mb_obj.message['t:version']).to eq(version)
+    end
+  end
+
+  context 'when multiple values are passed' do
+    it 'adds the last value as `t:version` key value to the message' do
+      version_1 = 'version_1'
+      version_2 = 'version_2'
+
+      @mb_obj.template_version(version_1)
+      @mb_obj.template_version(version_2)
+
+      expect(@mb_obj.message['t:version']).to eq(version_2)
+    end
+  end
+
+  context 'when version is not passed' do
+    it 'it deletes `t:version` key from the message' do
+      @mb_obj.template_version('version')
+
+      expect(@mb_obj.message.has_key?('t:version')).to eq(true)
+
+      @mb_obj.template_version
+
+      expect(@mb_obj.message.has_key?('t:version')).to eq(false)
+    end
+  end
+end
+
+describe 'The method template_text' do
+  before(:each) do
+    @mb_obj = Mailgun::MessageBuilder.new
+  end
+
+  it 'enables/disables rendering in the text part of the message in case of template sending' do
+    @mb_obj.template_text('Yes')
+
+    expect(@mb_obj.message["t:text"]).to eq("yes")
+
+    @mb_obj.template_text('No')
+
+    expect(@mb_obj.message["t:text"]).to eq("no")
+
+    @mb_obj.template_text(true)
+
+    expect(@mb_obj.message["t:text"]).to eq("yes")
+
+    @mb_obj.template_text(false)
+
+    expect(@mb_obj.message["t:text"]).to eq("no")
+  end
+end

data/spec/unit/railgun/mailer_spec.rb

@@ -31,6 +31,18 @@ class UnitTestMailer < ActionMailer::Base
     end
   end
 
+  def message_with_template(address, subject, template_name)
+    mail(to: address, subject: subject, template: template_name) do |format|
+      format.text { render plain: "Test!" }
+    end
+  end
+
+  def message_with_domain(address, subject, domain)
+    mail(to: address, subject: subject, domain: domain) do |format|
+      format.text { render plain: "Test!" }
+    end
+  end
+
 end
 
 describe 'Railgun::Mailer' do
@@ -45,6 +57,31 @@ describe 'Railgun::Mailer' do
     expect(@mailer_obj.mailgun_client).to be_a(Mailgun::Client)
   end
 
+  context 'when config does not have api_key or domain' do
+    it 'raises configuration error' do
+      config = {
+        api_key:  {}
+      }
+
+    expect { Railgun::Mailer.new(config) }.to raise_error(Railgun::ConfigurationError)
+    end
+  end
+
+  context 'when fake_message_send is present in config' do
+    it 'enables test mode' do
+      config = {
+        api_key:  {},
+        domain:   {},
+        fake_message_send: true
+      }
+      client_double = double(Mailgun::Client)
+      allow(Mailgun::Client).to receive(:new).and_return(client_double)
+      expect(client_double).to receive(:enable_test_mode!)
+
+      Railgun::Mailer.new(config)
+    end
+  end
+
   it 'properly creates a message body' do
     message = UnitTestMailer.plain_message('test@example.org', 'Test!', {})
     body = Railgun.transform_for_mailgun(message)
@@ -157,6 +194,43 @@ describe 'Railgun::Mailer' do
     expect(body['h:x-source']).to eq('unit tests')
   end
 
+  context 'when mailgun_variables are present' do
+    it 'accepts valid JSON and stores it as message[param].' do
+      message = UnitTestMailer.plain_message('test@example.org', '', {}).tap do |message|
+        message.mailgun_variables = {
+          'my-data' => '{"key":"value"}'
+        }
+      end
+      body = Railgun.transform_for_mailgun(message)
+      expect(body["v:my-data"]).to be_kind_of(String)
+      expect(body["v:my-data"].to_s).to eq('{"key":"value"}')
+    end
+
+    it 'accepts a hash and appends as data to the message.' do
+      message = UnitTestMailer.plain_message('test@example.org', '', {}).tap do |message|
+        message.mailgun_variables = {
+          'my-data' => {'key' => 'value'}
+        }
+      end
+      body = Railgun.transform_for_mailgun(message)
+
+      expect(body["v:my-data"]).to be_kind_of(String)
+      expect(body["v:my-data"].to_s).to eq('{"key":"value"}')
+    end
+
+    it 'accepts string values' do
+      message = UnitTestMailer.plain_message('test@example.org', '', {}).tap do |message|
+        message.mailgun_variables = {
+          'my-data' => 'String Value.'
+        }
+      end
+      body = Railgun.transform_for_mailgun(message)
+
+      expect(body["v:my-data"]).to be_kind_of(String)
+      expect(body["v:my-data"].to_s).to eq('String Value.')
+    end
+  end
+
   it 'properly adds attachments' do
     message = UnitTestMailer.message_with_attachment('test@example.org', '')
     body = Railgun.transform_for_mailgun(message)
@@ -239,4 +313,76 @@ describe 'Railgun::Mailer' do
     expect(body['h:x-neat-header']).to include('bar')
     expect(body['h:x-neat-header']).to include('zoop')
   end
+
+  context 'when message with template' do
+    it 'adds template header to message from mailer params' do
+      template_name = 'template.name'
+      message = UnitTestMailer.message_with_template('test@example.org', '', template_name)
+
+      body = Railgun.transform_for_mailgun(message)
+
+      expect(body).to include('template')
+      expect(body['template']).to eq(template_name)
+    end
+
+    context 'when mailgun_template_variables are assigned' do
+      it 'adds template variables to message body' do
+        message = UnitTestMailer.message_with_template('test@example.org', '', 'template.name')
+        version = 'version_1'
+        message.mailgun_template_variables ||= {
+          'version' => version,
+          'text' => 'yes'
+        }
+
+        body = Railgun.transform_for_mailgun(message)
+
+        expect(body).to include('t:version')
+        expect(body['t:version']).to eq('version_1')
+        expect(body).to include('t:text')
+        expect(body['t:text']).to eq('yes')
+      end
+    end
+  end
+
+  describe 'deliver!' do
+    let(:config) do
+      {
+        api_key: 'api_key',
+        domain: 'domain'
+      }
+    end
+    let(:mail) { UnitTestMailer.plain_message('test@example.org', '', {}) }
+    let(:response) do
+      response = Struct.new(:code, :id)
+      response.new(200, rand(50..100))
+    end
+
+    it 'initiates client message send' do
+      result = { from: 'test@example.org' }
+      allow(Railgun).to receive(:transform_for_mailgun).and_return(result)
+
+      expect_any_instance_of(Mailgun::Client).to receive(:send_message)
+        .with(config[:domain], result)
+        .and_return(response)
+      Railgun::Mailer.new(config).deliver!(mail)
+    end
+
+    it 'returns response' do
+      expect_any_instance_of(Mailgun::Client).to receive(:send_message).and_return(response)
+      expect(Railgun::Mailer.new(config).deliver!(mail)).to eq(response)
+    end
+
+    context 'when domain is provided in arguments' do
+      let(:new_domain) { 'new_domain' }
+      let(:mail) { UnitTestMailer.message_with_domain('test@example.org', '', new_domain) }
+
+      it 'uses provided domain' do
+        result = { from: 'test@example.org' }
+        allow(Railgun).to receive(:transform_for_mailgun).and_return(result)
+        expect_any_instance_of(Mailgun::Client).to receive(:send_message)
+          .with(new_domain, result).and_return(response)
+        Railgun::Mailer.new(config).deliver!(mail)
+      end
+    end
+  end
 end

data/vcr_cassettes/mailer_invalid_domain.yml

@@ -0,0 +1,109 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://api.mailgun.net/v3/not-our-doma.in/messages
+    body:
+      encoding: US-ASCII
+      string: from[]=sally%40not-our-doma.in&subject[]=subject&html[]=%3Cp%3ETest%21%3C%2Fp%3E&text[]=Test%21&to[]=bob%40DOMAIN.TEST&h%3Acontent-type=multipart%2Falternative%3B+boundary%3D%22--%3D%3D_mimepart_6098fb5a12edf_78633ff4e00521889696a%22%3B+charset%3DUTF-8
+    headers:
+      Accept:
+      - "*/*"
+      User-Agent:
+      - rest-client/2.1.0 (darwin18.7.0 x86_64) ruby/2.2.2p95
+      Content-Length:
+      - '262'
+      Content-Type:
+      - application/x-www-form-urlencoded
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Host:
+      - api.mailgun.net
+      Authorization:
+      - Basic YXBpOmQ5MTViNWNkYjlhNTgzNjg1ZDhmM2ZiMWJlYzBmMjBmLTA3YmM3YjA1LWZhNDgxNmEx
+  response:
+    status:
+      code: 401
+      message: UNAUTHORIZED
+    headers:
+      Access-Control-Allow-Headers:
+      - Content-Type, x-requested-with, Authorization
+      Access-Control-Allow-Methods:
+      - GET, POST, PUT, DELETE, OPTIONS
+      Access-Control-Allow-Origin:
+      - "*"
+      Access-Control-Max-Age:
+      - '600'
+      Cache-Control:
+      - no-store
+      Content-Type:
+      - text/html; charset=utf-8
+      Date:
+      - Mon, 10 May 2021 09:22:34 GMT
+      Server:
+      - nginx
+      Www-Authenticate:
+      - Basic realm="MG API"
+      Content-Length:
+      - '9'
+      Connection:
+      - keep-alive
+    body:
+      encoding: UTF-8
+      string: Forbidden
+    http_version:
+  recorded_at: Mon, 10 May 2021 09:22:34 GMT
+- request:
+    method: post
+    uri: https://api.mailgun.net/v3/not-our-doma.in/messages
+    body:
+      encoding: US-ASCII
+      string: from[]=sally%40not-our-doma.in&subject[]=subject&html[]=%3Cp%3ETest%21%3C%2Fp%3E&text[]=Test%21&to[]=bob%40DOMAIN.TEST&h%3Acontent-type=multipart%2Falternative%3B+boundary%3D%22--%3D%3D_mimepart_6098fb5a12edf_78633ff4e00521889696a%22%3B+charset%3DUTF-8
+    headers:
+      Accept:
+      - "*/*"
+      User-Agent:
+      - rest-client/2.1.0 (darwin18.7.0 x86_64) ruby/2.2.2p95
+      Content-Length:
+      - '262'
+      Content-Type:
+      - application/x-www-form-urlencoded
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Host:
+      - api.mailgun.net
+      Authorization:
+      - Basic YXBpOmQ5MTViNWNkYjlhNTgzNjg1ZDhmM2ZiMWJlYzBmMjBmLTA3YmM3YjA1LWZhNDgxNmEx
+  response:
+    status:
+      code: 401
+      message: UNAUTHORIZED
+    headers:
+      Access-Control-Allow-Headers:
+      - Content-Type, x-requested-with, Authorization
+      Access-Control-Allow-Methods:
+      - GET, POST, PUT, DELETE, OPTIONS
+      Access-Control-Allow-Origin:
+      - "*"
+      Access-Control-Max-Age:
+      - '600'
+      Cache-Control:
+      - no-store
+      Content-Type:
+      - text/html; charset=utf-8
+      Date:
+      - Mon, 10 May 2021 09:22:40 GMT
+      Server:
+      - nginx
+      Www-Authenticate:
+      - Basic realm="MG API"
+      Content-Length:
+      - '9'
+      Connection:
+      - keep-alive
+    body:
+      encoding: UTF-8
+      string: Forbidden
+    http_version:
+  recorded_at: Mon, 10 May 2021 09:22:40 GMT
+recorded_with: VCR 3.0.3

data/vcr_cassettes/message_deliver.yml

@@ -0,0 +1,149 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://api.mailgun.net/v3/DOMAIN.TEST/messages
+    body:
+      encoding: US-ASCII
+      string: from[]=bob%40DOMAIN.TEST&subject[]=subject&html[]=%3Cp%3ETest%21%3C%2Fp%3E&text[]=Test%21&to[]=bob%40DOMAIN.TEST&h%3Acontent-type=multipart%2Falternative%3B+boundary%3D%22--%3D%3D_mimepart_6098f913d64ca_62833fd4d74521802775%22%3B+charset%3DUTF-8
+    headers:
+      Accept:
+      - "*/*"
+      User-Agent:
+      - rest-client/2.1.0 (darwin18.7.0 x86_64) ruby/2.2.2p95
+      Content-Length:
+      - '261'
+      Content-Type:
+      - application/x-www-form-urlencoded
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Host:
+      - api.mailgun.net
+      Authorization:
+      - Basic YXBpOmQ5MTViNWNkYjlhNTgzNjg1ZDhmM2ZiMWJlYzBmMjBmLTA3YmM3YjA1LWZhNDgxNmEx
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Headers:
+      - Content-Type, x-requested-with, Authorization
+      Access-Control-Allow-Methods:
+      - GET, POST, PUT, DELETE, OPTIONS
+      Access-Control-Allow-Origin:
+      - "*"
+      Access-Control-Max-Age:
+      - '600'
+      Cache-Control:
+      - no-store
+      Content-Disposition:
+      - inline
+      Content-Type:
+      - application/json
+      Date:
+      - Mon, 10 May 2021 09:12:52 GMT
+      Server:
+      - nginx
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Ratelimit-Limit:
+      - '2000000'
+      X-Ratelimit-Remaining:
+      - '1999999'
+      X-Ratelimit-Reset:
+      - '1620637982656'
+      X-Recipient-Limit:
+      - '1000000'
+      X-Recipient-Remaining:
+      - '999999'
+      X-Recipient-Reset:
+      - '1620637982657'
+      Content-Length:
+      - '136'
+      Connection:
+      - keep-alive
+    body:
+      encoding: UTF-8
+      string: |-
+        {
+          "id": "<20210510091252.1.D6347B73DA43962E@DOMAIN.TEST>",
+          "message": "Queued. Thank you."
+        }
+    http_version:
+  recorded_at: Mon, 10 May 2021 09:12:52 GMT
+- request:
+    method: post
+    uri: https://api.mailgun.net/v3/DOMAIN.TEST/messages
+    body:
+      encoding: US-ASCII
+      string: from[]=bob%40DOMAIN.TEST&subject[]=subject&html[]=%3Cp%3ETest%21%3C%2Fp%3E&text[]=Test%21&to[]=bob%40DOMAIN.TEST&h%3Amessage-id=%3C20210510091252.1.D6347B73DA43962E%40DOMAIN.TEST%3E&h%3Acontent-type=multipart%2Falternative%3B+boundary%3D%22--%3D%3D_mimepart_6098f913d64ca_62833fd4d74521802775%22%3B+charset%3DUTF-8
+    headers:
+      Accept:
+      - "*/*"
+      User-Agent:
+      - rest-client/2.1.0 (darwin18.7.0 x86_64) ruby/2.2.2p95
+      Content-Length:
+      - '370'
+      Content-Type:
+      - application/x-www-form-urlencoded
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Host:
+      - api.mailgun.net
+      Authorization:
+      - Basic YXBpOmQ5MTViNWNkYjlhNTgzNjg1ZDhmM2ZiMWJlYzBmMjBmLTA3YmM3YjA1LWZhNDgxNmEx
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Headers:
+      - Content-Type, x-requested-with, Authorization
+      Access-Control-Allow-Methods:
+      - GET, POST, PUT, DELETE, OPTIONS
+      Access-Control-Allow-Origin:
+      - "*"
+      Access-Control-Max-Age:
+      - '600'
+      Cache-Control:
+      - no-store
+      Content-Disposition:
+      - inline
+      Content-Type:
+      - application/json
+      Date:
+      - Mon, 10 May 2021 09:12:56 GMT
+      Server:
+      - nginx
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Ratelimit-Limit:
+      - '2000000'
+      X-Ratelimit-Remaining:
+      - '1999998'
+      X-Ratelimit-Reset:
+      - '1620637982656'
+      X-Recipient-Limit:
+      - '1000000'
+      X-Recipient-Remaining:
+      - '999998'
+      X-Recipient-Reset:
+      - '1620637982657'
+      Content-Length:
+      - '136'
+      Connection:
+      - keep-alive
+    body:
+      encoding: UTF-8
+      string: |-
+        {
+          "id": "<20210510091252.1.D6347B73DA43962E@DOMAIN.TEST>",
+          "message": "Queued. Thank you."
+        }
+    http_version:
+  recorded_at: Mon, 10 May 2021 09:12:56 GMT
+recorded_with: VCR 3.0.3

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: mailgun-ruby
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.2.6
 platform: ruby
 authors:
 - Mailgun
 - Travis Swientek
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-04-05 00:00:00.000000000 Z
+date: 2022-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -192,6 +192,7 @@ files:
 - spec/integration/events_spec.rb
 - spec/integration/list_members_spec.rb
 - spec/integration/list_spec.rb
+- spec/integration/mailer_spec.rb
 - spec/integration/mailgun_spec.rb
 - spec/integration/messages/sample_data/mime.txt
 - spec/integration/routes_spec.rb
@@ -220,8 +221,10 @@ files:
 - vcr_cassettes/events.yml
 - vcr_cassettes/exceptions.yml
 - vcr_cassettes/list_members.yml
+- vcr_cassettes/mailer_invalid_domain.yml
 - vcr_cassettes/mailing_list.todo.yml
 - vcr_cassettes/mailing_list.yml
+- vcr_cassettes/message_deliver.yml
 - vcr_cassettes/routes.yml
 - vcr_cassettes/send_message.yml
 - vcr_cassettes/stats.yml
@@ -232,7 +235,7 @@ homepage: http://www.mailgun.com
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -247,8 +250,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.9
-signing_key:
+rubygems_version: 3.0.3
+signing_key: 
 specification_version: 4
 summary: Mailgun's Official Ruby SDK
 test_files:
@@ -260,6 +263,7 @@ test_files:
 - spec/integration/events_spec.rb
 - spec/integration/list_members_spec.rb
 - spec/integration/list_spec.rb
+- spec/integration/mailer_spec.rb
 - spec/integration/mailgun_spec.rb
 - spec/integration/messages/sample_data/mime.txt
 - spec/integration/routes_spec.rb