createsend 0.0.1 → 0.0.2

data/lib/segment.rb

@@ -0,0 +1,83 @@
+require 'createsend'
+require 'json'
+
+# Represents a subscriber list segment and associated functionality.
+class Segment
+  attr_reader :segment_id
+
+  def initialize(segment_id)
+    @segment_id = segment_id
+  end
+
+  # Creates a new segment.
+  def self.create(list_id, title, rules)
+    options = { :body => {
+      :Title => title,
+      :Rules => rules }.to_json }
+    response = CreateSend.post "/segments/#{list_id}.json", options
+    response.parsed_response
+  end
+
+  # Updates this segment.
+  def update(title, rules)
+    options = { :body => {
+      :Title => title,
+      :Rules => rules }.to_json }
+    response = CreateSend.put "/segments/#{segment_id}.json", options
+  end
+
+  # Adds a rule to this segment.
+  def add_rule(subject, clauses)
+    options = { :body => {
+      :Subject => subject,
+      :Clauses => clauses }.to_json }
+    response = CreateSend.post "/segments/#{segment_id}/rules.json", options
+  end
+
+  # Gets the active subscribers in this segment.
+  def subscribers(date, page=1, page_size=1000, order_field="email", order_direction="asc")
+    options = { :query => {
+      :date => date,
+      :page => page,
+      :pagesize => page_size,
+      :orderfield => order_field,
+      :orderdirection => order_direction } }
+    response = get "active", options
+    Hashie::Mash.new(response)
+  end
+
+  # Gets the details of this segment
+  def details
+    response = CreateSend.get "/segments/#{segment_id}.json", {}
+    Hashie::Mash.new(response)
+  end
+
+  # Clears all rules of this segment.
+  def clear_rules
+    response = CreateSend.delete "/segments/#{segment_id}/rules.json", {}
+  end
+
+  # Deletes this segment.
+  def delete
+    response = CreateSend.delete "/segments/#{segment_id}.json", {}
+  end
+  
+  private
+
+  def get(action, options = {})
+    CreateSend.get uri_for(action), options
+  end
+
+  def post(action, options = {})
+    CreateSend.post uri_for(action), options
+  end
+
+  def put(action, options = {})
+    CreateSend.put uri_for(action), options
+  end
+
+  def uri_for(action)
+    "/segments/#{segment_id}/#{action}.json"
+  end
+
+end

data/lib/subscriber.rb

@@ -1,6 +1,7 @@
 require 'createsend'
 require 'json'
 
+# Represents a subscriber and associated functionality.
 class Subscriber
   attr_reader :list_id
   attr_reader :email_address
@@ -10,12 +11,14 @@ class Subscriber
     @email_address = email_address
   end
 
+  # Gets a subscriber by list ID and email address.
   def self.get(list_id, email_address)
     options = { :query => { :email => email_address } }
     response = CreateSend.get "/subscribers/#{list_id}.json", options
     Hashie::Mash.new(response)
   end
 
