mailgun-ruby 1.2.0 → 1.2.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68010cfb6e35b2a015974c634c156f502a7fe76e75e571ad394761d8e6a50d97
-  data.tar.gz: 14f7dc96ffbb2d5bf1e499a336efe276235e0b260c580b40171236b3ea5f77fd
+  metadata.gz: 846d1a1383139f176ad8508d5e465ddfa90617e1b7cc138de178344f11b97365
+  data.tar.gz: b64fa898adc500f8c5ba7a21af1e02ec92eac3996905ce4a7851cebbe08d2bcd
 SHA512:
-  metadata.gz: 39d8397545a5c30c703cde0c32558c595d4479faa91595299232b113b23d60d0e0ad88f197616fc6a8d2cde2c1952cc3c9effe5fced19a208f5f290cca45f658
-  data.tar.gz: 2eed77f10d1090339987b0a9b120a65017267ced80e694a7710b5058fd14145bab6a2c091c39fa6495c52242648b9524fc88c0a35c782b6dd7057aa57691c16e
+  metadata.gz: bd26107fe4db4917f5e78141ed9fe6ca5d659ae1aea7959316bc12e5c18b130a9b5397c9aaf0c31001ba6bd4a2d490c1ec04f5c592c2653c0fa19b5342ff0996
+  data.tar.gz: 47b6b488bdae399de35f1418cd92015f0764f884b8a39d2c45c002b4f6bb1db367bd4a24dd6e985b8392f5ef442dc789e17fdd3ac270ad798e44984ddcf3777d

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.1.6'
+gem 'mailgun-ruby', '~>1.2.10'
 ```
 
 Usage
@@ -56,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
 -----
 
@@ -74,6 +80,7 @@ and replace `api-myapikey` and `mydomain.com` with your secret API key and domai
   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
   }
 ```
 
@@ -181,6 +188,7 @@ This SDK includes the following components:
 - [Webhooks](docs/Webhooks.md)
 - [Events](docs/Events.md)
 - [Suppressions](docs/Suppressions.md)
+- [Templates](docs/Templates.md)
 
 Message Builder allows you to quickly create the array of parameters, required
 to send a message, by calling a methods for each parameter.

data/docs/Domains.md

@@ -28,6 +28,9 @@ domainer.create 'my.new.moreness', { some: 'options' }
 
 # Remove a domain
 domainer.remove 'this.one.is.not.needed.'
+
+# Update a domain
+domainer.update 'my.new.moreness', { some: 'options' }
 ```
 
 Suppressions for a Domain

data/docs/OptInHandler.md

@@ -100,4 +100,4 @@ Available Functions
 
 More Documentation
 ------------------
-See the official [Mailgun Docs](https://documentation.mailgun.com/api-sending.html) for more information.
+See the official [Mailgun Docs](https://documentation.mailgun.com/en/latest/api-sending.html) for more information.

data/docs/Snippets.md

@@ -110,7 +110,7 @@ bm_obj.set_text_body "This is the text body."
 bm_obj.add_recipient :to, "a_user@example.com"
 
 # All message IDs returned in finalize method return
-message_ids = @bm_obj.finalize
+message_ids = bm_obj.finalize
 ```
 
 ### Domains:
