Class: Klaviyo::Lists

Inherits:
Client
  • Object
show all
Defined in:
lib/klaviyo/apis/lists.rb

Constant Summary collapse

EXCLUSIONS = 
'exclusions'
GROUP = 
'group'
LIST = 
'list'
LISTS = 
'lists'
MEMBERS = 
'members'
SUBSCRIBE = 
'subscribe'

Constants inherited from Client

Client::ALL, Client::BASE_API_URL, Client::CONTENT_JSON, Client::CONTENT_URL_FORM, Client::DEFAULT_COUNT, Client::DEFAULT_PAGE, Client::DEFAULT_SORT_DESC, Client::HTTP_DELETE, Client::HTTP_GET, Client::HTTP_POST, Client::HTTP_PUT, Client::METRIC, Client::METRICS, Client::TIMELINE, Client::V1_API, Client::V2_API

Class Method Summary collapse

Class Method Details

.add_subscribers_to_list(list_id, profiles: []) ⇒ Object

Subscribe profiles to a list.

Parameters:

  • list_id (String) —

    the id of the list

  • profiles (List) (defaults to: []) —

    a list of JSON objects. Each object requires either an email or phone number key.

Returns:

  • will retun HTTP OK on success. If the list is single opt-in then a list of records containing the email address, phone number, push token, and the corresponding profile ID will also be included.



78
79
80
81
82
83
84
 
# File 'lib/klaviyo/apis/lists.rb', line 78

def self.add_subscribers_to_list(list_id, profiles: [])
  path = "#{LIST}/#{list_id}/#{SUBSCRIBE}"
  params = {
    :profiles => profiles
  }
  v2_request(HTTP_POST, path, params)
end

.add_to_list(list_id, profiles: []) ⇒ Object

Add profiles to a list

Parameters:

  • list_id (String) —

    the id of the list

  • :profiles (List) —

    A list of JSON objects. Each object is a profile that will be added to the list

Returns:

  • will return with HTTP OK on success and a list of records of the corresponding profile id



104
105
106
107
108
109
110
 
# File 'lib/klaviyo/apis/lists.rb', line 104

def self.add_to_list(list_id, profiles: [])
  path = "#{LIST}/#{list_id}/#{MEMBERS}"
  params = {
    :profiles => profiles
  }
  v2_request(HTTP_POST, path, params)
end

.check_list_memberships(list_id, emails: [], phone_numbers: [], push_tokens: []) ⇒ Object

Check if profiles are on a list

Parameters:

  • list_id (String) —

    the id of the list

  • :emails (List) —

    the emails of the profiles to check

  • :phone_numbers (List) —

    the phone numbers of the profiles to check

  • :push_tokens (List) —

    push tokens of the profiles to check

Returns:

  • A list of JSON objects of the profiles. Profiles that are supressed or not found are not included.



119
120
121
122
123
124
125
126
127
 
# File 'lib/klaviyo/apis/lists.rb', line 119

def self.check_list_memberships(list_id, emails: [], phone_numbers: [], push_tokens: [])
  path = "#{LIST}/#{list_id}/#{MEMBERS}"
  params = {
    :emails => emails,
    :phone_numbers => phone_numbers,
    :push_tokens => push_tokens
  }
  v2_request(HTTP_GET, path, params)
end

.check_list_subscriptions(list_id, emails: [], phone_numbers: [], push_tokens: []) ⇒ Object

Check if profiles are in a list and not supressed

Parameters:

  • list_id (String) —

    the id of the list

  • :emails (List) —

    the emails of the profiles to check

  • :phone_numbers (List) —

    the phone numbers of the profiles to check

  • :push_tokens (List) —

    push tokens of the profiles to check

Returns:

  • A list of JSON objects of the profiles. Profiles that are supressed or not found are not included.



61
62
63
64
65
66
67
68
69
 
# File 'lib/klaviyo/apis/lists.rb', line 61

def self.check_list_subscriptions(list_id, emails: [], phone_numbers: [], push_tokens: [])
  path = "#{LIST}/#{list_id}/#{SUBSCRIBE}"
  params = {
    :emails => emails,
    :phone_numbers => phone_numbers,
    :push_tokens => push_tokens
  }
  v2_request(HTTP_GET, path, params)
end

.create_list(list_name) ⇒ Object

Creates a new list

Parameters:

  • list_name (String) —

    the list name

Returns:

  • will return with HTTP OK on success



13
14
15
16
17
18
 
# File 'lib/klaviyo/apis/lists.rb', line 13

def self.create_list(list_name)
  body = {
    :list_name => list_name
  }
  v2_request(HTTP_POST, LISTS, body)
