dotmailer 0.0.3 → 0.0.4

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    M2EzOWYzMzZiMTc2YzVmODA2ZTBiYmEzNmJhODFmMDRlNzMyMWY3OQ==
-  data.tar.gz: !binary |-
-    YjAzMmNlZTdlZDY0NDJkYjA2Njk4YjBkYWQ5MDY0OWM0MGYyZDg0Zg==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    ODAxZjliNTc4MmFjZTE4ZDg0ZmZlYTM0NmIxYjQ4ZTI4ZWVhOWI0YjNiNGE5
-    MzZiNGU3OTY0ZjkwY2M0NDQzN2RlODA1NGU1NDdhNWNjOTBiYzVhMmQ2MDZi
-    MmQxZmI5YzFjMDlkNGU4NTM2NjFlMzU1MzkyZDdhZGFmZjNlNTE=
-  data.tar.gz: !binary |-
-    NWZiOTcxNmQ4ZDgyNjJhOGExMzFjMTFjNmEwMTExOTZjZTc4NDUxZmVlODYz
-    ZTA5ZDk2Y2FmMzBlZjk3MDY5ZDQ5MGZiYmYzZGNmNmQ2ODg5ZjllYmIzOGZm
-    NjRmZTZiNzc1NmI5Mjc5NjE2YzM1Nzg2YjNmNzJkM2ViYTMwMjg=
+SHA1:
+  metadata.gz: 9c297ddc3dfc6b1e75f6cf9620cda8d2215699b3
+  data.tar.gz: 822f8f022616b4e52bfda533e268d61ab677d7fe
+SHA512:
+  metadata.gz: 499bedb96622c4b193300b9045f34cae23d22c6bbd3d461ed1b0e27aff1cd715315c76581ccc08aa3a798545ca43c8120b78256839811ffd16527fe89bba43f9
+  data.tar.gz: 14294fe5fa456b21e3fc6aba390d43088cf89588b7c089a0ee813f3c684091abd56e4ef949e49bf7d47e194f5ebb2c7ea2489030d7141654fc71f61b0c776328

data/.gitignore

@@ -1,4 +1,3 @@
 *.gem
 .bundle