@@ -118,57 +118,57 @@ ____________________________________________________
 **Get a list of all domains:**
 
 ```ruby
-result = @mg_client.get "domains", {:limit => 5, :skip => 0}
+result = mg_client.get "domains", {:limit => 5, :skip => 0}
 ```
 
 **Get a single domain:**
 
 ```ruby
-result = @mg_client.get "domains/#{domain}"
+result = mg_client.get "domains/#{domain}"
 ```
 
 **Add a domain:**
 
 ```ruby
-result = @mg_client.post "domains", {:name => 'anothersample.mailgun.org',
+result = mg_client.post "domains", {:name => 'anothersample.mailgun.org',
                                      :smtp_password => 'super_secret',
                                      :spam_action => 'tag'}
 ```
 **Delete a Domain: **
 
 ```ruby
-result = @mg_client.delete "domains/#{domain}"
+result = mg_client.delete "domains/#{domain}"
 ```
 ### Unsubscribes:
 ____________________________________________________
 **Get List of Unsubscribes: **
 
 ```ruby
-result = @mg_client.get "#{domain}/unsubscribes", {:limit => 50, :skip => 10}
+result = mg_client.get "#{domain}/unsubscribes", {:limit => 50, :skip => 10}
 ```
 
 **Get Single Unsubscribe: **
 
 ```ruby
-result = @mg_client.get "#{domain}/unsubscribes/#{email_address}"
+result = mg_client.get "#{domain}/unsubscribes/#{email_address}"
 ```
 
 **Unsubscribe a Recipient: **
 
 ```ruby
-result = @mg_client.post "#{domain}/unsubscribes", {:address => 'bob@example.com', :tag => 'mypromotion'}
+result = mg_client.post "#{domain}/unsubscribes", {:address => 'bob@example.com', :tag => 'mypromotion'}
 ```
 
 **Unsubscribe from all messages for a domain: **
 
 ```ruby
-result = @mg_client.post "#{domain}/unsubscribes", {:address => 'bob@example.com', :tag => '*'}
+result = mg_client.post "#{domain}/unsubscribes", {:address => 'bob@example.com', :tag => '*'}
 ```
 
 **Remove an unsubscribe: **
 
 ```ruby
-result = @mg_client.delete "#{domain}/unsubscribes/#{email_address}"
+result = mg_client.delete "#{domain}/unsubscribes/#{email_address}"
 ```
 
 ### Complaints:
@@ -176,24 +176,24 @@ ____________________________________________________
 **Get List of Complaints: **
 
 ```ruby
-result = @mg_client.get "#{domain}/complaints", {:limit => 50, :skip => 10}
+result = mg_client.get "#{domain}/complaints", {:limit => 50, :skip => 10}
 ```
 
 **Get a Single Complaint: **
 
 ```ruby
-result = @mg_client.get "#{domain}/complaints/#{email_address}"
+result = mg_client.get "#{domain}/complaints/#{email_address}"
 ```
 **Create a complaint: **
 
 ```ruby
-result = @mg_client.post "#{domain}/complaint", {:address => 'bob@example.com'}
+result = mg_client.post "#{domain}/complaint", {:address => 'bob@example.com'}
 ```
 
 **Remove a complaint: **
 
 ```ruby
-result = @mg_client.delete "#{domain}/complaint/#{email_address}"
+result = mg_client.delete "#{domain}/complaint/#{email_address}"
 ```
 
 ### Bounces:
@@ -201,19 +201,19 @@ ____________________________________________________
 **Get List of Bounces: **
 
 ```ruby
-result = @mg_client.get "#{domain}/bounces", {:limit => 50, :skip => 10}
+result = mg_client.get "#{domain}/bounces", {:limit => 50, :skip => 10}
 ```
 
 **Get a Single Bounce Event: **
 
 ```ruby
-result = @mg_client.get "#{domain}/bounces/#{email_address}"
+result = mg_client.get "#{domain}/bounces/#{email_address}"
 ```
 
 **Create a Bounce: **
 
 ```ruby
-result = @mg_client.post "#{domain}/bounces", {:address => 'bob@example.com',
+result = mg_client.post "#{domain}/bounces", {:address => 'bob@example.com',
                                                :code => 550,
                                                :error => 'Mailbox does not exist.'}
 ```