+  # Adds a subscriber to a subscriber list.
   def self.add(list_id, email_address, name, custom_fields, resubscribe)
     options = { :body => {
       :EmailAddress => email_address,
@@ -26,20 +29,35 @@ class Subscriber
     response.parsed_response
   end
 
+  # Imports subscribers into a subscriber list.
   def self.import(list_id, subscribers, resubscribe)
     options = { :body => {
       :Subscribers => subscribers,
       :Resubscribe => resubscribe }.to_json }
-    response = CreateSend.post "/subscribers/#{list_id}/import.json", options
+    begin
+      response = CreateSend.post "/subscribers/#{list_id}/import.json", options
+    rescue BadRequest => br
+      # Subscriber import will throw BadRequest if some subscribers are not imported
+      # successfully. If this occurs, we want to return the ResultData property of
+      # the BadRequest exception (which is of the same "form" as the response we'd 
+      # receive upon a completely successful import)
+      if br.data.ResultData
+        return br.data.ResultData
+      else
+        raise br
+      end
+    end
     Hashie::Mash.new(response)
   end
 
+  # Unsubscribes this subscriber from the associated list.
   def unsubscribe
     options = { :body => {
       :EmailAddress => @email_address }.to_json }
     CreateSend.post "/subscribers/#{@list_id}/unsubscribe.json", options
   end
 
+  # Gets the historical record of this subscriber's trackable actions.
   def history
     options = { :query => { :email => @email_address } }
     response = CreateSend.get "/subscribers/#{@list_id}/history.json", options

data/lib/template.rb

@@ -1,6 +1,7 @@
 require 'createsend'
 require 'json'
 
+# Represents an email template and associated functionality.
 class Template
   attr_reader :template_id
 
@@ -8,6 +9,7 @@ class Template
     @template_id = template_id
   end
 
+  # Creates a new email template.
   def self.create(client_id, name, html_url, zip_url, screenshot_url)
     options = { :body => { 
       :Name => name,
@@ -18,11 +20,13 @@ class Template
     response.parsed_response
   end
 
+  # Gets the details of this email template.
   def details
     response = CreateSend.get "/templates/#{template_id}.json", {}
     Hashie::Mash.new(response)
   end
 
+  # Updates this email template.
   def update(name, html_url, zip_url, screenshot_url)
     options = { :body => { 
       :Name => name,
@@ -32,6 +36,7 @@ class Template
     response = CreateSend.put "/templates/#{template_id}.json", options
   end
 
+  # Deletes this email template.
   def delete
     response = CreateSend.delete "/templates/#{template_id}.json", {}
   end

data/test/campaign_test.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/helper'
 
-class ClientTest < Test::Unit::TestCase
+class CampaignTest < Test::Unit::TestCase
   context "when an api caller is authenticated" do
     setup do
       @api_key = '123123123123123123123'
@@ -12,10 +12,16 @@ class ClientTest < Test::Unit::TestCase
       client_id = '87y8d7qyw8d7yq8w7ydwqwd'
       stub_post(@api_key, "campaigns/#{client_id}.json", "create_campaign.json")
       campaign_id = Campaign.create client_id, "subject", "name", "g'day", "good.day@example.com", "good.day@example.com", 
-      "http://example.com/campaign.html", "http://example.com/campaign.txt", [ '7y12989e82ue98u2e', 'dh9w89q8w98wudwd989' ], []
+      "http://example.com/campaign.html", "http://example.com/campaign.txt", [ '7y12989e82ue98u2e', 'dh9w89q8w98wudwd989' ],
+      [ 'y78q9w8d9w8ud9q8uw', 'djw98quw9duqw98uwd98' ]
       campaign_id.should == "787y87y87y87y87y87y87"
     end
-    
+
+    should "send a preview of a draft campaign" do
+      stub_post(@api_key, "campaigns/#{@campaign.campaign_id}/sendpreview.json", nil)
+      @campaign.send_preview [ "test+89898u9@example.com", "test+787y8y7y8@example.com" ], "random"
+    end
+
     should "send a campaign" do
       stub_post(@api_key, "campaigns/#{@campaign.campaign_id}/send.json", nil)
       @campaign.send "confirmation@example.com"
@@ -35,64 +41,107 @@ class ClientTest < Test::Unit::TestCase
       summary.Unsubscribed.should == 0
       summary.Bounced.should == 0
       summary.UniqueOpened.should == 5
-      summary.WebVersionURL.should == "http://clientone.createsend.com//t/ViewEmail/r/3A433FC72FFE3B8B/C67FD2F38AC4859C/"
+      summary.WebVersionURL.should == "http://clientone.createsend.com/t/ViewEmail/r/3A433FC72FFE3B8B/C67FD2F38AC4859C/"
     end
     
-    should "get the lists for a campaign" do
-      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/lists.json", "campaign_lists.json")
-      lists = @campaign.lists
-      lists.size.should == 2
-      lists.first.Name.should == "List One"
-      lists.first.ListID.should == "a58ee1d3039b8bec838e6d1482a8a965"
+    should "get the lists and segments for a campaign" do
+      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/listsandsegments.json", "campaign_listsandsegments.json")
+      ls = @campaign.lists_and_segments
+      ls.Lists.size.should == 1
+      ls.Segments.size.should == 1
+      ls.Lists.first.Name.should == "List One"
+      ls.Lists.first.ListID.should == "a58ee1d3039b8bec838e6d1482a8a965"
+      ls.Segments.first.Title.should == "Segment for campaign"
+      ls.Segments.first.ListID.should == "2bea949d0bf96148c3e6a209d2e82060"
+      ls.Segments.first.SegmentID.should == "dba84a225d5ce3d19105d7257baac46f"
     end
 
-    # TODO: Add this test once segments has been implemented
-    # should "get the segments for a campaign" do
-    # end
+    should "get the recipients for a campaign" do
+      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/recipients.json?pagesize=20&orderfield=email&page=1&orderdirection=asc", "campaign_recipients.json")
+      res = @campaign.recipients page=1, page_size=20
+      res.ResultsOrderedBy.should == "email"
+      res.OrderDirection.should == "asc"
+      res.PageNumber.should == 1
+      res.PageSize.should == 20
+      res.RecordsOnThisPage.should == 20
+      res.TotalNumberOfRecords.should == 2200
+      res.NumberOfPages.should == 110
+      res.Results.size.should == 20
+      res.Results.first.EmailAddress.should == "subs+6g76t7t0@example.com"
+      res.Results.first.ListID.should == "a994a3caf1328a16af9a69a730eaa706"
+    end
     
     should "get the opens for a campaign" do
       min_date = "2010-01-01"
-      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/opens.json?date=#{CGI.escape(min_date)}", "campaign_opens.json")
+      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/opens.json?page=1&pagesize=1000&orderfield=date&orderdirection=asc&date=#{CGI.escape(min_date)}", "campaign_opens.json")
       opens = @campaign.opens min_date
-      opens.size.should == 5
-      opens.first.EmailAddress.should == "subs+6576576576@example.com"
-      opens.first.ListID.should == "512a3bc577a58fdf689c654329b50fa0"
-      opens.first.Date.should == "2010-10-11 08:29:00"
-      opens.first.IPAddress.should == "192.168.126.87"
+      opens.Results.size.should == 5
+      opens.Results.first.EmailAddress.should == "subs+6576576576@example.com"
+      opens.Results.first.ListID.should == "512a3bc577a58fdf689c654329b50fa0"
+      opens.Results.first.Date.should == "2010-10-11 08:29:00"
+      opens.Results.first.IPAddress.should == "192.168.126.87"
+      opens.ResultsOrderedBy.should == "date"
+      opens.OrderDirection.should == "asc"
+      opens.PageNumber.should == 1
+      opens.PageSize.should == 1000
+      opens.RecordsOnThisPage.should == 5
+      opens.TotalNumberOfRecords.should == 5
+      opens.NumberOfPages.should == 1
     end
 
     should "get the subscriber clicks for a campaign" do
       min_date = "2010-01-01"
-      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/clicks.json?date=#{CGI.escape(min_date)}", "campaign_clicks.json")
+      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/clicks.json?page=1&pagesize=1000&orderfield=date&orderdirection=asc&date=#{CGI.escape(min_date)}", "campaign_clicks.json")
       clicks = @campaign.clicks min_date
-      clicks.size.should == 3
-      clicks.first.EmailAddress.should == "subs+6576576576@example.com"
-      clicks.first.URL.should == "http://video.google.com.au/?hl=en&tab=wv"
-      clicks.first.ListID.should == "512a3bc577a58fdf689c654329b50fa0"
-      clicks.first.Date.should == "2010-10-11 08:29:00"
-      clicks.first.IPAddress.should == "192.168.126.87"
+      clicks.Results.size.should == 3
+      clicks.Results.first.EmailAddress.should == "subs+6576576576@example.com"
+      clicks.Results.first.URL.should == "http://video.google.com.au/?hl=en&tab=wv"
+      clicks.Results.first.ListID.should == "512a3bc577a58fdf689c654329b50fa0"
+      clicks.Results.first.Date.should == "2010-10-11 08:29:00"
+      clicks.Results.first.IPAddress.should == "192.168.126.87"
+      clicks.ResultsOrderedBy.should == "date"
+      clicks.OrderDirection.should == "asc"
+      clicks.PageNumber.should == 1
+      clicks.PageSize.should == 1000
+      clicks.RecordsOnThisPage.should == 3
+      clicks.TotalNumberOfRecords.should == 3
+      clicks.NumberOfPages.should == 1
     end
     
     should "get the unsubscribes for a campaign" do
       min_date = "2010-01-01"
-      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/unsubscribes.json?date=#{CGI.escape(min_date)}", "campaign_unsubscribes.json")
+      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/unsubscribes.json?page=1&pagesize=1000&orderfield=date&orderdirection=asc&date=#{CGI.escape(min_date)}", "campaign_unsubscribes.json")
       unsubscribes = @campaign.unsubscribes min_date
-      unsubscribes.size.should == 1
-      unsubscribes.first.EmailAddress.should == "subs+6576576576@example.com"
-      unsubscribes.first.ListID.should == "512a3bc577a58fdf689c654329b50fa0"
-      unsubscribes.first.Date.should == "2010-10-11 08:29:00"
-      unsubscribes.first.IPAddress.should == "192.168.126.87"
+      unsubscribes.Results.size.should == 1
+      unsubscribes.Results.first.EmailAddress.should == "subs+6576576576@example.com"
+      unsubscribes.Results.first.ListID.should == "512a3bc577a58fdf689c654329b50fa0"
+      unsubscribes.Results.first.Date.should == "2010-10-11 08:29:00"
+      unsubscribes.Results.first.IPAddress.should == "192.168.126.87"
+      unsubscribes.ResultsOrderedBy.should == "date"
+      unsubscribes.OrderDirection.should == "asc"
+      unsubscribes.PageNumber.should == 1
+      unsubscribes.PageSize.should == 1000
+      unsubscribes.RecordsOnThisPage.should == 1
+      unsubscribes.TotalNumberOfRecords.should == 1
+      unsubscribes.NumberOfPages.should == 1
     end
 
     should "get the bounces for a campaign" do
-      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/bounces.json", "campaign_bounces.json")
+      stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/bounces.json?page=1&pagesize=1000&orderfield=date&orderdirection=asc", "campaign_bounces.json")
       bounces = @campaign.bounces
-      bounces.size.should == 2
-      bounces.first.EmailAddress.should == "asdf@softbouncemyemail.com"
-      bounces.first.ListID.should == "654523a5855b4a440bae3fb295641546"
-      bounces.first.BounceType.should == "Soft"
-      bounces.first.Date.should == "2010-07-02 16:46:00"
-      bounces.first.Reason.should == "Bounce - But No Email Address Returned "
+      bounces.Results.size.should == 2
+      bounces.Results.first.EmailAddress.should == "asdf@softbouncemyemail.com"
+      bounces.Results.first.ListID.should == "654523a5855b4a440bae3fb295641546"
+      bounces.Results.first.BounceType.should == "Soft"
+      bounces.Results.first.Date.should == "2010-07-02 16:46:00"
+      bounces.Results.first.Reason.should == "Bounce - But No Email Address Returned "
+      bounces.ResultsOrderedBy.should == "date"
+      bounces.OrderDirection.should == "asc"
+      bounces.PageNumber.should == 1
+      bounces.PageSize.should == 1000
+      bounces.RecordsOnThisPage.should == 2
+      bounces.TotalNumberOfRecords.should == 2
+      bounces.NumberOfPages.should == 1
     end
   end
 end

data/test/client_test.rb

@@ -17,6 +17,7 @@ class ClientTest < Test::Unit::TestCase
     should "get details of a client" do
       stub_get(@api_key, "clients/#{@client.client_id}.json", "client_details.json")
       cl = @client.details
+      cl.ApiKey.should == "639d8cc27198202f5fe6037a8b17a29a59984b86d3289bc9"
       cl.BasicDetails.ClientID.should == "4a397ccaaa55eb4e6aa1221e1e2d7122"
       cl.BasicDetails.ContactName.should == "Client One (contact)"
       cl.AccessDetails.Username.should == "clientone"
@@ -28,7 +29,7 @@ class ClientTest < Test::Unit::TestCase
       campaigns = @client.campaigns
       campaigns.size.should == 2
       campaigns.first.CampaignID.should == 'fc0ce7105baeaf97f47c99be31d02a91'
-      campaigns.first.WebVersionURL.should == 'http://hello.createsend.com//t/ViewEmail/r/765E86829575EE2C/C67FD2F38AC4859C/'
+      campaigns.first.WebVersionURL.should == 'http://hello.createsend.com/t/ViewEmail/r/765E86829575EE2C/C67FD2F38AC4859C/'
       campaigns.first.Subject.should == 'Campaign One'
       campaigns.first.Name.should == 'Campaign One'
       campaigns.first.SentDate.should == '2010-10-12 12:58:00'
@@ -43,6 +44,7 @@ class ClientTest < Test::Unit::TestCase
       drafts.first.Name.should == 'Draft One'
       drafts.first.Subject.should == 'Draft One'
       drafts.first.DateCreated.should == '2010-08-19 16:08:00'
+      drafts.first.PreviewURL.should == 'http://hello.createsend.com/t/ViewEmail/r/E97A7BB2E6983DA1/C67FD2F38AC4859C/'
     end
 
     should "get all lists" do
@@ -53,21 +55,29 @@ class ClientTest < Test::Unit::TestCase
       lists.first.Name.should == 'List One'
     end
     
-    should "get all segments" do
+    should "get all segments for a client" do
       stub_get(@api_key, "clients/#{@client.client_id}/segments.json", "segments.json")
       segments = @client.segments
       segments.size.should == 2
       segments.first.ListID.should == 'a58ee1d3039b8bec838e6d1482a8a965'
-      segments.first.Name.should == 'Segment One'
+      segments.first.SegmentID.should == '46aa5e01fd43381863d4e42cf277d3a9'
+      segments.first.Title.should == 'Segment One'
     end
 
     should "get suppression list" do
-      stub_get(@api_key, "clients/#{@client.client_id}/suppressionlist.json", "suppressionlist.json")
-      sl = @client.suppressionlist
-      sl.size.should == 2
-      sl.first.EmailAddress.should == "subs+098u0qu0qwd@example.com"
-      sl.first.Date.should == "2009-11-25 13:23:20"
-      sl.first.State.should == "Suppressed"
+      stub_get(@api_key, "clients/#{@client.client_id}/suppressionlist.json?pagesize=1000&orderfield=email&page=1&orderdirection=asc", "suppressionlist.json")
+      res = @client.suppressionlist
+      res.ResultsOrderedBy.should == "email"
+      res.OrderDirection.should == "asc"
+      res.PageNumber.should == 1
+      res.PageSize.should == 1000
+      res.RecordsOnThisPage.should == 5
+      res.TotalNumberOfRecords.should == 5
+      res.NumberOfPages.should == 1
+      res.Results.size.should == 5
+      res.Results.first.EmailAddress.should == "example+1@example.com"
+      res.Results.first.Date.should == "2010-10-26 10:55:31"
+      res.Results.first.State.should == "Suppressed"
     end
 
     should "get all templates" do

data/test/fixtures/active_subscribers.json

@@ -1,67 +1,69 @@
-[
-  {
-    "EmailAddress": "subs+7t8787Y@example.com",
-    "Name": "Subscriber One",
-    "Date": "2010-10-25 10:28:00",
-    "State": "Active",
-    "CustomFields": [
-      {
-        "Key": "website",
-        "Value": "http://example.com"
-      },
-      {
-        "Key": "age",
-        "Value": "24"
-      },
-      {
-        "Key": "subscription date",
-        "Value": "2010-03-09"
-      }
-    ]
-  },
-  {
-    "EmailAddress": "subs+7878787y8ggg@example.com",
-    "Name": "Subscriber Two",
-    "Date": "2010-10-25 12:17:00",
-    "State": "Active",
-    "CustomFields": [
-      {
-        "Key": "website",
-        "Value": "http://subdomain.example.com"
-      }
-    ]
-  },
-  {
-    "EmailAddress": "subs+7890909i0ggg@example.com",
-    "Name": "Subscriber Three",
-    "Date": "2010-10-25 12:52:00",
-    "State": "Active",
-    "CustomFields": [
-      {
-        "Key": "website",
-        "Value": "http://subdomain.example.com"
-      }
-    ]
-  },
-  {
-    "EmailAddress": "example+1@example.com",
-    "Name": "Example One",
-    "Date": "2010-10-25 14:33:00",
-    "State": "Active",
-    "CustomFields": []
-  },
-  {
-    "EmailAddress": "example+2@example.com",
-    "Name": "Example Two",
-    "Date": "2010-10-25 14:33:00",
-    "State": "Active",
-    "CustomFields": []
-  },
-  {
-    "EmailAddress": "example+3@example.com",
-    "Name": "Example Three",
-    "Date": "2010-10-25 14:33:00",
-    "State": "Active",
-    "CustomFields": []
-  }
-]
+{
+  "Results": [
+    {
+      "EmailAddress": "subs+7t8787Y@example.com",
+      "Name": "Person One",
+      "Date": "2010-10-25 10:28:00",
+      "State": "Active",
+      "CustomFields": [
+        {
+          "Key": "website",
+          "Value": "http://example.com"
+        },
+        {
+          "Key": "age",
+          "Value": "24"
+        },
+        {
+          "Key": "subscription date",
+          "Value": "2010-03-09"
+        }
+      ]
+    },
+    {
+      "EmailAddress": "subs+7878787y8ggg@example.com",
+      "Name": "Person Two",
+      "Date": "2010-10-25 12:17:00",
+      "State": "Active",
+      "CustomFields": [
+        {
+          "Key": "website",
+          "Value": "http://subdomain.example.com"
+        }
+      ]
+    },
+    {
+      "EmailAddress": "subs+7890909i0ggg@example.com",
+      "Name": "Person Three",
+      "Date": "2010-10-25 12:52:00",
+      "State": "Active",
+      "CustomFields": [
+        {
+          "Key": "website",
+          "Value": "http://subdomain.example.com"
+        }
+      ]
+    },
+    {
+      "EmailAddress": "subs@example.com",
+      "Name": "Person Four",
+      "Date": "2010-10-27 13:13:00",
+      "State": "Active",
+      "CustomFields": []
+    },
+    {
+      "EmailAddress": "joey@example.com",
+      "Name": "Person Five",
+      "Date": "2010-10-27 13:13:00",
+      "State": "Active",
+      "CustomFields": []
+    }
+  ],
+  "ResultsOrderedBy": "email",
+  "OrderDirection": "asc",
+  "PageNumber": 1,
+  "PageSize": 1000,
+  "RecordsOnThisPage": 5,
+  "TotalNumberOfRecords": 5,
+  "NumberOfPages": 1
+}