wj-mailgun-ruby 1.1.7

data/Rakefile

@@ -0,0 +1,35 @@
+require 'bundler/gem_tasks'
+require 'rake'
+require 'rspec/core/rake_task'
+
+desc 'Build Gem'
+task :build do
+  system 'gem build mailgun.gemspec'
+end
+
+desc 'Run unit specs'
+RSpec::Core::RakeTask.new('spec:unit') do |t|
+  t.rspec_opts = %w(--colour --format documentation)
+  t.pattern = 'spec/unit/*_spec.rb', 'spec/unit/*/*_spec.rb'
+end
+
+desc 'Run integration specs'
+# Before running integration tests, you need to specify
+# a valid API KEY in the spec/spec_helper.rb file.
+RSpec::Core::RakeTask.new('spec:integration') do |t|
+  t.rspec_opts = %w(--colour --format documentation)
+  t.pattern = 'spec/integration/*_spec.rb'
+end
+
+desc 'Run all tests'
+RSpec::Core::RakeTask.new('spec:all') do |t|
+  t.rspec_opts = %w(--colour --format documentation)
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+task default: 'spec:unit'
+task spec: 'spec:unit'
+
+task :console do
+  sh 'pry --gem'
+end

data/docs/Domains.md

@@ -0,0 +1,54 @@
+Mailgun - Domains
+====================
+
+This is the Mailgun Ruby *Domain* 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.
+
+Usage - Domains
+-----------------------
+
+```ruby
+# First, instantiate the Mailgun Client with your API key
+mg_client = Mailgun::Client.new('your-api-key')
+domainer = Mailgun::Domains.new(mg_client)
+
+# Get a list of current domains.
+domainer.list
+
+# View details of a domain
+domainer.info 'my.perfect.domain'
+
+# Add a new domain
+domainer.create 'my.new.moreness'
+# or with options
+domainer.create 'my.new.moreness', { some: 'options' }
+
+# Remove a domain
+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)
+for more information

data/docs/Events.md

@@ -0,0 +1,46 @@
+Mailgun - Events
+====================
+
+This is the Mailgun Ruby *Events* utility.
+
+The below assumes you've already installed the Mailgun Ruby SDK in your project.
+If not, go back to the master README for a few quick install steps.
+
+Events: Provides methods for traversing the Mailgun Events API.
+
+
+Usage - Events
+-----------------------------------------------------
+Here's how to use the Events Handler to pull events.
+
+```ruby
+# First, instantiate the SDK with your API credentials, domain, and required parameters for example.
+mg_client = Mailgun::Client.new("your-api-key")
+mg_events = Mailgun::Events.new(mg_client, "your-domain")
+
+result = mg_events.get({'limit' => 25,
+                        'recipient' => 'joe@example.com'})
+
+result.to_h['items'].each do | item |
+    # outputs "Delivered - 20140509184016.12571.48844@example.com"
+    puts "#{item['event']} - #{item['message']['headers']['message-id']}"
+end
+
+# Want more results?
+result = mg_events.next
+
+# Go backwards?
+result = mg_events.previous
+```
+
+A few notes:  
+1. Next will use the pagination links to advance the result set.
+Retain the mg_events object to query forward, or reverse, at any time.  
+2. If the result set is less than your limit, do not worry. A
+second query against "next" will return the next 25 results since the
+last time you called "next".
+
+More Documentation
+------------------
+See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html)
+for more information.

data/docs/MessageBuilder.md

@@ -0,0 +1,105 @@
+Mailgun - Messages
+====================
+
+This is the Mailgun Ruby *Message* utilities.
+
+The below assumes you've already installed the Mailgun Gem. If not, go back to the master README for instructions.
+
+There are two utilities included, Message Builder and Batch Message.
+
+Message Builder: Allows you to build a message object by calling methods for
+each attribute.
+Batch Message: Inherits Message Builder and allows you to iterate through
+recipients from a list. Messages will fire after the 1,000th recipient has been
+added.
+
+Usage - Message Builder
+-----------------------
+Here's how to use Message Builder to build your Message.
+
+```ruby
+# First, instantiate the Mailgun Client with your API key
+mg_client = Mailgun::Client.new("your-api-key")
+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('')
+
+# Campaigns and headers.
+mb_obj.add_campaign_id("My-Awesome-Campaign");
+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"
+
+# Attach an image inline.
+mb_obj.add_inline_image "/path/to/file/header.png"
+
+# Schedule message in the future
+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)
+
+puts result.body.to_s
+```
+
+Usage - Batch Message
+---------------------
+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"});
+
+# 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!");
+
+
+# Loop through all of your recipients
+mb_obj.add_recipient(:to, "john.doe@example.com", {"first" => "John", "last" => "Doe"});
+mb_obj.add_recipient(:to, "jane.doe@example.com", {"first" => "Jane", "last" => "Doe"});
+mb_obj.add_recipient(:to, "bob.doe@example.com", {"first" => "Bob", "last" => "Doe"});
+...
+mb_obj.add_recipient(:to, "sally.doe@example.com", {"first" => "Sally", "last" => "Doe"});
+
+# Call finalize to get a list of message ids and totals.
+message_ids = mb_obj.finalize
+# {'id1234@example.com' => 1000, 'id5678@example.com' => 15}
+```
+
+More Documentation
+------------------
+See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html)
+for more information.

