mailgun-ruby 1.1.5 → 1.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 55f7b59eef02feab663dbffa1a3da56692c37737
-  data.tar.gz: 2d6ad04ff6ee6607554fcffea4453bb751a0162a
+  metadata.gz: e16b23def5c2076ebf90803c69e67c11275dd4cf
+  data.tar.gz: 538a0a0aa99f037d0ef044fc9d427483eb4073b1
 SHA512:
-  metadata.gz: 70292ac10f56e185894bf288861c861dcb16a03157bba9fe6bb4498f074ad56521fbe8ced7d2b609275742650293304fd26f3ec276fcca7f103e3e6d030c1c7c
-  data.tar.gz: 919717c8e88c1d8671be798a9ce53c4db246dd11927b74d0bb555b6bc2b34c00315c13337570197a7fdf2b84e13f9d2550013abd15e04574ec2f1e7df9f58c96
+  metadata.gz: 4c76cf234af827e8280e5eaa466d961817d30c3875345f4c481871ac8ca5083f11d4257ab06531c12dd693eab09e70910e6feaa13576766cd689caa32653c1f6
+  data.tar.gz: 305a1d5edc83fef3006682c884d9abee4ecf190e40919008b8985e6a86e5dd4f1506c3344a7641f67a435a5a3f510f1e350fb63daccb25fbcdec5cbfc1a20617

data/.ruby-env.yml.example

@@ -7,6 +7,6 @@
 # Replace <THESE_VALUES> with yours from
 # https://mailgun.com/app/dashboard (don't include <brackets>)
 # and rename to/save as: .ruby-env.yml
