mailjet 0.0.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d0e2c12ab0cc6237b42bd1d380226a9c34129ea8
-  data.tar.gz: 89d3e6c6d4d64cfa2a07b3e2d336ac0ce65dfae3
+  metadata.gz: 156203494ae9dd313d17567b8a512d76d69c702f
+  data.tar.gz: e6abc5b3be30813cd8ba595269ffca54d046f8ac
 SHA512:
-  metadata.gz: 803e5a56bf4c2cb174c49af87e6c2ba6a8376613c186dfe01153c62956f027029b82773eaf5c5acbf0f0dbd29920dc61bade288820aeebde184adf53a3e35dd7
-  data.tar.gz: 5ef130cf9c095200c80a8e6adc91934932beb0d675b343aa1bf6c7b72fdb363e248c809f9f55bb3134664f1d8b8707e820b19227cade2122c38b8d46fd73e7d4
+  metadata.gz: 8ef83c13a06ab4abcdc1cad0bab70c8825fca208c6f69c2cb26198607cdd623aff145edb3bb002df65aad36955c2fda3093027787cb671e373df2488c8f9ef86
+  data.tar.gz: 1394da23d224428d2c3def93b3e6ae4a960bbfb74377c164f3cf2bbb31c442981b0d3282dde237737c97052c5de190ca9e02eafc334da06a21bee5f0b383b442

data/README.md

@@ -16,26 +16,34 @@
 [mailjet]: http://www.mailjet.com
 [rubinius]: http://rubini.us/
 [ree]: http://www.rubyenterpriseedition.com/
-[jruby]:http://jruby.org/
-[mailjetter]:https://github.com/holinnn/mailjetter/
+[jruby]: http://jruby.org/
+[mailjetter]: https://github.com/holinnn/mailjetter/
+[activeresource]: https://github.com/rails/activeresource
+[apidoc]: http://dev.mailjet.com/guides
+[apidoc-recipient]: http://mjdemo.poxx.net/~shubham/listrecipient.html?utm_source=github&utm_medium=link&utm_content=readme&utm_campaign=mailjet-gem
+[camelcase-api]: http://api.rubyonrails.org/classes/String.html#method-i-camelcase
+[underscore-api]: http://api.rubyonrails.org/classes/String.html#method-i-underscore
+[actionmailerdoc]: http://guides.rubyonrails.org/action_mailer_basics.html#sending-emails-with-dynamic-delivery-options
+[send-api-doc]: http://dev.mailjet.com/guides/send-api-guide/
+[v1-branch]: https://github.com/mailjet/mailjet-gem/tree/v1
 
 <!-- You can read this readme file in other languages:
 english | [french](./README.fr.md) -->
 
 This gem helps you to:
 
-* Send transactional emails through Mailjet API in Rails 3
-* Manage your lists, contacts and campaigns
+* Send transactional emails through Mailjet API in Rails 3/4
+* Manage your lists, contacts and campaigns, and much more...
 * Track email delivery through event API
 
 Compatibility:
 
- - Ruby 1.8.7
  - Ruby 1.9.X
- - [jRuby][jruby]
- - [Rubinius][rubinius]
+ - Ruby 2.0.0
 
-Rails ActionMailer integration designed for Rails 3.X
+Rails ActionMailer integration designed for Rails 3.X and 4.X
+
+IMPORTANT: Mailjet gem switched to API v3, the new API provided by Mailjet. For the wrapper for API v1, check the [v1 branch][v1-branch].
 
 ## Install
 