@@ -221,7 +221,7 @@ result = @mg_client.post "#{domain}/bounces", {:address => 'bob@example.com',
 **Remove a Bounced Address: **
 
 ```ruby
-result = @mg_client.delete "#{domain}/bounces/#{email_address}"
+result = mg_client.delete "#{domain}/bounces/#{email_address}"
 ```
 
 ### Statistics:
@@ -229,7 +229,7 @@ ____________________________________________________
 **Get Statistics: **
 
 ```ruby
-result = @mg_client.get "#{domain}/stats", {:limit => 50,
+result = mg_client.get "#{domain}/stats", {:limit => 50,
                                             :skip => 10,
                                             :event => 'sent',
                                             "start-date" => 'Mon, 13 Feb 2015 00:00:00 GMT'}
@@ -238,14 +238,14 @@ result = @mg_client.get "#{domain}/stats", {:limit => 50,
 **Remove a Tag: **
 
 ```ruby
-result = @mg_client.delete "#{domain}/tags/#{tag}"
+result = mg_client.delete "#{domain}/tags/#{tag}"
 ```
 ### Events:
 ____________________________________________________
 **Get Event: **
 
 ```ruby
-result = @mg_client.get "#{domain}/events", {:event => 'rejected'}
+result = mg_client.get "#{domain}/events", {:event => 'rejected'}
 ```
 
 ### Routes:
@@ -253,18 +253,18 @@ ____________________________________________________
 **Get List of Routes: **
 
 ```ruby
-result = @mg_client.get "routes", {:limit => 50, :skip => 10}
+result = mg_client.get "routes", {:limit => 50, :skip => 10}
 ```
 
 **Get a Single Route by ID: **
 
 ```ruby
-result = @mg_client.get "routes/#{route_id}"
+result = mg_client.get "routes/#{route_id}"
 ```
 **Create a Route: **
 
 ```ruby
-result = @mg_client.post "routes",  {:priority => 10,
+result = mg_client.post "routes",  {:priority => 10,
                                      :description => 'This is a test route',
                                      :expression => 'match_recipient(".*@gmail.com")',
                                      :action => 'forward("alice@example.com")'}
@@ -272,7 +272,7 @@ result = @mg_client.post "routes",  {:priority => 10,
 **Update a Route: **
 
 ```ruby
-result = @mg_client.put "routes/#{route_id}",  {:priority => 10,
+result = mg_client.put "routes/#{route_id}",  {:priority => 10,
                                                 :description => 'This is a test route',
                                                 :expression => 'match_recipient(".*@gmail.com")',
                                                 :action => 'forward("alice@example.com")'}
@@ -280,46 +280,46 @@ result = @mg_client.put "routes/#{route_id}",  {:priority => 10,
 **Remove a Route: **
 
 ```ruby
-result = @mg_client.delete "routes/#{route_id}"
+result = mg_client.delete "routes/#{route_id}"
 ```
 ### Campaigns:
 ____________________________________________________
 **Get List of Campaigns: **
 
 ```ruby
-result = @mg_client.get "#{domain}/campaigns", {:limit => 50, :skip => 10}
+result = mg_client.get "#{domain}/campaigns", {:limit => 50, :skip => 10}
 ```
 
 **Get a Single Campaign: **
 
 ```ruby
-result = @mg_client.get "#{domain}/campaigns/#{campaign_id}"
+result = mg_client.get "#{domain}/campaigns/#{campaign_id}"
 ```
 
 **Create a Campaign: **
 
 ```ruby
-result = @mg_client.post "#{domain}/campaigns", {:name => 'My Campaign',
+result = mg_client.post "#{domain}/campaigns", {:name => 'My Campaign',
                                                  :id => 'campaign_123_2014'}
 ```
 
 **Update a Campaign: **
 
 ```ruby
-result = @mg_client.put "#{domain}/campaigns/#{campaign_id}", {:name => 'My Campaign',
+result = mg_client.put "#{domain}/campaigns/#{campaign_id}", {:name => 'My Campaign',
                                                                :id => 'campaign_123_2014'}
 ```
 
 **Remove a Campaign: **
 
 ```ruby
-result = @mg_client.delete "#{domain}/campaigns/#{campaign_id}"
+result = mg_client.delete "#{domain}/campaigns/#{campaign_id}"
 ```
 
 **Get Campaign Events: **
 
 ```ruby
-result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/events", {:event => 'clicked',
+result = mg_client.get "#{domain}/campaigns/#{campaign_id}/events", {:event => 'clicked',
                                                                       :recipient => 'test@example.com',
                                                                       :country => 'US',
                                                                       :region => 'TX',
@@ -331,13 +331,13 @@ result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/events", {:event =>
 **Get a Single Campaign's Stats: **
 
 ```ruby
-result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/stats", {:groupby => 'domain'}
+result = mg_client.get "#{domain}/campaigns/#{campaign_id}/stats", {:groupby => 'domain'}
 ```
 
 **Get a Single Campaign's Click Stats: **
 
 ```ruby
-result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/clicks", {:groupby => 'hour',
+result = mg_client.get "#{domain}/campaigns/#{campaign_id}/clicks", {:groupby => 'hour',
                                                                       :country => 'US',
                                                                       :region => 'TX',
                                                                       :city => 'Austin',
@@ -349,7 +349,7 @@ result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/clicks", {:groupby =
 **Get a Single Campaign's Click Opens: **
 
 ```ruby
-result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/opens", {:groupby => 'hour',
+result = mg_client.get "#{domain}/campaigns/#{campaign_id}/opens", {:groupby => 'hour',
                                                                      :country => 'US',
                                                                      :region => 'TX',
                                                                      :city => 'Austin',
@@ -361,7 +361,7 @@ result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/opens", {:groupby =>
 **Get a Single Campaign's Click Unsubscribes: **
 
 ```ruby
-result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/unsubscribes", {:groupby => 'hour',
+result = mg_client.get "#{domain}/campaigns/#{campaign_id}/unsubscribes", {:groupby => 'hour',
                                                                             :country => 'US',
                                                                             :region => 'TX',
                                                                             :city => 'Austin',
@@ -373,7 +373,7 @@ result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/unsubscribes", {:gro
 **Get a Single Campaign's Click Complaints: **
 
 ```ruby
-result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/complaints", {:groupby => 'hour',
+result = mg_client.get "#{domain}/campaigns/#{campaign_id}/complaints", {:groupby => 'hour',
                                                                           :limit => 100,
                                                                           :page => 1,
                                                                           :count => true}
@@ -385,33 +385,33 @@ ____________________________________________________
 **Get List of Webhooks: **
 
 ```ruby
-result = @mg_client.get "domains/#{domain}/webhooks"
+result = mg_client.get "domains/#{domain}/webhooks"
 ```
 
 **Get a Webhook Properties: **
 
 ```ruby
-result = @mg_client.get "domains/#{domain}/webhooks/#{webhook_id}"
+result = mg_client.get "domains/#{domain}/webhooks/#{webhook_id}"
 ```
 
 **Create a Webhook: **
 
 ```ruby
-result = @mg_client.post "domains/#{domain}/webhooks", {:id => 'bounce',
+result = mg_client.post "domains/#{domain}/webhooks", {:id => 'bounce',
                                                         :url => 'http://example.com/mailgun/events/bounce'}
 ```
 
 **Update a Webhook: **
 
 ```ruby
-result = @mg_client.put "domains/#{domain}/webhooks/#{webhook_id}", {:id => 'bounce',
+result = mg_client.put "domains/#{domain}/webhooks/#{webhook_id}", {:id => 'bounce',
                                                                      :url => 'http://example.com/mailgun/events/bounce'}
 ```
 
 **Remove a Webhook: **
 
 ```ruby
-result = @mg_client.delete "domains/#{domain}/webhooks/#{webhook_id}"
+result = mg_client.delete "domains/#{domain}/webhooks/#{webhook_id}"
 ```
 
 ### Mailing Lists:
@@ -420,19 +420,19 @@ ____________________________________________________
 **Get list of Lists: **
 
 ```ruby
-result = @mg_client.get "lists"
+result = mg_client.get "lists"
 ```
 
 **Get List Properties: **
 
 ```ruby
-result = @mg_client.get "lists/#{list_address}"
+result = mg_client.get "lists/#{list_address}"
 ```
 
 **Create a List: **
 
 ```ruby
-result = @mg_client.post "lists", {:address => 'dev.group@samples.mailgun.org',
+result = mg_client.post "lists", {:address => 'dev.group@samples.mailgun.org',
                                    :name => 'Development Group List',
                                    :description => 'List of all developers.',
                                    :access_level => 'members'}
@@ -441,7 +441,7 @@ result = @mg_client.post "lists", {:address => 'dev.group@samples.mailgun.org',
 **Update a List: **
 
 ```ruby
-result = @mg_client.put "lists/#{list_address}", {:address => 'dev.group@samples.mailgun.org',
+result = mg_client.put "lists/#{list_address}", {:address => 'dev.group@samples.mailgun.org',
                                                   :name => 'Development Group List',
                                                   :description => 'List of all developers.',
                                                   :access_level => 'members'}
@@ -450,25 +450,25 @@ result = @mg_client.put "lists/#{list_address}", {:address => 'dev.group@samples
 **Remove a List: **
 
 ```ruby
-result = @mg_client.delete "lists/#{list_address}"
+result = mg_client.delete "lists/#{list_address}"
 ```
 
 **Get List Members: **
 
 ```ruby
-result = @mg_client.get "lists/#{list_address}/members"
+result = mg_client.get "lists/#{list_address}/members"
 ```
 
 **Get List Member Properties: **
 
 ```ruby
-result = @mg_client.get "lists/#{list_address}/members/#{member_address}"
+result = mg_client.get "lists/#{list_address}/members/#{member_address}"
 ```
 
 **Add Member to List: **
 
 ```ruby
-result = @mg_client.post "lists/#{list_address}/members/#{member_address}", {:address => 'jane@samples.mailgun.org',
+result = mg_client.post "lists/#{list_address}/members/#{member_address}", {:address => 'jane@samples.mailgun.org',
                                                                              :name => 'Jane Doe',
                                                                              :vars => '{"first": "Jane", "last": "Doe"}',
                                                                              :subscribed => true,
@@ -478,7 +478,7 @@ result = @mg_client.post "lists/#{list_address}/members/#{member_address}", {:ad
 **Update Member on List: **
 
 ```ruby
-result = @mg_client.put "lists/#{list_address}/members/#{member_address}", {:address => 'jane@samples.mailgun.org',
+result = mg_client.put "lists/#{list_address}/members/#{member_address}", {:address => 'jane@samples.mailgun.org',
                                                                              :name => 'Jane Doe',
                                                                              :vars => '{"first": "Jane", "last": "Doe"}',
                                                                              :subscribed => true}
@@ -487,13 +487,13 @@ result = @mg_client.put "lists/#{list_address}/members/#{member_address}", {:add
 **Delete a Member from List: **
 
 ```ruby
-result = @mg_client.delete "lists/#{list_address}/members/#{member_address}"
+result = mg_client.delete "lists/#{list_address}/members/#{member_address}"
 ```
 
 **Get Stats for List: **
 
 ```ruby
-result = @mg_client.get "lists/#{list_address}/stats"
+result = mg_client.get "lists/#{list_address}/stats"
 ```
 
 ### Email Validation:
@@ -501,14 +501,7 @@ ____________________________________________________
 **Validate Single Address: **
 
 ```ruby
-result = @mg_client.get "address/validate", {:address => 'test@example.com'}
-```
-
-**Parse Addresses: **
-
-```ruby
-result = @mg_client.get "address/parse", {:addresses => 'test@example.com, "First Last <first.last@example.com>',
-                                          :syntax_only => true}
+result = mg_client.get "address/validate", {:address => 'test@example.com'}
 ```
 
 

data/docs/railgun/Templates.md

@@ -0,0 +1,92 @@
+Mailgun - Templates
+====================
+
+This is the Mailgun Ruby *Templates* 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.
+
+Usage - Templates
+-----------------------
+
+**Build a message with a template:**
+
+```ruby
+mb_obj = Mailgun::MessageBuilder.new
+
+mb_obj.from("sender@example.com")
+mb_obj.add_recipient("to", "recipient@example.com")
+mb_obj.subject ("This is the subject!")
+message.template('example.template.name')
+message.template_version('example.tag')
+
+mg_client.send_message "sending_domain.com", mb_obj
+```
+
+**Rails Example. Build a message with a template:**
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome_email
+    message = mail(
+    	from: "sender@example.com",
+    	to: "recipient@example.com",
+    	subject: "This is the subject!",
+    	template: 'example.template.name'
+    ) do |format|
+      format.text { render plain: "Test!" }
+    end
+    message.tap do |message|
+      message.mailgun_template_variables ||= {
+       'version' => 'example.tag'
+      }
+    end
+  end
+end
+```
+
+Template Handlebars
+-------------------------
+
+```
+{{#if english}}
+<p>This text is in the English language.</p>
+{{else if spanish}}
+<p>Este texto está en idioma español.</p>
+{{else if french}}
+<p>Ce texte est en langue française.</p>
+{{/if}}
+```
+
+In order to send the spanish version, for example:
+
+```ruby
+message.variable('spanish', 'true')
+```
+
+Also, Rails example:
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome_email
+    message = mail(
+    	from: "sender@example.com",
+    	to: "recipient@example.com",
+    	subject: "This is the subject!",
+    	template: 'example.template.name'
+    ) do |format|
+      format.text { render plain: "Test!" }
+    end
+    message.tap do |message|
+      message.mailgun_variables ||= {
+       'spanish' => 'true'
+      }
+    end
+  end
+end
+```
+
+More Documentation
+------------------
+See the official [Mailgun Templates Docs](https://documentation.mailgun.com/en/latest/api-templates.html)
+for more information

data/lib/mailgun/address.rb

@@ -4,45 +4,20 @@ 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)
+    def initialize
+      @client = Mailgun::Client.new(Mailgun.api_key, Mailgun.api_host || 'api.mailgun.net', 'v4')
     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 = {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