mailgun-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d0af97ef09388ef5e354ea330f46da241d89528a
+  data.tar.gz: 9c79b5dda98783d6a783e280323f7cd2b7026519
+SHA512:
+  metadata.gz: 4c908d5931b2b65655ee7138497c0aece18773c4c7b9d278ed69fc2ae72fd23ebd2b3ab1ddb2645767bc2a4a89bdf6bd9a2624904a7a8411598ef4675234fc55
+  data.tar.gz: 6beb9e890aeaf563521d2c341e86eaead15d25939243a2de33aa01ff76ea1c430fb4f7e45b95f27f29a557777f8595f746cb2cbf0fa5cc38a983f9d39c75d908

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.DS_Store
+test.rb
+ruby

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mailgun.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,191 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where
+such license applies only to those patent claims licensable by such Contributor
+that are necessarily infringed by their Contribution(s) alone or by combination
+of their Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+Contribution incorporated within the Work constitutes direct or contributory
+patent infringement, then any patent licenses granted to You under this License
+for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute,
+all copyright, patent, trademark, and attribution notices from the Source form
+of the Work, excluding those notices that do not pertain to any part of the
+Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any
+Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of
+any separate license agreement you may have executed with Licensor regarding
+such Contributions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work (and each Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental,
+or consequential damages of any character arising as a result of this License or
+out of the use or inability to use the Work (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or
+any and all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License. However,
+in accepting such obligations, You may act only on Your own behalf and on Your
+sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification within
+third-party archives.
+
+   Copyright [2013] [Rackpace]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/MessageBuilder.md

@@ -0,0 +1,85 @@
+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.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!");
+
+# Campaign and other headers.
+mb_obj.add_campaign_id("My-Awesome-Campaign");
+mb_obj.add_custom_parameter("h:Customer-Id", "12345");
+
+# Attach a file and rename it.
+mb_obj.add_attachment("/path/to/file/receipt_123491820.pdf", "Receipt.pdf");
+
+# Schedule message in the future
+mb_obj.set_delivery_time("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(@mb_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("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 = mg_client.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/Messages.md

@@ -0,0 +1,77 @@
+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::BatchMessage.new(@mb_client, "example.com")
+
+# 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!");
+
+# 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.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(@mb_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("This is the text body of the message!");
+
+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"});
+
+# Send your message through the client
+message_ids = mg_client.finalize
+```
+
+More Documentation
+------------------
+See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) 
+for more information.

data/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});
+
+if result[: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](http://documentation.mailgun.com/api-sending.html) 
+for more information.