end

.delete_list(list_id) ⇒ Object

Deletes a list

Parameters:

  • list_id (String) —

    the id of the list

Returns:

  • will return with HTTP OK on success



49
50
51
52
 
# File 'lib/klaviyo/apis/lists.rb', line 49

def self.delete_list(list_id)
  path = "#{LIST}/#{list_id}"
  v2_request(HTTP_DELETE, path)
end

.get_group_members(list_id) ⇒ List

Get all of the emails, phone numbers, and push tokens for profiles in a given list or segment

Parameters:

  • list_id (String) —

    the id of the list

  • marker (Integer) —

    a marker from a previous call to get the next batch

Returns:

  • (List) —

    A list of JSON objects for each profile with the id, email, phone number, and push token



161
162
163
164
 
# File 'lib/klaviyo/apis/lists.rb', line 161

def self.get_group_members(list_id)
  path = "#{GROUP}/#{list_id}/#{MEMBERS}/#{ALL}"
  v2_request(HTTP_GET, path)
end

.get_list_details(list_id) ⇒ JSON

Retrieves the details of the list

Parameters:

  • list_id (String) —

    the id of the list

Returns:

  • (JSON) —

    a JSON object containing information about the list



29
30
31
32
 
# File 'lib/klaviyo/apis/lists.rb', line 29

def self.get_list_details(list_id)
  path = "#{LIST}/#{list_id}"
  v2_request(HTTP_GET, path)
end

.get_list_exclusions(list_id, marker: nil) ⇒ List

Get all emails, phone numbers, along with reasons for list exclusion

Parameters:

  • list_id (String) —

    the id of the list

  • marker (Integer) (defaults to: nil) —

    a marker from a previous call to get the next batch

Returns:

  • (List) —

    A list of JSON object for each profile with the reason for exclusion



149
150
151
152
153
154
155
 
# File 'lib/klaviyo/apis/lists.rb', line 149

def self.get_list_exclusions(list_id, marker: nil)
  path = "#{LIST}/#{list_id}/#{EXCLUSIONS}/#{ALL}"
  params = {
    :marker => marker
  }
  v2_request(HTTP_GET, path, params)
end

.get_lists ⇒ List

Retrieves all the lists in the Klaviyo account

Returns:

  • (List) —

    a list of JSON objects of the name and id for each list



22
23
24
 
# File 'lib/klaviyo/apis/lists.rb', line 22

def self.get_lists()
  v2_request(HTTP_GET, LISTS)
end

.remove_from_list(list_id, emails: [], phone_numbers: [], push_tokens: []) ⇒ Object

Remove profiles from a list

Parameters:

  • list_id (String) —

    the id of the list

  • :emails (List) —

    the emails of the profiles to check

  • :phone_numbers (List) —

    the phone numbers of the profiles to check

  • :push_tokens (List) —

    push tokens of the profiles to check

Returns:

  • will return with HTTP OK on success



135
136
137
138
139
140
141
142
143
 
# File 'lib/klaviyo/apis/lists.rb', line 135

def self.remove_from_list(list_id, emails: [], phone_numbers: [], push_tokens: [])
  path = "#{LIST}/#{list_id}/#{MEMBERS}"
  params = {
    :emails => emails,
    :phone_numbers => phone_numbers,
    :push_tokens => push_tokens
  }
  v2_request(HTTP_DELETE, path, params)
end

.unsubscribe_from_list(list_id, emails: []) ⇒ Object

Unsubscribe and remove profiles from a list

Parameters:

  • list_id (String) —

    the id of the list

  • :emails (List) —

    the emails of the profiles to check

Returns:

  • will return with HTTP OK on success



90
91
92
93
94
95
96
 
# File 'lib/klaviyo/apis/lists.rb', line 90

def self.unsubscribe_from_list(list_id, emails: [])
  path = "#{LIST}/#{list_id}/#{SUBSCRIBE}"
  params = {
    :emails => emails
  }
  v2_request(HTTP_DELETE, path, params)
end

.update_list_details(list_id, list_name) ⇒ Object

Updates the properties of a list

Parameters:

  • list_id (String) —

    the id of the list

  • list_name (String) —

    the new name of the list

Returns:

  • will return with HTTP OK on success



38
39
40
41
42
43
44
 
# File 'lib/klaviyo/apis/lists.rb', line 38

def self.update_list_details(list_id, list_name)
  path = "#{LIST}/#{list_id}"
  body = {
    :list_name => list_name
  }
  v2_request(HTTP_PUT, path, body)
end