mailgun-ruby 1.1.0 → 1.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 15c6226ce2745501543bd148db41a0297f2d58df
-  data.tar.gz: 2110bec8de2f21d49fee5d56ad41aef0d4fbc2b7
+SHA256:
+  metadata.gz: eeb68d33e0686c3074e829fa7c33c1a9300c31bd9db3b7fde74abfdbdd681a31
+  data.tar.gz: dc0cd7912abb804476731ba487186a362595f7806d88f50bbbe2296da8eb0b5b
 SHA512:
-  metadata.gz: 04f6a82d67c5d8cda08c7a38956edfab2ff28b9c16b9344fcee2e3ec3caf1e0e69f901797de3a98640a962af9c28fff58d7151deb3cffbc32bee740df48eb901
-  data.tar.gz: 4fc8aec4b0e5e5c100a707c3cf44151b9eb2fe1e1cd047bf0df3c0122c1443c9264e048d27fe65390e23a9718be2ce5ab8d6009deaaf7ec0f512e9a7217f3552
+  metadata.gz: 9469121fbdd8341af7cc6ee395d35d8f487f556b67d8b6a0d2b6cd874f4bb1828384f9aff7c6751377fa56182b7c890947e40444f09d583d97aca8f90c41c642
+  data.tar.gz: 2f2b70e53e187c28ea3fcf3d3abc3f208886baca01732af0bb233c154bd171565790279620fe392259f3fa74151276d4e281389606d35ce60047b6f9a922a7cf

data/.gitignore

@@ -20,3 +20,4 @@ test.rb
 ruby
 .ruby-env.yml
 .rspec-local
+.tool-versions

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,9 +1,25 @@
 language: ruby
-rvm:
-  - 2.2
-  - 2.1
-  - 2.0.0
-  - 1.9.3
 sudo: false
-gemfile: Gemfile
-script: bundle exec rake spec
+rvm:
+- 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: DoX3w48gRyhDM1o1OLvtWsTi8ehLIarIsErzg/UlNRoLacQt5l5UzwD+u6wqsCEr4+c2uAHNahafpnw/j1rPG3LBPIXOK5A0SYbjovlckutiAC0330Q4PHwOZb73AFN1DG5JTeg4/fguEjdsEBdZObF7mh5gBMBQtNjo1Fos+4w=
+  gemspec: mailgun.gemspec
+  on:
+    tags: true
+    condition: "$TRAVIS_RUBY_VERSION == 2.5.1"
+notifications:
+  slack:
+    rooms:
+      secure: G4iBtDfFGeryQslfrKZK4hSPikOy9y3SDnpzwmN8SoB0uIAWE2mLfMUJZonKm7yoz+DbPU0u3c1SwiMLwHkXZhPdnJdC1fb1DpicXnVgGZYdiLGiY+OAwkvcBE9p3piWhpwigTjvmSqTaNSRL/VLhG4qwQbHU0fTl1M1zwU4e6c=

data/Gemfile

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

data/README.md

@@ -19,14 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.0.5', require: 'mailgun'
-```
-
-Include
---------
-
-```ruby
-require 'mailgun'
+gem 'mailgun-ruby', '~>1.2.5'
 ```
 
 Usage
@@ -34,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'
 
@@ -52,7 +47,7 @@ Or obtain the last couple log items:
 
 ```ruby
 # First, instantiate the Mailgun Client with your API key
-mg_client = Mailgun::Client.new 'your-api-key'
+mg_client = Mailgun::Client.new 'your-secret-api-key'
 
 # Define the domain you wish to query
 domain = 'example.com'
@@ -61,17 +56,56 @@ 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
 -----
 
 The library can be initialized with a Rails initializer containing similar:
 ```ruby
 Mailgun.configure do |config|
-  config.api_key = 'your-secret-key'
+  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
 --------
@@ -143,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.
@@ -159,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}

@@ -23,29 +23,45 @@ mg_client = Mailgun::Client.new("your-api-key")
 mb_obj = Mailgun::MessageBuilder.new()
 
 # Define the from address.
-mb_obj.set_from_address("me@example.com", {"first"=>"Ruby", "last" => "SDK"});
+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.set_subject("A message from the Ruby SDK using Message Builder!");
+mb_obj.subject("A message from the Ruby SDK using Message Builder!");
+
 # Define the body of the message.
-mb_obj.set_text_body("This is the text 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.set_message_id("<20141014000000.11111.11111@example.com>")
+mb_obj.message_id("<20141014000000.11111.11111@example.com>")
+
 # Or clear the Message-Id header, provide nil or empty string.
-mb_obj.set_message_id(nil)
-mb_obj.set_message_id('')
-# Campaign and other headers.
+mb_obj.message_id(nil)
+mb_obj.message_id('')
+
+# 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.set_delivery_time("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,15 +76,18 @@ 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.set_from_address("me@example.com", {"first"=>"Ruby", "last" => "SDK"});
+mb_obj.from("me@example.com", {"first" => "Ruby", "last" => "SDK"});
+
 # Define the subject.
-mb_obj.set_subject("A message from the Ruby SDK using Message Builder!");
+mb_obj.subject("A message from the Ruby SDK using Message Builder!");
+
 # Define the body of the message.
-mb_obj.set_text_body("This is the text body of the message!");
+mb_obj.body_text("This is the text body of the message!");
 
 
 # Loop through all of your recipients

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

@@ -0,0 +1,48 @@
+require 'mailgun/exceptions/exceptions'
+
+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)
+    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[: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