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::KL_USER_AGENT, Client::KL_VERSION, 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, api_key: nil, 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.



85
86
87
88
89
90
91
 
# File 'lib/klaviyo/apis/lists.rb', line 85

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

.add_to_list(list_id, api_key: nil, 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



113
114
115
116
117
118
119
 
# File 'lib/klaviyo/apis/lists.rb', line 113

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

.check_list_memberships(list_id, api_key: nil, 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.



129
130
131
132
133
134
135
136
137
 
# File 'lib/klaviyo/apis/lists.rb', line 129

def self.check_list_memberships(list_id, api_key: nil, 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, api_key: api_key, **params)
end

.check_list_subscriptions(list_id, api_key: nil, 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.



67
68
69
70
71
72
73
74
75
 
# File 'lib/klaviyo/apis/lists.rb', line 67

def self.check_list_subscriptions(list_id, api_key: nil, 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, api_key: api_key, **params)
end

.create_list(list_name, api_key: nil) ⇒ Object

Creates a new list

Parameters:

  • list_name (String) —

    the list name

Returns:

  • will return with HTTP OK on success



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

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

.delete_list(list_id, api_key: nil) ⇒ Object

Deletes a list

Parameters:

  • list_id (String) —

    the id of the list

Returns:

  • will return with HTTP OK on success



54
55
56
57
 
# File 'lib/klaviyo/apis/lists.rb', line 54

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

.get_group_members(list_id, api_key: nil) ⇒ 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



174
175
176
177
 
# File 'lib/klaviyo/apis/lists.rb', line 174

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

.get_list_details(list_id, api_key: nil) ⇒ 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



32
33
34
35
 
# File 'lib/klaviyo/apis/lists.rb', line 32

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

.get_list_exclusions(list_id, api_key: nil, 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



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

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

.get_lists(api_key: nil) ⇒ List

Retrieves all the lists in the Klaviyo account

Returns:

  • (List) —

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



24
25
26
 
# File 'lib/klaviyo/apis/lists.rb', line 24

def self.get_lists(api_key: nil)
  v2_request(HTTP_GET, LISTS, api_key: api_key)
end

.remove_from_list(list_id, api_key: nil, 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



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

def self.remove_from_list(list_id, api_key: nil, 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, api_key: api_key, **params)
end

.unsubscribe_from_list(list_id, api_key: nil, 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



98
99
100
101
102
103
104
 
# File 'lib/klaviyo/apis/lists.rb', line 98

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

.update_list_details(list_id, list_name, api_key: nil) ⇒ 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



42
43
44
45
46
47
48
 
# File 'lib/klaviyo/apis/lists.rb', line 42

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