-Gemfile.lock
 pkg/*

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p247

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 1.9.3
+
+script: bundle exec rspec

data/Gemfile.lock

@@ -0,0 +1,58 @@
+PATH
+  remote: .
+  specs:
+    dotmailer (0.0.4)
+      activesupport
+      rest-client
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (4.0.1)
+      i18n (~> 0.6, >= 0.6.4)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    addressable (2.3.5)
+    atomic (1.1.14)
+    coderay (1.0.9)
+    crack (0.4.1)
+      safe_yaml (~> 0.9.0)
+    diff-lcs (1.2.4)
+    i18n (0.6.5)
+    method_source (0.8.2)
+    mime-types (2.0)
+    minitest (4.7.5)
+    multi_json (1.8.2)
+    pry (0.9.12.2)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.3)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+    safe_yaml (0.9.7)
+    slop (3.4.6)
+    thread_safe (0.1.3)
+      atomic
+    tzinfo (0.3.38)
+    webmock (1.15.2)
+      addressable (>= 2.2.7)
+      crack (>= 0.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  dotmailer!
+  pry
+  rspec
+  webmock

data/README.md

@@ -1,4 +1,4 @@
-dotMailer
+dotMailer [![Build Status](https://travis-ci.org/econsultancy/dotmailer.png?branch=master)](https://travis-ci.org/econsultancy/dotmailer) [![Gem Version](https://badge.fury.io/rb/dotmailer.png)](http://badge.fury.io/rb/dotmailer)
 =========
 
 [dotMailer](http://www.dotmailer.co.uk/) provide both a REST and SOAP API for interacting with their system. The REST API supports both XML and JSON payloads.
@@ -138,18 +138,31 @@ Then, once the contact has gone through the resubscribe process and been redirec
     contact.subscribed?
     => true
 
+### Deleting a contact
+
+Contacts can be deleted by calling `DotMailer::Contact#delete`:
+
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
+
+    contact = account.find_contact_by_email 'john@example.com'
+    => DotMailer::Contact id: 12345, email: john@example.com, email_type: Html
+
+    contact.delete
+
 ### Bulk Import
 
 `DotMailer::Account#import_contacts` will start a batch import of contacts into the global address book, and return a `DotMailer::ContactImport` object which has a `status`:
 
     account = DotMailer::Account.new('your-api-username', 'your-api-password')
 
-    import = account.import_contacts [
+    contacts = [
       { 'Email' => 'joe@example.com' },
       { 'Email' => 'sue@example.com' },
       { 'Email' => 'bob@example.com' },
       { 'Email' => 'invalid@email'   }
     ]
+
+    import = account.import_contacts contacts
     => DotMailer::ContactImport contacts: [{"Email"=>"joe@example.com" }, {"Email"=>"sue@example.com" }, {"Email"=>"bob@example.com"}]
 
     import.finished?
@@ -157,6 +170,18 @@ Then, once the contact has gone through the resubscribe process and been redirec
     import.status
     => "NotFinished"
 
+
+The call can also block for you and will wait until the import is finished :
+
+    import = account.import_contacts contacts, wait_for_finish: true
+
+    # it will block here until finished is true
+    # if the import takes longer than 385 seconds then it will raise `DotMailer::ImportNotFinished`
+
+    import.finished?
+    => true
+
+
 Then, once the import has finished, you can query the status and get any errors (as a CSV::Table object):
 
     import.finished?
@@ -200,3 +225,51 @@ To fetch these suppressions, pass a Time object to `DotMailer::Account#find_supp
 
     suppressions.first.contact
     => DotMailer::Contact id: 12345, email: john@example.com
+
+Campaigns
+---------
+
+### From addresses
+
+Campaigns can only be sent with a from address which has been set up in dotMailer (see [here](https://support.dotmailer.com/entries/20653397-How-do-I-create-a-custom-from-address-or-additional-alias-)).
+
+To access this list of from addresses, call `DotMailer::Account#from_addresses`:
+
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
+
+    account.from_addresses
+    => [
+         DotMailer::FromAddress id: 123 email: info@example.com,
+         DotMailer::FromAddress id: 456 email: no-reply@example.com
+       ]
+
+### Creating Campaigns
+
+To create a dotMailer campaign, call `DotMailer::Account#create_campaign` with a hash containing the following required keys:
+
+* `:name`               - The name of the campaign as it will appear in the web interface
+* `:subject`            - The subject to use when sending the campaign
+* `:from_name`          - The name which will appear in the "From" header of the sent campaign
+* `:from_email`         - The email which will appear in the "From" header of the sent campaign (this must be a valid from address in the dotMailer system, see "From addresses" above)
+* `:html_content`       - The content which will be included in the HTML part of the sent campaign
+* `:plain_text_content` - The content which will be included in the Plain Text part of the sent campaign
+
+For example:
+
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
+
+    campaign = account.create_campaign(
+      :name                => 'my_campaign',
+      :subject             => 'My Campaign',
+      :from_name           => 'Me',
+      :from_email          => 'me@example.com',
+      :html_content        => '<h1>Hello!</h1><a href="http://$UNSUB$">Unsubscribe</a>',
+      :plain_text_content  => "Hello!\n======\nhttp://$UNSUB$"
+    )
+    => DotMailer::Campaign id: 123, name: my_campaign
+
+    campaign.subject
+    => "My Campaign"
+
+    campaign.from_address
+    => DotMailer::FromAddress id: 345, email: 'me@example.com'

data/Rakefile

@@ -1 +1,10 @@
 require "bundler/gem_tasks"
+
+desc "Load the gem into an irb console"
+task :console do
+  require 'irb'
+  ARGV.clear
+  ARGV.push("-Ilib")
+  ARGV.push("-rdotmailer")
+  IRB.start
+end

data/dotmailer.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'webmock'
+  s.add_development_dependency 'pry'
 end

data/lib/dot_mailer.rb

@@ -3,9 +3,14 @@ require 'dot_mailer/data_field'
 require 'dot_mailer/contact_import'
 require 'dot_mailer/contact'
 require 'dot_mailer/suppression'
+require 'dot_mailer/from_address'
+require 'dot_mailer/campaign'
 require 'dot_mailer/account'
 require 'dot_mailer/client'
+require 'dot_mailer/segment'
+require 'dot_mailer/campaign_summary'
 
 module DotMailer
-  SUBSCRIBED_STATUS = 'Subscribed'
+  SUBSCRIBED_STATUS          = 'Subscribed'
+  GLOBALLY_SUPPRESSED_STATUS = 'Globally Suppressed'
 end

data/lib/dot_mailer/account.rb

@@ -23,8 +23,8 @@ module DotMailer
       cache.delete 'data_fields'
     end
 
-    def import_contacts(contacts)
-      ContactImport.import self, contacts
+    def import_contacts(contacts, options = {})
+      ContactImport.import self, contacts, options[:wait_for_finish]
     end
 
     def find_contact_by_email(email)
@@ -47,6 +47,26 @@ module DotMailer
       client.post_json '/contacts/unsubscribe', 'Email' => email
     end
 
+    def from_addresses
+      response = cache.fetch 'from_addresses' do
+        client.get('/custom-from-addresses')
+      end
+
+      response.map { |a| FromAddress.new(a) }
+    end
+
+    def create_campaign(attributes)
+      Campaign.create(self, attributes)
+    end
+
+    def find_campaign_by_id(id)
+      Campaign.find_by_id(self, id)
+    end
+
+    def find_segment_by_id(id)
+      DotMailer::Segment.find_by_id(self, id)
+    end
+
     def to_s
       "#{self.class.name} client: #{client}"
     end

data/lib/dot_mailer/campaign.rb

@@ -0,0 +1,95 @@
+module DotMailer
+  class Campaign
+    def self.create(account, attributes)
+      params = {}
+
+      params['Name']             = attributes[:name]               || raise('missing :name')
+      params['Subject']          = attributes[:subject]            || raise('missing :subject')
+      params['FromName']         = attributes[:from_name]          || raise('missing :from_name')
+      params['HtmlContent']      = attributes[:html_content]       || raise('missing :html_content')
+      params['PlainTextContent'] = attributes[:plain_text_content] || raise('missing :plain_text_content')
+
+      raise 'missing :from_email' unless attributes[:from_email]
+
+      from_address = account.from_addresses.detect do |from_address|
+        from_address.email == attributes[:from_email]
+      end
+
+      raise InvalidFromAddress, attributes[:from_email] unless from_address.present?
+
+      params['FromAddress'] = from_address.to_hash
+
+      response = account.client.post_json('/campaigns', params)
+
+      new(account, response)
+    end
+
+    def self.find_by_id(account, id)
+      response = account.client.get "/campaigns/#{id}"
+
+      new(account, response)
+    end
+
+    def initialize(account, attributes)
+      self.account    = account
+      self.attributes = attributes
+    end
+
+    def id
+      attributes['id']
+    end
+
+    def name
+      attributes['name']
+    end
+
+    def from_name
+      attributes['fromName']
+    end
+
+    def from_address
+      FromAddress.new attributes['fromAddress']
+    end
+
+    def html_content
+      attributes['htmlContent']
+    end
+
+    def plain_text_content
+      attributes['plainTextContent']
+    end
+
+    def to_s
+      %{#{self.class.name} id: #{id}, name: #{name}}
+    end
+
+    def inspect
+      to_s
+    end
+
+    def send_to_contact_ids(contact_ids)
+      client.post_json '/campaigns/send', {
+        'campaignId' => id,
+        'contactIds' => contact_ids
+      }
+    end
+
+    def send_to_segment(segment)
+      client.post_json '/campaigns/send', {
+        'campaignId' => id,
+        'addressBookIds' => [segment.id]
+      }
+    end
+
+    def summary
+      DotMailer::CampaignSummary.new(account, id)
+    end
+
+    private
+    attr_accessor :attributes, :account
+
+    def client
+      account.client
+    end
+  end
+end

data/lib/dot_mailer/campaign_summary.rb

@@ -0,0 +1,77 @@
+module DotMailer
+  class CampaignSummary
+    %w(
+    numUniqueOpens
+    numUniqueTextOpens
+    numTotalUniqueOpens
+    numOpens
+    numTextOpens
+    numTotalOpens
+    numClicks
+    numTextClicks
+    numTotalClicks
+    numPageViews
+    numTotalPageViews
+    numTextPageViews
+    numForwards
+    numTextForwardsge
+    numEstimatedForwards
+    numTextEstimatedForwards
+    numTotalEstimatedForwards
+    numReplies
+    numTextReplies
+    numTotalReplies
+    numHardBounces
+    numTextHardBounces
+    numTotalHardBounces
+    numSoftBounces
+    numTextSoftBounces
+    numTotalSoftBounces
+    numUnsubscribes
+    numTextUnsubscribes
+    numTotalUnsubscribes
+    numIspComplaints
+    numTextIspComplaints
+    numTotalIspComplaints
+    numMailBlocks
+    numTextMailBlocks
+    numTotalMailBlocks
+    numSent
+    numTextSent
+    numTotalSent
+    numRecipientsClicked
+    numDelivered
+    numTextDelivered
+    numTotalDelivered
+    ).each do |meth|
+      define_method(meth.underscore) do
+        @params[meth].to_i
+      end
+    end
+
+    %w(
+    percentageDelivered
+    percentageUniqueOpens
+    percentageOpens
+    percentageUnsubscribes
+    percentageReplies
+    percentageHardBounces
+    percentageSoftBounces
+    percentageUsersClicked
+    percentageClicksToOpens
+    ).each do |meth|
+      define_method(meth.underscore) do
+        @params[meth].to_f
+      end
+    end
+
+    def date_sent
+      Time.parse(@params["dateSent"])
+    end
+
+    def initialize(account, id)
+      @params = account.client.get "/campaigns/#{id.to_s}/summary"
+    end
+  end
+end
+