Class: Contactology::List

Inherits:
Stash
  • Object
show all
Extended by:
API
Defined in:
lib/contactology/list.rb

Overview

Represents a subscription List in Contactology. Lists are a convenient way to organize groups of Contacts in order to send large numbers of contacts a Campaign, easily.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from API

query, request_headers

Methods inherited from Stash

#[]=

Class Method Details

.all(options = {}) ⇒ Object

Public: Returns a collection of all active lists on your account.

Returns a collection of Contactology::List instances.



27
28
29
30
31
32
33
 
# File 'lib/contactology/list.rb', line 27

def self.all(options = {})
  query('List_Get_Active_Lists', options.merge({
    :on_timeout => [],
    :on_error => [],
    :on_success => Proc.new { |response| response.values.collect { |list| List.new(list) }}
  }))
end

.create(attributes, options = {}) ⇒ Object

Public: Creates a new, public list on Contactology. The new list’s :name is the only required attribute.

Returns a Contactology::List instance when successful. Returns false when unsuccessful or a network failure occurs.

Raises:

  • (ArgumentError) 


42
43
44
45
 
# File 'lib/contactology/list.rb', line 42

def self.create(attributes, options = {})
  raise ArgumentError, 'Expected an :name attribute' unless attributes.has_key?(:name)
  new(attributes).save(options)
end

.find(id, options = {}) ⇒ Object

Public: Loads a Contactology list by ID.

Returns a Contactology::List instance on success. Returns nil for an unknown ID or network error.



53
54
55
56
57
58
59
60
 
# File 'lib/contactology/list.rb', line 53

def self.find(id, options = {})
  query('List_Get_Info', options.merge({
    'listId' => id,
    :on_timeout => nil,
    :on_error => nil,
    :on_success => Proc.new { |response| new(response) if response.kind_of?(Hash) }
  }))
end

Instance Method Details

#destroy(options = {}) ⇒ Object

Public: Removes a list from Contactology.

Returns true when successful. Returns false when unsuccessful.



69
70
71
72
73
74
75
76
 
# File 'lib/contactology/list.rb', line 69

def destroy(options = {})
  self.class.query('List_Delete', options.merge({
    'listId' => id,
    :on_timeout => false,
    :on_error => false,
    :on_success => Proc.new { |response| response }
  }))
end

#import(contacts, options = {}) ⇒ Object

Public: Imports contacts into a list using a prescribed contact collection format.

Examples

list = Contactology::List.create :name => 'import-test'
# => #<Contactology::List:0x000... @name="import-test" ...>
list.import([{'email' => '[email protected]', 'first_name' => 'Imp', 'last_name' => 'Orted'}, {...}])
# => true

Returns true if all contacts imported successfully. Returns false if any contact import failed or a network error occurred.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/contactology/list.rb', line 92

def import(contacts, options = {})
  self.class.query('List_Import_Contacts', options.merge({
    'listId' => id,
    'source' => options[:source] || 'Manual Entry',
    'contacts' => contacts,
    'optionalParameters' => {
      'activateDeleted' => true,
      'updateCustomFields' => true
    },
    :on_timeout => false,
    :on_error => false,
    :on_success => Proc.new { |response|
      response.kind_of?(Hash) && response['success'] == contacts.size
    }
  }))
end

#internal? ⇒ Boolean

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/contactology/list.rb', line 109

def internal?
  type == 'internal'
end

#opt_in? ⇒ Boolean

Returns:

  • (Boolean) 


113
114
115
 
# File 'lib/contactology/list.rb', line 113

def opt_in?
  opt_in
end

#private? ⇒ Boolean

Returns:

  • (Boolean) 


121
122
123
 
# File 'lib/contactology/list.rb', line 121

def private?
  type == 'private'
end

#public? ⇒ Boolean

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/contactology/list.rb', line 117

def public?
  type == 'public'
end

#save(options = {}) ⇒ Object 



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/contactology/list.rb', line 125

def save(options = {})
  self.class.query('List_Add_Public', options.merge({
    'listId' => id,
    'name' => name,
    'description' => description,
    'optionalParameters' => {
      'optIn' => opt_in
    },
    :on_timeout => false,
    :on_error => false,
    :on_success => Proc.new { |response|
      data = self.class.find(response)
      self.id = data.id
      self.description = data.description
      self.name = data.name
      self.type = data.type
      self.opt_in = data.opt_in
      self
    }
  }))
end

#save!(options = {}) ⇒ Object 



147
148
149
 
# File 'lib/contactology/list.rb', line 147

def save!(options = {})
  save(options) || raise(InvalidObjectError)
end

#subscribe(email, options = {}) ⇒ Object

Public: Adds an email address to the list.

Examples

list = Contactology::List.find 1
# => #<Contactology::List:0x000... @id="1" ...>
list.subscribe '[email protected]'
# => true

Returns true when the address is successfully added. Returns false when the subscription fails or a network error occurs.



164
165
166
167
168
169
170
171
172
 
# File 'lib/contactology/list.rb', line 164

def subscribe(email, options = {})
  self.class.query('List_Subscribe', options.merge({
    'listId' => id,
    'email' => email.respond_to?(:email) ? email.email : email,
    :on_timeout => false,
    :on_error => false,
    :on_success => Proc.new { |response| response }
  }))
end

#test? ⇒ Boolean

Returns:

  • (Boolean) 


174
175
176
 
# File 'lib/contactology/list.rb', line 174

def test?
  type == 'test'
end

#unsubscribe(email, options = {}) ⇒ Object

Public: Unsubscribes an email address from the Contactology::List.

Returns true when the address is removed. Returns false when the removal fails or a network error occurs.



184
185
186
187
188
189
190
191
192
 
# File 'lib/contactology/list.rb', line 184

def unsubscribe(email, options = {})
  self.class.query('List_Unsubscribe', options.merge({
    'listId' => id,
    'email' => email,
    :on_timeout => false,
    :on_error => false,
    :on_success => Proc.new { |response| response }
  }))
end