mailgun-ruby 1.1.2 → 1.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7191c12a6dc2a08445f7cb623f10608e9208c9d2
-  data.tar.gz: 5033b5cd5eb92f6ce5c2d678222f8c7d9d118c78
+  metadata.gz: e16b23def5c2076ebf90803c69e67c11275dd4cf
+  data.tar.gz: 538a0a0aa99f037d0ef044fc9d427483eb4073b1
 SHA512:
-  metadata.gz: 38dd19ded277a5566d738c88368b811607762ee258eaca48f7f1afe069b6fd84672bef1e6fb9637b028c06762c840dbd84b7a722ec2e6b7bd51828f99eedd406
-  data.tar.gz: a87aab066601ca346f897d551ff37165b862654d378c156df84b9443714c0795b9bb7299e16e0bce5666511d28900b0d0d7677ffe7ff826b2681d1d9c96ea7cc
+  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/.travis.yml

@@ -1,21 +1,23 @@
 language: ruby
 sudo: false
 rvm:
-- 2.3.1
-- 2.2
-- 2.1
 - 2.0.0
+- 2.1
+- 2.2
+- 2.3.1
 script:
+- bundle install
 - bundle exec rake spec
 - '[[ "${TRAVIS_PULL_REQUEST}" == "false" ]] && ( bundle exec rake spec:integration
   ) || ( echo "Testing PR - No integration tests available")'
 deploy:
   provider: rubygems
   api_key:
-    secure: QTNP+6720w38b8krtvXM25WDEOUxw9BlUwdXgWLrU0MGAOSvVFgnWTJs+7QvGWODjhrIqAfAm11zc+yEpzgD9P8np9cteWv5K7rMxsUMcb14kaGIA+MKO+RRJXlru4teBNX5jtp2GJiNS2mn7urzn5YhE9x9P7pMjcF+j5usoF0=
+    secure: DoX3w48gRyhDM1o1OLvtWsTi8ehLIarIsErzg/UlNRoLacQt5l5UzwD+u6wqsCEr4+c2uAHNahafpnw/j1rPG3LBPIXOK5A0SYbjovlckutiAC0330Q4PHwOZb73AFN1DG5JTeg4/fguEjdsEBdZObF7mh5gBMBQtNjo1Fos+4w=
   gemspec: mailgun.gemspec
   on:
     tags: true
+    condition: "$TRAVIS_RUBY_VERSION == 2.3.1"
 notifications:
   slack:
     rooms:

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.1.2'
+gem 'mailgun-ruby', '~>1.1.6'
 ```
 
 Usage
@@ -27,6 +27,8 @@ Usage
 Here's how to send a message using the library:
 
 ```ruby
+require 'mailgun' 
+
 # First, instantiate the Mailgun Client with your API key
 mg_client = Mailgun::Client.new 'your-api-key'
 
@@ -65,6 +67,15 @@ end
 ```
 Or have the initializer read your environment setting if you perfer.
 
+To use as the ActionMailer delivery method, add this to your `config/environments/whatever.yml`
+and replace `api-myapikey` and `mydomain.com` with your secret API key and domain, respectively:
+```ruby
+  config.action_mailer.delivery_method = :mailgun
+  config.action_mailer.mailgun_settings = {
+    api_key: 'api-myapikey',
+    domain: 'mydomain.com',
+  }
+```
 
 Response
 --------
@@ -136,15 +147,17 @@ mg_client.send_message("sending_domain.com", message_params)
 ```
 
 For usage examples on each API endpoint, head over to our official documentation
-pages. Or the [Snippets](Snippets.md) file.
+pages. Or the [Snippets](docs/Snippets.md) file.
 
 This SDK includes the following components:
-- [Message Builder](Messages.md)
-- [Batch Message](Messages.md)
-- [Opt-In Handler](OptInHandler.md)
-- [Domains](Domains.md)
-- [Webhooks](Webhooks.md)
-- [Events](Events.md)
+- [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.
@@ -152,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/{Domains.md → 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/{MessageBuilder.md → docs/MessageBuilder.md}

@@ -24,28 +24,41 @@ mb_obj = Mailgun::MessageBuilder.new()
 
 # Define the from address.
 mb_obj.from("me@example.com", {"first"=>"Ruby", "last" => "SDK"});
+
 # Define a to recipient.
 mb_obj.add_recipient(:to, "john.doe@example.com", {"first" => "John", "last" => "Doe"});
+
 # Define a cc recipient.
 mb_obj.add_recipient(:cc, "sally.doe@example.com", {"first" => "Sally", "last" => "Doe"});
+
 # Define the subject.
 mb_obj.subject("A message from the Ruby SDK using Message Builder!");
+
 # Define the body of the message.
 mb_obj.body_text("This is the text body of the message!");
+
 # Set the Message-Id header, provide a valid Message-Id.
 mb_obj.message_id("<20141014000000.11111.11111@example.com>")
+
 # Or clear the Message-Id header, provide nil or empty string.
 mb_obj.message_id(nil)
 mb_obj.message_id('')
-# Campaign and other headers.
+
+# Campaigns and headers.
 mb_obj.add_campaign_id("My-Awesome-Campaign");
-mb_obj.add_custom_parameter("h:Customer-Id", "12345");
+mb_obj.header("Customer-Id", "12345");
+
+# Custom variables
+mb_obj.variable("Customer-Data", { :first_name => "John", :last_name => "Smith" })
 
 # Attach a file and rename it.
-mb_obj.add_attachment("/path/to/file/receipt_123491820.pdf", "Receipt.pdf");
+mb_obj.add_attachment "/path/to/file/receipt_123491820.pdf", "Receipt.pdf"
+
+# Attach an image inline.
+mb_obj.add_inline_image "/path/to/file/header.png"
 
 # Schedule message in the future
-mb_obj.delivery_at("tomorrow 8:00AM PST");
+mb_obj.deliver_at("tomorrow 8:00AM PST");
 
 # Finally, send your message using the client
 result = mg_client.send_message("sending_domain.com", mb_obj)
@@ -60,13 +73,16 @@ Here's how to use Batch Message to easily handle batch sending jobs.
 ```ruby
 # First, instantiate the Mailgun Client with your API key
 mg_client = Mailgun::Client.new("your-api-key")
+
 # Create a Batch Message object, pass in the client and your domain.
 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!");
+
 # Define the body of the message.
 mb_obj.body_text("This is the text body of the message!");
 

data/{Messages.md → docs/Messages.md}

@@ -50,8 +50,8 @@ mb_obj.set_message_id('')
 
 # Other Optional Parameters.
 mb_obj.add_campaign_id("My-Awesome-Campaign")
-mb_obj.add_custom_parameter("h:Customer-Id", "12345")
-mb_obj.add_attachment("@/tron.jpg")
+mb_obj.header("Customer-Id", "12345")
+mb_obj.add_attachment("./tron.jpg")
 mb_obj.set_delivery_time("tomorrow 8:00AM PST")
 mb_obj.set_click_tracking(true)
 
@@ -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/{Snippets.md → docs/Snippets.md}

@@ -41,8 +41,7 @@ mg_client.send_message "sending_domain.com", data
 
 ```ruby
 # Don't include a file, pull the file to a string
-mime_string = '
-From: Bob Sample <example@example.com>
+mime_string = 'From: Bob Sample <example@example.com>
 MIME-Version: 1.0
 Content-Type: multipart/mixed;
 boundary="--boundary-goes-here--"
@@ -76,6 +75,26 @@ mb_obj.set_text_body "This is the text body."
 mg_client.send_message "sending_domain.com", mb_obj
 ```
 
+**Build a message with attachments, part by part, with Message Builder:**
+
+```ruby
+mb_obj = Mailgun::MessageBuilder.new
+
+mb_obj.set_from_address "sender@example.com", {'first' => 'Sending', 'last' => 'User'}
+mb_obj.add_recipient :to, "recipient@example.com", {'first' => 'Recipient', 'last' => 'User'}
+mb_obj.set_subject "This is the subject!"
+mb_obj.set_text_body "This is the text body."
+
+# Add separate attachments
+mb_obj.add_attachment "/path/to/file/invoice_8675309.pdf", "Order Invoice - 8675309.pdf"
+mb_obj.add_attachment "/path/to/file/datasheet_00001.pdf", "Product Datasheet - 00001.pdf"
+
+# Attach inline image to message
+mb_obj.add_inline_image "/path/to/file/product_image_00001.png"
+
+mg_client.send_message "sending_domain.com", mb_obj
+```
+
 **Send batches of 1000 messages per post:**
 
 ```ruby

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."}',
@@ -62,6 +71,11 @@ module Mailgun
 
       case data
       when Hash
+        # Remove nil values from the data hash
+        # Submitting nils to the API will likely cause an error.
+        #  See also: https://github.com/mailgun/mailgun-ruby/issues/32
+        data = data.select { |k, v| v != nil }
+
         if data.key?(:message)
           if data[:message].is_a?(String)
             data[:message] = convert_string_to_file(data[:message])
@@ -82,9 +96,10 @@ module Mailgun
     # with. Be sure to include your domain, where necessary.
     # @param [Hash] data This should be a standard Hash
     # containing required parameters for the requested resource.
+    # @param [Hash] headers Additional headers to pass to the resource.
     # @return [Mailgun::Response] A Mailgun::Response object.
-    def post(resource_path, data)
-      response = @http_client[resource_path].post(data)
+    def post(resource_path, data, headers = {})
+      response = @http_client[resource_path].post(data, headers)
       Response.new(response)
     rescue => err
       raise communication_error err
@@ -94,8 +109,9 @@ module Mailgun
     #
     # @param [String] resource_path This is the API resource you wish to interact
     # with. Be sure to include your domain, where necessary.
-    # @param [Hash] query_string This should be a standard Hash
+    # @param [Hash] params This should be a standard Hash
     # containing required parameters for the requested resource.
+    # @param [String] accept Acceptable Content-Type of the response body.
     # @return [Mailgun::Response] A Mailgun::Response object.
     def get(resource_path, params = nil, accept = '*/*')
       if params
@@ -134,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/batch_message.rb

@@ -48,7 +48,7 @@ module Mailgun
       send_message if @counters[:recipients][recipient_type] == Mailgun::Chains::MAX_RECIPIENTS
 
       compiled_address = parse_address(address, variables)
-      complex_setter(recipient_type, compiled_address)
+      set_multi_complex(recipient_type, compiled_address)
 
       store_recipient_variables(recipient_type, address, variables) if recipient_type != :from
 
@@ -84,7 +84,7 @@ module Mailgun
     # @return [Boolean]
     def send_message
       rkey = 'recipient-variables'
-      simple_setter rkey, JSON.generate(@recipient_variables)
+      set_multi_simple rkey, JSON.generate(@recipient_variables)
       @message[rkey] = @message[rkey].first if @message.key?(rkey)
 
       response = @client.send_message(@domain, @message).to_h!