@@ -88,310 +96,124 @@ As easy as:
 
 ```ruby
 # application.rb
-config.action_mailer.delivery_method = :mailjet
-
-```
-
-## Manage your campaigns
-
-### Contacts
-
-#### Filter your contacts
-
-```ruby
-> contacts = Mailjet::Contact.all(status: 'active', start: 100, limit: 2)
-=> [#<Mailjet::Contact>, #<Mailjet::Contact>]
-> contacts = Mailjet::Contact.all(openers: true, start: 100, limit: 2)
-=> [#<Mailjet::Contact>, #<Mailjet::Contact>]
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/contact/list*
-*All parameters and attributes for the openers option at https://eu.mailjet.com/docs/api/contact/openers*
-
-#### More info about your contacts
+config.action_mailer.delivery_method = :mailjet_smtp
 
-```ruby
-> contacts[0].infos
-=> {blocked: 12, click: 1, email: 'test@mailjet.com'}
 ```
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/contact/infos*
-
-### Lists
-
-#### Create a new list
-
-```ruby
-> list = Mailjet::List.create(label: 'My Mailjet list', name: "mymailjetlist")
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/lists/create*
-
-#### List your lists
-
-```ruby
-> Mailjet::List.all(limit: 10, start: 0, orderby: 'id ASC')
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/lists/all*
-
-#### Update a list
-
-```ruby
-> list = Mailjet::List.all.find{|l| l.name == 'mymailjetlist' }
-> list = list.update(label: 'My updated Mailjet list', name: "myupdatedmailjetlist")
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/lists/update*
-
-#### Show all contacts within a list
-
-```ruby
-> list.contacts
-=> [#<Mailjet::Contact>, #<Mailjet::Contact>]
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/lists/contacts*
-
-#### Add contacts to your list
-
-```ruby
-> list.add_contacts("test@mailjet.com", "test2@mailjet.com", force: true  )
-=> OK
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/lists/addmanycontacts*
-
-#### Unsubscribe contact from a list
-
-```ruby
-> list.unsubscribe_contact("test@mailjet.com")
-=> OK
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/lists/unsubcontact*
-
-#### Remove contacts from a list
-
-```ruby
-> list.remove_contacts("test@mailjet.com", "test2@mailjet.com")
-=> OK
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/lists/removemanycontacts*
-
-#### Direct list email
-
-```ruby
-> list.email
-=> "jk324jlO3N32203@lists.mailjet.com"
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/lists/email*
-
-
-#### Get statistics
-
-```ruby
-> list.statistics
-=> {active: 20, bounce: 1, click: 14, created_at: "2012-02-02 21:59:59", ...}
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/lists/statistics*
-
-#### Delete a list
+Or if you prefer sending messages through mailjet REST API:
 
 ```ruby
-> list.delete
-=> OK
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/lists/delete*
-
-### Campaigns
-
-#### Create a new campaign:
-
-```ruby
-> campaign = Mailjet::Campaign.create(title: "My Mailjet Campaign", list_id: Mailjet::List.all.first.id, from: "mailjet-registered-email@domain.com", from_name: "Sender Name", subject: "Our new product", lang: "en", footer: "default")
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/createcampaign*
-
-#### List your campaigns:
-
-```ruby
-> campaigns = Mailjet::Campaign.all(start: 10, limit: 20)
-=> [#<Mailjet::Campaign>, #<Mailjet::Campaign>, ...]
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/campaigns*
-
-#### Find one campaign:
-
-```ruby
-> campaigns = Mailjet::Campaign.find(19)
-=> #<Mailjet::Campaign>
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/campaigns*
-
-#### Update your campaign:
-
-```ruby
-> campaign.update(title: "My *new* Mailjet Campaign")
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/updatecampaign*
-
-#### Get all the subscribers to your campaign:
-
-```ruby
-> campaign.contacts(limit: 2, start: 0, status: 'queued')
-=> [#<Mailjet::Contact id: 123, email: 'test@mailjet.com', sent_at: "2012-02-02 21:59:59", status: 'queued'>, #<Mailjet::Contact id: 456, email: 'test2@mailjet.com', sent_at: "2012-02-02 23:13:02", status: 'queued'>]
+# application.rb
+config.action_mailer.delivery_method = :mailjet_api
 ```
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/contacts*
+You can use mailjet specific options with `delivery_method_options` as detailed in the official [ActionMailer doc][actionmailerdoc]
 
-#### Send the campaign the associated contacts:
+## Manage your campaigns
 
-```ruby
-> campaign.send!
-=> OK
-```
+This gem provide a convenient wrapper for consuming the mailjet API. The wrapper is highly inspired by [ActiveResource][activeresource] even though it does not depend on it.
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/sendcampaign*
+You can find out all the resources you can access to in the [Official API docs][apidocs].
 
-#### Send a test email to specified email address:
+Let's have a look at the power of this thin wrapper
 
-```ruby
-> campaign.test('test@mailjet.com')
-=> OK # response status
-```
+### Wrapper REST API
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/testcampaign*
+Let's say we want to manage list recipients.
 
-#### Get statistics:
+#### GET all the recipients in one query:
 
 ```ruby
-> campaign.statistics
-=> { total: 200, bounce: 1, bounce_pct: 0.5, click: 10, click_pct: 5, open: 20, open_pct: 10, sent: 200, sent_pct: 100, spam: 1, spam_pct: 0.5, total: 200 }
+> recipients = Mailjet::Listrecipient.all(limit: 0)
+=> [#<Mailjet::Listrecipient>, #<Mailjet::Listrecipient>]
 ```
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/statistics*
+By default, `.all` will retrieve only 10 resources, so, you have to specify `limit: 0` if you want to GET them all.
 
-#### Template categories:
+You can refine queries using [API Filters][apidoc-recipient]`*` as well as the following parameters:
 
-```ruby
-> Mailjet::TemplateCategory.all
-=> [#<Mailjet::TemplateCategory id: 2, label: "basic", value: "Basic">, #<Mailjet::TemplateCategory id: 6, label: "design", value: "Design">]
-```
+* format: `:json, :xml, :rawxml, :html, :csv` or `:phpserialized` (default: `:json`)
+* limit: int (default: 10)
+* offset: int (default: 0)
+* sort: `[[:property, :asc], [:property, :desc]]`
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/tplcategories*
+`*` See below for [naming conventions](#naming-conventions)
 
-#### Template models:
+#### GET the resources count
 
 ```ruby
-> Mailjet::TemplateModel.all(category: 2, custom: true, locale: 'fr_FR')
-=> [<#Mailjet::TemplateModel id: 4, name: "Text", header_link: "http:\/\/" ... ]
+> Mailjet::Listrecipient.count
+=> 83
 ```
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/tplmodels*
-
-#### Get the raw HTML form a campaign:
+#### GET the first resource matching a query
 
 ```ruby
-> campaign.html
-=> "<html><head></head><body>Test</body></html>"
+> Mailjet::Listrecipient.first
+=> #<Mailjet::Listrecipient>
 ```
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/htmlcampaign*
-
-#### Set the raw HTML for a campaign:
+#### GET a resource from its id
 
 ```ruby
-> campaign.set_html("<html><head><title>Test</title></head><body>Test <a href=\"[[UNSUB_LINK_EN]]\">[[UNSUB_LINK_EN]]</a></body></html>")
-=> OK # response status
+> recipient = Mailjet::Listrecipient.find(id)
+=> #<Mailjet::Listrecipient>
 ```
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/sethtmlcampaign*
-
-#### Duplicate a campaign:
+#### Updating a resource
 
 ```ruby
-> new_campaign = campaign.duplicate(title: "Another Mailjet Campaign")
-=> #<Mailjet::Campaign title: "Another Mailjet Campaign" ... >
+> recipient = Mailjet::Listrecipient.first
+=> #<Mailjet::Listrecipient>
+> recipient.is_active = false
+=> false
+> recipient.attributes
+=> {...} # attributes hash
+> recipient.save
+=> true
+> recipient.update_attributes(is_active: true)
+=> true
 ```
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/message/duplicatecampaign*
+#### Deleting a resource
+ ```ruby
+> recipient = Mailjet::Listrecipient.first
+=> #<Mailjet::Listrecipient>
+> recipient.delete
+> Mailjet::Listrecipient.delete(123)
+=> #<Mailjet::Listrecipient>
+ ```
 
-### Reporting
+### Naming conventions
 
-#### Get the list of all your clicks
+* Classes names are the [camelcased][camelcase-api] version of resource names (e.g. class name for `listrecipient` resource will be `Listrecipient` - notice the "r" of "recipient" is downcase since the "listrecipient" resource has no dash or underscore between "list" and "recipient")
+* Ruby attribute names are the [underscored][underscore-api] versions of API attributes names (e.g. `IsActive` will be `is_active` in ruby)
+* If you do not like the name of the resource, you can easily rename them. For instance, if you want a capital R to ListRecipient, you can define the following class:
 
 ```ruby
-> clicks = Mailjet::Reporting.clicks(from: "test@domain.com")
-=> [<#Mailjet::Click id: 4, click_delay: 1234, date: "2012-02-08", link: "", user_agent: "Mozilla/5.0 (Windows NT 5.1; rv:5.0) Gecko/20100101 Firefox/5.0"} ]
-> clicks.first.contact
-=> #<Mailjet::Contact id: 123, email: "test@mailjet.com">
-```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/report/click*
-
-#### Info about domains your emails are sent to
-
-```ruby
-> Mailjet::Reporting.domains(start: 3, limit: 6)
-=> [{bounce_rate: 0.1, clicked_rate: 0.2, ...}, {bounce_rate: 0.8, clicked_rate: 0.1, ...}]
+class ListRecipient
+  include Mailjet::Resource
+  self.resource_path = 'listrecipient'
+  self.public_operations = [:get, :put, :post, :delete] # optional
+end
 ```
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/report/domain*
+## Send emails through API
 
-#### Clients used to open emails
+In order to send emails through the API, you just have to `create` a new `MessageDelivery` resource.
 
-```ruby
-> Mailjet::Reporting.clients(start: 3, limit: 6)
-=> [{client: "Gmail", open_rate: 0.1, platform: "Windows", ...}, {client: "Outlook", open_rate: 0.3, platform: "Windows", ...}]
 ```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/report/emailclients*
-
-#### Info about email sent
-
-```ruby
-> Mailjet::Reporting.emails(from_domain: "domain.com", limit: 10)
-=> [#<Mailjet::Email>, #<Mailjet::Email>, #<Mailjet::Email>, ...]
+Mailjet::MessageDelivery.create(from: "me@example.com", to: "you@example.com", subject: "Mailjet is awesome", text: "Yes, it is!")
 ```
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/report/emailsent*
-
-#### Global stats about a set of emails
-
-```ruby
-> Mailjet::Reporting.statistics(from_domain: "domain.com", limit: 10)
-=> { avg_clicked_delay: 123, avg_opened_rate: 0.432, blocked: 13, ...}
+If you want to send it to multiple recipients, just use an array:
 ```
-
-*All parameters and attributes at https://eu.mailjet.com/docs/api/report/emailstatistics*
-
-
-#### Opened email Geolocation
-
-```ruby
-> Mailjet::Reporting.geolocation(from_domain: "domain.com", limit: 10)
-=> [{click: 123, country: "France", open: 234}, {click: 9876, country: "US", open: 12345}]
+Mailjet::MessageDelivery.create(from: "me@example.com", to: ["you@example.com", "someone-else@example.com"], subject: "Mailjet is awesome", text: "Yes, it is!")
 ```
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/report/geoip*
-
-#### User-Agents used to open emails
-
-```ruby
-> Mailjet::Reporting.agents(start: 3, limit: 6)
-=> [{cnt_clicked: 123, part: 30, platform: "Windows", user_agent: "Mozilla/5.0 (Windows NT 5.1; rv:5.0) Gecko/20100101 Firefox/5.0"}, ...]
-```
+In order to Mailjet modifiers, you cannot use the regular form of Ruby 2 hashes. Instead, use a String `e.g.: 'mj-prio' => 2` or a quoted symbol `e.g.: 'mj-prio' => 2`.
 
-*All parameters and attributes at https://eu.mailjet.com/docs/api/report/useragents*
+You can check available params in the [official doc][send-api-doc].
 
 ## Track email delivery
 

data/Rakefile

@@ -5,12 +5,13 @@ Bundler::GemHelper.install_tasks
 
 $:.push File.expand_path("../lib", __FILE__)
 
-Rake::TestTask.new(:test) do |t|
+Rake::TestTask.new(:spec) do |t|
   t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
+  t.libs << 'spec'
+  # t.pattern = 'spec/**/*_spec.rb'
   t.verbose = true
+  t.test_files = Dir['spec/**/*_spec.rb']
 end
 
 
-task :default => :test
+task :default => :spec

data/lib/mailjet.rb

@@ -1,19 +1,15 @@
 require 'active_support'
 require 'ostruct'
 require 'mailjet/core_extensions/ostruct'
-require 'mailjet/api'
-require 'mailjet/api_request'
-require 'mailjet/api_error'
 require 'mailjet/configuration'
-require 'mailjet/contact'
-require 'mailjet/list'
-require 'mailjet/campaign'
-require 'mailjet/template_category'
-require 'mailjet/template_model'
-require 'mailjet/reporting'
-require 'mailjet/click'
-require 'mailjet/email'
+require 'mailjet/api_error'
 
+require 'mailjet/resource'
+require 'mailjet/message_delivery'
+
+Dir[File.expand_path("../mailjet/resources/*.rb", __FILE__)].each do |file|
+  require file
+end
 
 module Mailjet
   def self.configure