data/docs/Messages.md

@@ -0,0 +1,107 @@
+Mailgun - Messages
+====================
+
+This is the Mailgun Ruby *Message* 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.
+
+There are two utilities included, Message Builder and Batch Message.
+
+Message Builder: Allows you to build a message object by calling methods for
+each MIME attribute.
+Batch Message: Inherits Message Builder and allows you to iterate through
+recipients from a list. Messages will fire after the 1,000th recipient has been
+added.
+
+Usage - Message Builder
+-----------------------
+Here's how to use Message Builder to build your Message.
+
+```ruby
+# First, instantiate the Mailgun Client with your API key
+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"})
+
+# 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!")
+
+# Define the body of the message.
+mb_obj.set_text_body("This is the text body of the message!")
+
+# Define the HTML text of the message
+mb_obj.set_html_body("<html><body><p>This is the text body of the message</p></body></html>")
+
+# Set the Message-Id header. Pass in a valid Message-Id.
+mb_obj.set_message_id("<20141014000000.11111.11111@example.com>")
+
+# Clear the Message-Id header. Pass in nil or empty string.
+mb_obj.set_message_id(nil)
+mb_obj.set_message_id('')
+
+# Other Optional Parameters.
+mb_obj.add_campaign_id("My-Awesome-Campaign")
+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)
+
+# Send your message through the client
+mg_client.send_message("sending_domain.com", mb_obj)
+```
+
+Usage - Batch Message
+---------------------
+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")
+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"})
+
+# Define the subject.
+mb_obj.set_subject("A message from the Ruby SDK using Message Builder!")
+
+# Define the body of the message.
+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: %recipient.account-id%.")
+
+mb_obj.add_recipient(:to, "john.doe@example.com", {"first"      => "John",
+                                                   "last"       => "Doe",
+                                                   "account-id" => 1234})
+
+mb_obj.add_recipient(:to, "jane.doe@example.com", {"first"      => "Jane",
+                                                   "last"       => "Doe",
+                                                   "account-id" => 5678})
+
+mb_obj.add_recipient(:to, "bob.doe@example.com", {"first"       => "Bob",
+                                                  "last"        => "Doe",
+                                                  "account-id"  => 91011})
+...
+mb_obj.add_recipient(:to, "sally.doe@example.com", {"first"      => "Sally",
+                                                    "last"       => "Doe",
+                                                    "account-id" => 121314})
+
+# Send your message through the client
+message_ids = mb_obj.finalize
+```
+
+More Documentation
+------------------
+See the official [Mailgun Docs](https://documentation.mailgun.com/api-sending.html)
+for more information.

data/docs/OptInHandler.md

@@ -0,0 +1,103 @@
+Mailgun - Lists
+====================
+
+This is the Mailgun Ruby *Lists* utilities.
+
+The below assumes you've already installed the Mailgun Ruby SDK in your project.
+If not, go back to the master README for a few quick install steps.
+
+OptInHandler: Provides methods for authenticating an Opt-In Request.
+
+The typical flow for using this utility would be as follows:
+**Recipient Requests Subscribe** -> [Validate Recipient Address] -> [Generate Opt-In Link] -> [Email Recipient Opt-In Link]
+**Recipient Clicks Opt-In Link** -> [Validate Opt-In Link] -> [Subscribe User] -> [Send final confirmation]
+
+The above flow is modeled below.
+
+Usage - Opt-In Handler (Recipient Requests Subscribe)
+-----------------------------------------------------
+Here's how to use Opt-In Handler to validate Opt-In requests.
+
+```ruby
+# First, instantiate the SDK with your API credentials, domain, and required parameters for example.
+mg_client = Mailgun::Client.new("your-api-key")
+mg_validate = Mailgun::Client.new("your-pub-api-key")
+
+domain = 'example.com';
+
+mailing_list = 'youlist@example.com';
+secret_app_id = 'a_secret_passphrase';
+recipient_address = 'recipient@example.com';
+
+# Let's validate the customer's email address, using Mailgun's validation endpoint.
+result = mg_validate.get('address/validate', {:address => recipient_address});
+body = JSON.parse(result.body)
+
+if body['is_valid'] == true
+	# Next, generate a hash.
+	generated_hash = Mailgun::OptInHandler.generate_hash(mailing_list, secret_app_id, recipient_address);
+	
+	# Now, let's send a confirmation to the recipient with our link.
+	mg_client.send_message(domain, {:from    => 'bob@example.com',
+	                                :to      => recipient_address,
+	                                :subject => 'Please Confirm!',
+	                                :html    => "<html><body>Hello,<br><br>You have requested to be subscribed
+		                            to the mailing list #{mailing_list}. Please <a
+		                            href=\"http://yourdomain.com/subscribe.php?hash=#{generated_hash}\">
+		                            confirm</a> your subscription.<br><br>Thank you!</body></html>"});
+	                                			  
+	# Finally, let's add the subscriber to a Mailing List, as unsubscribed, so we can track non-conversions.
+	mg_client.post("lists/#{mailing_list}/members", {:address    => recipient_address,
+	                                		         :subscribed => 'no',
+	                                			     :upsert     => 'yes'});
+end
+```
+
+Usage - Opt-In Handler (Recipient Clicks Opt In Link)
+-----------------------------------------------------
+Here's how to use Opt-In Handler to validate an Opt-In Hash.
+
+```ruby
+# First, instantiate the SDK with your API credentials and domain.
+mg_client = Mailgun::Client.new("your-api-key")
+domain = 'example.com';
+
+# Now, validate the captured hash.
+hash_validation = Mailgun::OptInHandler.validate_hash(secret_app_id, inbound_hash);
+
+# Lastly, check to see if we have results, parse, subscribe, and send confirmation.
+if !hash_validation.nil?
+	validated_list = hash_validation['mailing_list'];
+	validated_recipient = hash_validation['recipient_address'];
+	
+	mg_client.put("lists/#{validated_list}/members/#{validated_recipient}",
+							{:address    => validated_recipient,
+	                         :subscribed => 'yes'})
+    
+    mg_client.send_message(domain, {:from    => 'bob@example.com',
+                                    :to      => validated_recipient,
+                                    :subject => 'Confirmation Received!',
+                                    :html    => "<html><body>Hello,<br><br>We've successfully subscribed you to the list, #{validated_list}!<br><br>Thank you!
+                                    </body></html>"});
+end
+```
+
+A few notes:
+1. 'secret_app_id' can be anything. It's used as the *key* in hashing,
+since your email address will vary. It should be secured like a password.
+2. validateHash will return an array containing the recipient address and list
+address.
+3. You should *always* send an email confirmation before and after the
+subscription request. This is what double-opt in means.
+
+
+Available Functions
+-----------------------------------------------------
+
+`string generate_hash(string mailing_list, string secret_app_id, string recipient_address)`
+
+`array validate_hash(string secret_app_id, string unique_hash)`
+
+More Documentation
+------------------
+See the official [Mailgun Docs](https://documentation.mailgun.com/api-sending.html) for more information.