-MAILGUN_APIKEY : '<MAILGUN_APIKEY'>
+MAILGUN_APIKEY : '<MAILGUN_APIKEY>'
 MAILGUN_PUB_APIKEY : '<MAILGUN_PUBLIC_APIKEY>'
 MAILGUN_TESTDOMAIN : '<MAILGUN_SANDBOX_DOMAIN>'

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.1.4'
+gem 'mailgun-ruby', '~>1.1.6'
 ```
 
 Usage
@@ -150,12 +150,14 @@ For usage examples on each API endpoint, head over to our official documentation
 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)
 - [Opt-In Handler](docs/OptInHandler.md)
 - [Domains](docs/Domains.md)
 - [Webhooks](docs/Webhooks.md)
 - [Events](docs/Events.md)
+- [Suppressions](docs/Suppressions.md)
 
 Message Builder allows you to quickly create the array of parameters, required
 to send a message, by calling a methods for each parameter.
@@ -163,6 +165,31 @@ Batch Message is an extension of Message Builder, and allows you to easily send
 a batch message job within a few seconds. The complexity of
 batch messaging is eliminated!
 
+Testing mail deliveries
+----------------------
+
+```ruby
+# First, instantiate the Mailgun Client with your API key
+mg_client = Mailgun::Client.new 'your-api-key'
+
+# Put the client in test mode
+mg_client.enable_test_mode!
+
+# Define your message parameters
+message_params = {  from: 'bob@sending_domain.com',
+                    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('sending_domain.com', message_params)
+
+# You can now access a copy of message_params
+Mailgun::Client.deliveries.first[:from] # => 'bob@sending_domain.com'
+```
+
 Testing
 -------
 

data/docs/Domains.md

@@ -30,6 +30,24 @@ domainer.create 'my.new.moreness', { some: 'options' }
 domainer.remove 'this.one.is.not.needed.'
 ```
 
+Suppressions for a Domain
+-------------------------
+
+You can manage domain suppressions (bounces, unsubscribes, complaints) using the
+[`Mailgun::Suppressions`](/docs/Suppressions.md) client:
+
+```ruby
+# Instantiate the Mailgun Client with your API key
+mg_client = Mailgun::Client.new('your-api-key')
+supp_client = mg_client.suppressions('example.org')
+
+# ...
+```
+
+See the [Suppressions](/docs/Suppressions.md) for usage samples and
+[suppressions.rb](/lib/mailgun/suppressions.rb) for suppressions client API.
+
+
 More Documentation
 ------------------
 See the official [Mailgun Domain Docs](https://documentation.mailgun.com/api-domains.html)

data/docs/MessageBuilder.md

@@ -78,7 +78,7 @@ mg_client = Mailgun::Client.new("your-api-key")
 mb_obj = Mailgun::BatchMessage.new(mg_client, "example.com")
 
 # Define the from address.
-mb_obj.from("me@example.com", {"first"=>"Ruby", "last" => "SDK"});
+mb_obj.from("me@example.com", {"first" => "Ruby", "last" => "SDK"});
 
 # Define the subject.
 mb_obj.subject("A message from the Ruby SDK using Message Builder!");

data/docs/Messages.md

@@ -79,7 +79,7 @@ mb_obj.set_text_body("Hello %recipient.first%,
                      This is the text body of the message
                      using recipient variables!
                      If you need to include custom data,
-                     you could do it like this: %account-id%.")
+                     you could do it like this: %recipient.account-id%.")
 
 mb_obj.add_recipient(:to, "john.doe@example.com", {"first"      => "John",
                                                    "last"       => "Doe",

data/docs/Suppressions.md

@@ -0,0 +1,82 @@
+Mailgun - Suppressions
+====================
+
+This is the Mailgun Ruby *Suppressions* 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. It currently supports
+all calls except credentials.
+
+----
+
+The Suppressions client lets you manage bounces, unsubscribes, and complaints for a
+single domain.
+
+You can view additional samples in the [suppressions_spec.rb](/spec/integration/suppressions_spec.rb)
+or the Suppressions client API in [suppressions.rb](/lib/mailgun/suppressions.rb).
+
+
+Usage
+-----
+
+To get an instance of the Suppressions client:
+
+```ruby
+mg_client = Mailgun::Client.new('api_key')
+supp_client = mg_client.suppressions('yourdomain.com')
+```
+
+----
+
+To get a list of bounces, unsubscribes, and/or complaints:
+
+```ruby
+supp_client.list_bounces
+supp_client.list_unsubscribes
+supp_client.list_complaints
+```
+
+----
+
+To batch-add a set of bounces:
+
+```ruby
+@addresses = <load or generate some addresses...>
+
+bounces = []
+@addresses.each do |addr|
+  bounces.push({
+    :address => addr,
+    :code => 500,
+    :error => 'some bounce because reasons',
+  })
+end
+
+response, addt_responses = @supp_client.create_bounces bounces
+```
+
+`create_bounces`, `create_unsubscribes`, and `create_complaints` will all
+return two values - first, a simple `Mailgun::Response` object. Second,
+a list containing any `Mailgun::Response` objects created recursively, if over 998
+bounces were provided to `create_*`.
+
+----
+
+To delete bounces:
+
+```ruby
+@addresses = <load addresses...>
+
+@addresses.each do |addr|
+  @supp_client.delete_bounce addr
+end
+```
+
+Or, alternatively, to remove *all* bounces:
+
+```ruby
+@supp_client.delete_all_bounces
+```
+
+The `delete_*` methods are similar for `bounces`, `unsubscribe`, and `complaints` -
+they all will return a `Mailgun::Response` object.

data/lib/mailgun/client.rb

@@ -1,4 +1,5 @@
 require 'mailgun/chains'
+require 'mailgun/suppressions'
 require 'mailgun/exceptions/exceptions'
 
 module Mailgun
@@ -44,6 +45,13 @@ module Mailgun
       @test_mode
     end
 
+    # Provides a store of all the emails sent in test mode so you can check them.
+    #
+    # @return [Hash]
+    def self.deliveries
+      @@deliveries ||= []
+    end
+
     # Simple Message Sending
     #
     # @param [String] working_domain This is the domain you wish to send from.
@@ -52,6 +60,7 @@ module Mailgun
     # @return [Mailgun::Response] A Mailgun::Response object.
     def send_message(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."}',
@@ -141,6 +150,14 @@ module Mailgun
       raise communication_error err
     end
 
+    # Constructs a Suppressions client for the given domain.
+    #
+    # @param [String] domain Domain which suppressions requests will be made for
+    # @return [Mailgun::Suppressions]
+    def suppressions(domain)
+      Suppressions.new(self, domain)
+    end
+
     private
 
     # Converts MIME string to file for easy uploading to API

data/lib/mailgun/events/events.rb

@@ -11,6 +11,7 @@ module Mailgun
   #
   #    See the Github documentation for full examples.
   class Events
+    include Enumerable
 
     # Public: event initializer
     #
@@ -23,31 +24,47 @@ module Mailgun
       @paging_previous = nil
     end
 
-    # Public: Issues a simple get against the client.
+    # Public: Issues a simple get against the client. Alias of `next`.
     #
     # params - a Hash of query options and/or filters.
     #
     # Returns a Mailgun::Response object.
     def get(params = nil)
-      get_events(params)
+      self.next(params)
     end
 
     # Public: Using built in paging, obtains the next set of data.
     # If an events request hasn't been sent previously, this will send one
     #   without parameters
     #
+    # params - a Hash of query options and/or filters.
+    #
     # Returns a Mailgun::Response object.
-    def next
-      get_events(nil, @paging_next)
+    def next(params = nil)
+      get_events(params, @paging_next)
     end
 
     # Public: Using built in paging, obtains the previous set of data.
     # If an events request hasn't been sent previously, this will send one
     #   without parameters
     #
+    # params - a Hash of query options and/or filters.
+    #
     # Returns Mailgun::Response object.
-    def previous
-      get_events(nil, @paging_previous)
+    def previous(params = nil)
+      get_events(params, @paging_previous)
+    end
+
+    # Public: Allows iterating through all events and performs automatic paging.
+    #
+    # &block - Block to execute on items.
+    def each(&block)
+      items = self.next.to_h['items']
+
+      until items.empty?
+        items.each(&block)
+        items = self.next.to_h['items']
+      end
     end
 
     private

data/lib/mailgun/messages/message_builder.rb

@@ -133,6 +133,14 @@ module Mailgun
       add_file(:inline, inline_image, filename)
     end
 
+    # Adds a List-Unsubscribe for the message header.
+    #
+    # @param [Array<String>] *variables Any number of url or mailto
+    # @return [void]
+    def list_unsubscribe(*variables)
+      set_single('h:List-Unsubscribe', variables.map { |var| "<#{var}>" }.join(','))
+    end
+
     # Send a message in test mode. (The message won't really be sent to the recipient)
     #
     # @param [Boolean] mode The boolean or string value (will fix itself)

data/lib/mailgun/suppressions.rb

@@ -60,16 +60,17 @@ module Mailgun
     #
     # @param [Array] data Array of bounce hashes
     # @return [Response] Mailgun API response
-    # @return [Array] Array of invalid bounce hashes.
     # @return [Array] Return values from recursive call for list split.
     def create_bounces(data)
       # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
       split_return = []
       if data.length >= 1000 then
-        split_return = create_bounces data[999..-1]
+        resp, resp_l = create_bounces data[999..-1]
+        split_return.push(resp)
+        split_return.concat(resp_l)
         data = data[0..998]
       elsif data.length == 0 then
-        []
+        return nil, []
       end
 
       valid = []
@@ -132,16 +133,17 @@ module Mailgun
     #
     # @param [Array] data Array of unsubscribe hashes
     # @return [Response] Mailgun API response
-    # @return [Array] Array of invalid unsubscribe hashes.
     # @return [Array] Return values from recursive call for list split.
     def create_unsubscribes(data)
       # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
       split_return = []
       if data.length >= 1000 then
-        split_return = create_unsubscribes data[999..-1]
+        resp, resp_l = create_unsubscribes data[999..-1]
+        split_return.push(resp)
+        split_return.concat(resp_l)
         data = data[0..998]
       elsif data.length == 0 then
-        []
+        return nil, []
       end
 
       valid = []
@@ -197,16 +199,17 @@ module Mailgun
     #
     # @param [Array] data Array of complaint hashes
     # @return [Response] Mailgun API response
-    # @return [Array] Array of invalid complaint hashes.
     # @return [Array] Return values from recursive call for list split.
     def create_complaints(data)
       # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
       split_return = []
       if data.length >= 1000 then
-        split_return = create_complaints data[999..-1]
+        resp, resp_l = create_complaints data[999..-1]
+        split_return.push(resp)
+        split_return.concat(resp_l)
         data = data[0..998]
       elsif data.length == 0 then
-        []
+        return nil, []
       end
 
       valid = []

data/lib/mailgun/version.rb

@@ -1,4 +1,4 @@
 # It's the version. Yeay!
 module Mailgun
-  VERSION = '1.1.5'
+  VERSION = '1.1.6'
 end

data/lib/railgun/mailer.rb

@@ -20,7 +20,7 @@ module Railgun
       @config = config
 
       [:api_key, :domain].each do |k|
-        raise Railgun::ConfigurationError("Config requires `#{k}` key", @config) unless @config.has_key? k
+        raise Railgun::ConfigurationError.new("Config requires `#{k}` key", @config) unless @config.has_key?(k)
       end
 
       @mg_client = Mailgun::Client.new(config[:api_key])
@@ -97,6 +97,7 @@ module Railgun
     mb = Mailgun::MessageBuilder.new
 
     mb.from mail[:from]
+    mb.reply_to(mail[:reply_to].to_s) if mail[:reply_to].present?
     mb.subject mail.subject
     mb.body_html extract_body_html(mail)
     mb.body_text extract_body_text(mail)

data/spec/integration/events_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 require 'mailgun'
+require 'mailgun/events/events'
 
 vcr_opts = { :cassette_name => "events" }
 
@@ -7,9 +8,10 @@ describe 'For the Events endpoint', vcr: vcr_opts do
   before(:all) do
     @mg_obj = Mailgun::Client.new(APIKEY, APIHOST, APIVERSION, SSL)
     @domain = TESTDOMAIN
+    @events = Mailgun::Events.new(@mg_obj, @domain)
   end
 
-  it 'get an event.' do
+  it 'can get an event.' do
     result = @mg_obj.get("#{@domain}/events", {:limit => 1})
 
     result.to_h!
@@ -17,4 +19,10 @@ describe 'For the Events endpoint', vcr: vcr_opts do
     expect(result.body["paging"]).to include("next")
     expect(result.body["paging"]).to include("previous")
   end
+
+  it 'can iterate over all events with `each`' do
+    @events.each do |e|
+      expect(e.id).to eq("JAx9z641TuGGUyaJlD9sCQ")
+    end
+  end
 end

data/spec/unit/events/events_spec.rb

@@ -5,7 +5,7 @@ describe 'The method get' do
     @mg_obj = Mailgun::UnitClient.new('events')
     events = Mailgun::Events.new(@mg_obj, "samples.mailgun.org")
     result = events.get()
-    
+
     expect(result.body).to include("items")
     expect(result.body).to include("paging")
   end
@@ -17,7 +17,7 @@ describe 'The method next' do
     @mg_obj = Mailgun::UnitClient.new('events')
     events = Mailgun::Events.new(@mg_obj, "samples.mailgun.org")
     result = events.next()
-    
+
     expect(result.body).to include("items")
     expect(result.body).to include("paging")
   end
@@ -33,3 +33,18 @@ describe 'The method previous' do
     expect(result.body).to include("paging")
   end
 end
+
+describe 'The method each' do
+  it 'should iterate over all event items.' do
+    @mg_obj = Mailgun::UnitClient.new('events')
+    events = Mailgun::Events.new(@mg_obj, "samples.mailgun.org")
+    # Events from the UnitClient are actually empty.
+    count = 0
+    events.each do |e|
+      count = count + 1
+    end
+
+    # Better than nothing..
+    expect(count).to eq(0)
+  end
+end

data/spec/unit/messages/message_builder_spec.rb

@@ -249,6 +249,31 @@ describe 'The method add_inline_image' do
   end
 end
 
+describe 'The method list_unsubscribe' do
+  before(:each) do
+    @mb_obj = Mailgun::MessageBuilder.new
+  end
+
+  it 'sets the message list_unsubscribe to blank if called and no parameters are provided' do
+    @mb_obj.list_unsubscribe
+    expect(@mb_obj.message['h:List-Unsubscribe']).to eq('')
+  end
+
+  it 'sets the message list_unsubscribe if called with one list_unsubscribe parameter' do
+    unsubscribe_to = 'http://example.com/stop-hassle'
+    @mb_obj.list_unsubscribe(unsubscribe_to)
+    expect(@mb_obj.message['h:List-Unsubscribe']).to eq("<#{unsubscribe_to}>")
+  end
+
+  it 'sets the message list_unsubscribe if called with many list_unsubscribe parameters' do
+    unsubscribe_to = %w(http://example.com/stop-hassle mailto:stop-hassle@example.com)
+    @mb_obj.list_unsubscribe(*unsubscribe_to)
+    expect(@mb_obj.message['h:List-Unsubscribe']).to eq(
+      unsubscribe_to.map { |var| "<#{var}>" }.join(',')
+    )
+  end
+end
+
 describe 'The method set_test_mode' do
   it 'warns of set_test_mode deprecation' do
     @mb_obj = Mailgun::MessageBuilder.new

data/vcr_cassettes/events.yml

@@ -58,4 +58,51 @@ http_interactions:
         \ }\n}"
     http_version: 
   recorded_at: Thu, 07 Jan 2016 22:08:06 GMT
-recorded_with: VCR 3.0.1
+- request:
+    method: get
+    uri: https://api:<APIKEY>@api.mailgun.net/v3/DOMAIN.TEST/events
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Accept:
+      - "*/*"
+      Accept-Encoding:
+      - gzip, deflate
+      User-Agent:
+      - rest-client/2.0.1 (linux-gnu x86_64) ruby/2.3.3p222
+      Host:
+      - api.mailgun.net
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Headers:
+      - Content-Type, x-requested-with
+      Access-Control-Allow-Methods:
+      - GET, POST, PUT, DELETE, OPTIONS
+      Access-Control-Allow-Origin:
+      - "*"
+      Access-Control-Max-Age:
+      - '600'
+      Content-Type:
+      - application/json
+      Date:
+      - Wed, 10 May 2017 20:06:54 GMT
+      Server:
+      - nginx
+      Content-Length:
+      - '2060'
+      Connection:
+      - keep-alive
+    body:
+      encoding: UTF-8
+      string: "{\n  \"items\": [], \n  \"paging\": {\n    \"next\": \"https://api.mailgun.net/v3/DOMAIN.TEST/events/W3siYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIHsiYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIFsiZiJdLCBudWxsLCBbWyJhY2NvdW50LmlkIiwgIjU4MDUyMTg2NzhmYTE2MTNjNzkwYjUwZiJdLCBbImRvbWFpbi5uYW1lIiwgInNhbmRib3gyOTcwMTUyYWYzZDM0NTU5YmZjN2U3MTcwM2E2Y2YyNC5tYWlsZ3VuLm9yZyJdXSwgMTAwLCBudWxsXQ==\",
+        \n    \"last\": \"https://api.mailgun.net/v3/DOMAIN.TEST/events/W3siYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIHsiYiI6ICIyMDE3LTA1LTA4VDIwOjA2OjU0LjU3NyswMDowMCIsICJlIjogIjIwMTctMDUtMTBUMjA6MDY6NTQuNTc2KzAwOjAwIn0sIFsicCIsICJmIl0sIG51bGwsIFtbImFjY291bnQuaWQiLCAiNTgwNTIxODY3OGZhMTYxM2M3OTBiNTBmIl0sIFsiZG9tYWluLm5hbWUiLCAic2FuZGJveDI5NzAxNTJhZjNkMzQ1NTliZmM3ZTcxNzAzYTZjZjI0Lm1haWxndW4ub3JnIl1dLCAxMDAsIG51bGxd\",
+        \n    \"first\": \"https://api.mailgun.net/v3/DOMAIN.TEST/events/W3siYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIHsiYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIFsiZiJdLCBudWxsLCBbWyJhY2NvdW50LmlkIiwgIjU4MDUyMTg2NzhmYTE2MTNjNzkwYjUwZiJdLCBbImRvbWFpbi5uYW1lIiwgInNhbmRib3gyOTcwMTUyYWYzZDM0NTU5YmZjN2U3MTcwM2E2Y2YyNC5tYWlsZ3VuLm9yZyJdXSwgMTAwLCBudWxsXQ==\",
+        \n    \"previous\": \"https://api.mailgun.net/v3/DOMAIN.TEST/events/W3siYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIHsiYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMTBUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIFsicCIsICJmIl0sIG51bGwsIFtbImFjY291bnQuaWQiLCAiNTgwNTIxODY3OGZhMTYxM2M3OTBiNTBmIl0sIFsiZG9tYWluLm5hbWUiLCAic2FuZGJveDI5NzAxNTJhZjNkMzQ1NTliZmM3ZTcxNzAzYTZjZjI0Lm1haWxndW4ub3JnIl1dLCAxMDAsIG51bGxd\"\n
+        \ }\n}"
+    http_version: 
+  recorded_at: Wed, 10 May 2017 20:06:54 GMT
+recorded_with: VCR 3.0.3

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailgun-ruby
 version: !ruby/object:Gem::Version
-  version: 1.1.5
+  version: 1.1.6
 platform: ruby
 authors:
 - Mailgun
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-27 00:00:00.000000000 Z
+date: 2017-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -144,6 +144,7 @@ files:
 - docs/Messages.md
 - docs/OptInHandler.md
 - docs/Snippets.md
+- docs/Suppressions.md
 - docs/Webhooks.md
 - lib/mailgun-ruby.rb
 - lib/mailgun.rb