mailgun-ruby 1.1.2 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 7191c12a6dc2a08445f7cb623f10608e9208c9d2
-  data.tar.gz: 5033b5cd5eb92f6ce5c2d678222f8c7d9d118c78
+SHA256:
+  metadata.gz: 64d4a0d5c1b85d58db90763fc5dbcd0f813f29bf30b328fdda6b7a019fbeb445
+  data.tar.gz: 2ddef97a1b88cd9d45c5e2d1b41df3b61e7b3a09a5dcbe4c3b0a62191335aeed
 SHA512:
-  metadata.gz: 38dd19ded277a5566d738c88368b811607762ee258eaca48f7f1afe069b6fd84672bef1e6fb9637b028c06762c840dbd84b7a722ec2e6b7bd51828f99eedd406
-  data.tar.gz: a87aab066601ca346f897d551ff37165b862654d378c156df84b9443714c0795b9bb7299e16e0bce5666511d28900b0d0d7677ffe7ff826b2681d1d9c96ea7cc
+  metadata.gz: 18df9ff784b8c39376420fcebe0b16a195318e63b70e6b6f5fb6139fd4cbd276ef1647844de6fd12c1e272906862ddfcdc85bb59ab29460dee6e0e02ec872ee8
+  data.tar.gz: 25547234506d03d471ea3f3bbfb46eb6c10e104147f6fc7cbe3b3228b966d31b5a3e53f423554c22f45360c119c5c015659b819559ef8d664c7c5ac47be09d00

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,24 @@
 language: ruby
 sudo: false
 rvm:
-- 2.3.1
-- 2.2
-- 2.1
-- 2.0.0
+- 2.2.2
+- 2.2.10
+- 2.3.7
+- 2.4.4
+- 2.5.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.5.1"
 notifications:
   slack:
     rooms:

data/Gemfile

@@ -3,4 +3,4 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in mailgun.gemspec
 gemspec
 
-gem 'json', '~> 1.8', platform: :mri_19
+gem 'json', '~> 2.1', platform: :mri_19

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.1.2'
+gem 'mailgun-ruby', '~>1.2.4'
 ```
 
 Usage
@@ -27,6 +27,8 @@ Usage
 Here's how to send a message using the library:
 
 ```ruby
+require 'mailgun-ruby'
+
 # First, instantiate the Mailgun Client with your API key
 mg_client = Mailgun::Client.new 'your-api-key'
 
@@ -54,6 +56,12 @@ domain = 'example.com'
 result = mg_client.get("#{domain}/events", {:event => 'delivered'})
 ```
 
+If you're using the EU domains, make sure you specify it when creating the client:
+
+```
+mg_client = Mailgun::Client.new 'your-api-key', 'api.eu.mailgun.net'
+```
+
 Rails
 -----
 
@@ -63,8 +71,41 @@ Mailgun.configure do |config|
   config.api_key = 'your-secret-api-key'
 end
 ```
-Or have the initializer read your environment setting if you perfer.
+Or have the initializer read your environment setting if you prefer.
+
+To use as the ActionMailer delivery method, add this to your `config/environments/whatever.rb`
+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',
+    # api_host: 'api.eu.mailgun.net'  # Uncomment this line for EU region domains
+  }
+```
 
+To specify Mailgun options such as campaign or tags:
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome_email
+    mail(to: params[:to], subject: "Welcome!").tap do |message|
+      message.mailgun_options = {
+        "tag" => ["abtest-option-a", "beta-user"],
+        "tracking-opens" => true,
+        "tracking-clicks" => "htmlonly"
+      }
+    end
+  end
+end   
+```
+
+To get the Mailgun `message_id` after ActionMailer has successfully delivered the email:
+
+```ruby
+  mailer = UserNotifier.welcome_email(current_user)
+  mailer_response = mailer.deliver_now
+  mailgun_message_id = mailer_response.message_id
+```
 
 Response
 --------
@@ -136,15 +177,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 +195,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,44 @@ 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.
+
+# Set the Message-tags at most 3.
+mb_obj.add_tag("You can track mails as tag-units!")
+
+# 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 +76,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/{Webhooks.md → docs/Webhooks.md}

@@ -31,7 +31,7 @@ hook.create 'my.perfect.domain', 'deliver', 'https://the.webhook.url/'
 hook.remove 'my.perfect.domain', 'deliver'
 
 # Remove all webhooks for a domain
-hook.remove 'my.perfect.domain'
+hook.remove_all 'my.perfect.domain'
 ```
 
 More Documentation

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/lib/mailgun/address.rb

@@ -18,8 +18,11 @@ module Mailgun
     # Given an arbitrary address, validates it based on defined checks.
     #
     # @param [String] address Email address to validate (max 512 chars.)
-    def validate(address)
-      res = @client.get "address/validate", {:address => address}
+    def validate(address, mailbox_verification = false)
+      params = {:address => address}
+      params[:mailbox_verification] = true if mailbox_verification
+
+      res = @client.get "address/validate", params
       return res.to_h!
     end
 

data/lib/mailgun/client.rb

@@ -1,4 +1,5 @@
 require 'mailgun/chains'
+require 'mailgun/suppressions'
 require 'mailgun/exceptions/exceptions'
 
 module Mailgun
@@ -13,13 +14,18 @@ module Mailgun
                    api_host = 'api.mailgun.net',
                    api_version = 'v3',
                    ssl = true,
-                   test_mode = false)
+                   test_mode = false,
+                   timeout = nil)
+
+      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}")
+      @http_client = RestClient::Resource.new(endpoint, rest_client_params)
       @test_mode = test_mode
     end
 
@@ -44,6 +50,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.
@@ -51,7 +64,10 @@ 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
+
       if test_mode? then
+        Mailgun::Client.deliveries << data
         return Response.from_hash(
           {
             :body => '{"id": "test-mode-mail@localhost", "message": "Queued. Thank you."}',
@@ -62,6 +78,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 +103,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 +116,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 +157,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