mailgun-ruby 1.2.10 → 1.2.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 846d1a1383139f176ad8508d5e465ddfa90617e1b7cc138de178344f11b97365
-  data.tar.gz: b64fa898adc500f8c5ba7a21af1e02ec92eac3996905ce4a7851cebbe08d2bcd
+  metadata.gz: cf800982a326bb3cd2417126fc5a9de3de7ca0c4cf2c9387541244f3ee6d362d
+  data.tar.gz: f3515a9207e04c66d69afcaee25ee7aa746ee58f58ea4a48d2511363c1bc6005
 SHA512:
-  metadata.gz: bd26107fe4db4917f5e78141ed9fe6ca5d659ae1aea7959316bc12e5c18b130a9b5397c9aaf0c31001ba6bd4a2d490c1ec04f5c592c2653c0fa19b5342ff0996
-  data.tar.gz: 47b6b488bdae399de35f1418cd92015f0764f884b8a39d2c45c002b4f6bb1db367bd4a24dd6e985b8392f5ef442dc789e17fdd3ac270ad798e44984ddcf3777d
+  metadata.gz: a65a2e514f1865825d8c4d7673fd2060e4dd3902402c0500e9dcf213052fff6fb7222379bd155430f30d6abf0300361228ec3cb1db53d2998b2718fb27ffb46a
+  data.tar.gz: 2f3988bcd4ecd490305543d3719b37f1531f796558879604263810d02d0bca068647634d8d9141f90711d1d9c4f3038ff29b385bdbe0df0537ac80bc451a05e1

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [1.2.12] - 2023-10-22
+
+### Added
+
+- Templates CRUD support (https://github.com/mailgun/mailgun-ruby/pull/300).
+
+### Fixed
+
+- transform_for_mailgun block iteration issue (https://github.com/mailgun/mailgun-ruby/pull/298).
+- Typos in several files (https://github.com/mailgun/mailgun-ruby/pull/297).

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.2.10'
+gem 'mailgun-ruby', '~>1.2.12'
 ```
 
 Usage
@@ -81,6 +81,7 @@ and replace `api-myapikey` and `mydomain.com` with your secret API key and domai
     api_key: 'api-myapikey',
     domain: 'mydomain.com',
     # api_host: 'api.eu.mailgun.net'  # Uncomment this line for EU region domains
+    # timeout: 20 # Default depends on rest-client, whose default is 60s. Added in 1.2.3.
   }
 ```
 
@@ -96,7 +97,7 @@ class UserMailer < ApplicationMailer
       }
     end
   end
-end   
+end
 ```
 
 To get the Mailgun `message_id` after ActionMailer has successfully delivered the email:
@@ -182,7 +183,7 @@ pages. Or the [Snippets](docs/Snippets.md) file.
 This SDK includes the following components:
 - [Messages](docs/Messages.md)
 - [Message Builder](docs/MessageBuilder.md)
-- [Batch Message](docs/MessageBuilder.md)
+- [Batch Message](docs/MessageBuilder.md#usage---batch-message)
 - [Opt-In Handler](docs/OptInHandler.md)
 - [Domains](docs/Domains.md)
 - [Webhooks](docs/Webhooks.md)

data/lib/mailgun/client.rb

@@ -222,11 +222,11 @@ module Mailgun
       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',
+        '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 containg at least 1 `from` sender',
+        'Missing a `from` sender, message should contain at least 1 `from` sender',
         working_domain
       ) if message.fetch('from', []).empty? && message.fetch(:from, []).empty?
     end

data/lib/mailgun/domains/domains.rb

@@ -56,7 +56,7 @@ module Mailgun
     #     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.
+    #       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

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)

data/lib/mailgun/messages/message_builder.rb

@@ -125,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.
@@ -383,7 +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'
+      warn 'WARN: for bool type actions next values are preferred: true yes yep | false no nope | htmlonly'
       value
     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/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.2.10'
+  VERSION = '1.2.12'
 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.rb

@@ -15,6 +15,7 @@ require 'mailgun/events/events'
 require 'mailgun/exceptions/exceptions'
 require 'mailgun/domains/domains'
 require 'mailgun/webhooks/webhooks'
+require 'mailgun/templates/templates'
 
 # Module for interacting with the sweet Mailgun API.
 #

data/lib/railgun/mailer.rb

@@ -145,7 +145,7 @@ module Railgun
 
     # reject blank values
     message.delete_if do |k, v|
-      return true if v.nil?
+      next 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)

data/mailgun.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
 
   spec.name             = 'mailgun-ruby'
   spec.version          = Mailgun::VERSION
-  spec.homepage         = 'http://www.mailgun.com'
+  spec.homepage         = 'https://www.mailgun.com/'
   spec.platform         = Gem::Platform::RUBY
   spec.license          = 'Apache-2.0'
 
@@ -17,6 +17,9 @@ Gem::Specification.new do |spec|
   spec.authors          = ['Mailgun', 'Travis Swientek']
   spec.email            = 'support@mailgunhq.com'
 
+  spec.metadata['documentation_uri'] = 'https://documentation.mailgun.com/'
+  spec.metadata['source_code_uri'] = 'https://github.com/mailgun/mailgun-ruby'
+
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})

data/spec/integration/email_validation_spec.rb

@@ -15,6 +15,13 @@ describe 'For the email validation endpoint', order: :defined, vcr: vcr_opts do
     @all_addrs = @valid + @invalid
   end
 
+  it 'returns parsed and unparsable lists' do
+    res = @mg_obj.parse(@all_addrs)
+
+    expect(res["parsed"]).to eq(@valid)
+    expect(res["unparsable"]).to eq(@invalid)
+  end
+
   it 'validates alice@mailgun.net with info' do
     res = @mg_obj.validate("alice@mailgun.net")
 

data/spec/integration/mailgun_spec.rb

@@ -192,5 +192,21 @@ Testing some Mailgun awesomness!'
     expect(result.body).to include("message")
     expect(result.body).to include("id")
   end
+  
+  it 'receives success response code' do
+    @mg_obj.enable_test_mode!
+
+    expect(@mg_obj.test_mode?).to eq(true)
+
+    data = { :from => "joe@#{@domain}",
+             :to => "bob@#{@domain}",
+             :subject => "Test",
+             :text => "Test Data" }
+
+    result = @mg_obj.send_message(@domain, data)
+    result.to_h!
+    
+    expect(result.success?).to be(true)
+  end
 end
 

data/spec/integration/templates_spec.rb

@@ -0,0 +1,135 @@
+require 'spec_helper'
+require 'mailgun'
+
+vcr_opts = { :cassette_name => "templates" }
+
+describe 'For the templates endpoints', vcr: vcr_opts do
+  let(:template_name) { 'test.template' }
+  let(:domain) { "integration-test.domain.invalid" }
+  let(:tag) { 'v2' }
+
+  before(:all) do
+    @mg_client = Mailgun::Client.new(APIKEY, APIHOST, APIVERSION, SSL)
+    @mg_obj = Mailgun::Templates.new(@mg_client)
+  end
+
+  describe '#create' do
+    it 'creates the template' do
+      result = @mg_obj.create(
+        domain,
+        {
+          name: template_name,
+          description: 'Test',
+          template: '{{fname}} {{lname}}',
+            comment: 'test comment',
+            headers: '{"Subject": "{{subject}}"}',
+            tag: 'V1'
+        }
+      )
+
+      expect(result['template']["name"]).to eq('test.template')
+      expect(result['template']["description"]).to eq("Test")
+    end
+  end
+
+  describe '#info' do
+    it 'gets the templates info' do
+      result = @mg_obj.info(domain, 'test.template')
+
+      expect(result).to include("template")
+      expect(result["template"]["name"]).to eq(template_name)
+    end
+  end
+
+  describe '#update' do
+    it 'updates the template' do
+      result = @mg_obj.update(domain, template_name, { description: 'Updated Description' })
+
+      expect(result['message']).to eq('template has been updated')
+    end
+  end
+
+  describe '#list' do
+    it 'returns a list of templates' do
+      result = @mg_obj.list(domain)
+
+      expect(result.first).to have_key('name')
+      expect(result.first).to have_key('description')
+    end
+  end
+
+  describe '#delete' do
+    it 'deletes a template' do
+      result = @mg_obj.delete(domain, template_name)
+
+      expect(result).to be_truthy
+    end
+  end
+
+  describe '#remove_all' do
+    it 'deletes all templates from domain' do
+      result = @mg_obj.remove_all(domain)
+
+      expect(result).to be_truthy
+    end
+  end
+
+  describe '#create_version' do
+    it 'creates the version for the template' do
+      result = @mg_obj.create_version(
+        domain,
+        template_name,
+        {
+          template: '{{fname}} {{lname}}',
+          comment: 'test comment',
+          headers: '{"Subject": "{{subject}}"}',
+          tag: tag,
+          active: 'yes'
+        }
+      )
+
+      expect(result['template']["version"]['tag']).to eq(tag)
+    end
+  end
+
+  describe '#info_version' do
+    it "gets the template's version info" do
+      result = @mg_obj.info_version(domain, template_name, tag)
+
+      expect(result["template"]["version"]['tag']).to eq(tag)
+    end
+  end
+
+  describe '#update_version' do
+    it 'updates the template' do
+      result = @mg_obj.update_version(
+        domain,
+        template_name,
+        tag,
+        {
+          template: '{{fname}} {{lname}}',
+          comment: 'test comment 2',
+          headers: '{"Subject": "{{subject}}"}'
+        }
+      )
+
+      expect(result['message']).to eq('version has been updated')
+    end
+  end
+
+  describe '#template_versions_list' do
+    it "returns template's versions" do
+      result = @mg_obj.template_versions_list(domain, template_name)
+
+      expect(result["template"]["versions"].first).to include('tag')
+    end
+  end
+
+  describe '#delete_version' do
+    it "deletes template's version" do
+      result = @mg_obj.delete_version(domain, template_name, tag)
+
+      expect(result).to be_truthy
+    end
+  end
+end

data/spec/unit/connection/test_client.rb

@@ -83,11 +83,11 @@ module Mailgun
       message = data.respond_to?(:message) ? data.message : data
 
       fail ParameterError.new(
-        'Missing `to` recipient, message should containg at least 1 recipient',
+        '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 containg at least 1 `from` sender',
+        'Missing a `from` sender, message should contain at least 1 `from` sender',
         working_domain
       ) if message.fetch('from', []).empty? && message.fetch(:from, []).empty?
     end

data/spec/unit/messages/message_builder_spec.rb

@@ -513,7 +513,7 @@ describe 'The method track_clicks' do
   end
 
   context 'when unexpected value is provided' do
-    it 'warns about prefered values' do
+    it 'warns about preferred values' do
       expect(@mb_obj).to receive :warn
       @mb_obj.track_clicks('random')
     end