mailgun-ruby 1.1.9 → 1.2.13

data/docs/Subaccounts.md

@@ -0,0 +1,68 @@
+Mailgun - [Subaccounts](https://help.mailgun.com/hc/en-us/articles/16380043681435-Subaccounts)
+====================
+
+Rails
+-----
+
+The library can be initialized with a Rails initializer containing similar:
+```ruby
+Mailgun.configure do |config|
+  config.api_key = 'your-secret-api-key'
+end
+```
+Or have the initializer read your environment setting if you prefer.
+
+```ruby
+  Mailgun.api_key = 'your-secret-api-key'
+```
+
+```ruby
+  mb_obj = Mailgun::Subaccounts.new
+
+  # Get subaccounts list
+  mb_obj.get_subaccounts(limit: 10, skip: 0, sort: 'ask', enabled: true)
+  => {"subaccounts"=>[{"id"=>"XYZ", "name"=>"test.subaccount1", "status"=>"open"}, {"id"=>"YYY", "name"=>"test.subaccount2", "status"=>"open"}], "total"=>2}
+
+  # Get subaccount information
+  mb_obj.info(subaccount_id)
+  => {"subaccount"=>{"id"=>"XYZ", "name"=>"test.subaccount1", "status"=>"open"}
+
+  # Add Subaccount
+  mb_obj.create(name)
+  => {"subaccount"=>{"id"=>"XYZ", "name"=>"test.subaccount1", "status"=>"open"}}
+
+  # Disable
+  mb_obj.disable(subaccount_id)
+  => {"subaccount"=>{"id"=>"XYZ", "name"=>"test.subaccount1", "status"=>"disabled"}}
+
+  # Enable
+  mb_obj.enable(subaccount_id)
+  => {"subaccount"=>{"id"=>"XYZ", "name"=>"test.subaccount1", "status"=>"open"}}
+```
+
+Primary accounts can make API calls on behalf of their subaccounts.
+```ruby
+# First, instantiate the Mailgun Client with your API key
+mg_client = Mailgun::Client.new 'your-api-key'
+mg_client.set_subaccount('SUBACCOUNT_ID')
+
+# Define your message parameters
+message_params = {  from: 'bob@SUBACCOUNT_DOMAIN',
+                    to: 'sally@example.com',
+                    subject: 'The Ruby SDK is awesome!',
+                    text: 'It is really easy to send a message!'
+                  }
+
+# Send your message through the client
+# Note: This will not actually hit the API, and will return a generic OK response.
+mg_client.send_message('SUBACCOUNT_DOMAIN', message_params)
+
+# Reset subaccount for primary usage
+mg_client.reset_subaccount
+```
+
+
+More Documentation
+------------------
+See the official [Mailgun Docs](https://documentation.mailgun.com/en/latest/subaccounts.html#subaccounts)
+for more information.

data/docs/Suppressions.md

@@ -38,6 +38,16 @@ supp_client.list_complaints
 
 ----
 
+To get the next or previous suppressions page:
+
+```ruby
+supp_client.list_bounces # returns first *limit* records + next, previous pages urls
+supp_client.next # returns next *limit* records
+supp_client.prev # returns previous *limit* records
+```
+
+----
+
 To batch-add a set of bounces:
 
 ```ruby

data/docs/railgun/EmailValidation.md

@@ -0,0 +1,34 @@
+Mailgun - Email Validation
+====================
+
+This is the Mailgun Ruby *Email Validation* 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 - Email Validation
+-----------------------
+
+```ruby
+# First, instantiate the Mailgun Address. It pulls api key for Client from Mailgun.api_key variable.
+email_validator = Mailgun::Address.new
+
+# Given an arbitrary address, validates address based off defined checks.
+# Response Example:
+# {
+#     "address": "existingemail@realdomain.com",
+#     "is_disposable_address": false,
+#     "is_role_address": false,
+#     "reason": [],
+#     "result": "deliverable",
+#     "risk": "low"
+# }
+email_validator.validate('email@example.com')
+
+
+```
+
+More Documentation
+------------------
+See the official [Mailgun Email Validation Docs](https://documentation.mailgun.com/en/latest/api-email-validation.html)
+for more information

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

@@ -9,18 +9,26 @@ module Mailgun
   #
   # See the Github documentation for full examples.
   class Client
+    SUBACCOUNT_HEADER = 'X-Mailgun-On-Behalf-Of'.freeze
 
     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 +46,21 @@ module Mailgun
       @test_mode = false
     end
 
+    # Change API key
+    def set_api_key(api_key)
+      @http_client.options[:password] = api_key
+    end
+
+    # Add subaccount id to headers
+    def set_subaccount(subaccount_id)
+      @http_client.options[:headers] = { SUBACCOUNT_HEADER => subaccount_id }
+    end
+
+    # Reset subaccount for primary usage
+    def reset_subaccount
+      @http_client.options[:headers].delete(SUBACCOUNT_HEADER)
+    end
+
     # Client is in test mode?
     #
     # @return [Boolean] Is the client set in test mode?
@@ -59,11 +82,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 +216,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)