Klaviyo Ruby SDK (Legacy)

Legacy Notice

This SDK is set to be deprecated + retired on 2024-06-30.

We have a NEW ruby SDK to go along with our new API.

We recommend migrating over to our newest SDK.

You can read more about our SDK release history and support here

Klaviyo Ruby SDK

• SDK version: 1.0.5.20220329

Helpful Resources

• API Reference
• API Guides
• Postman Workspace

Design & Approach

This SDK is a thin wrapper around our API. See our API Reference for full documentation on API behavior.

Organization

This SDK is organized into the following resources:

• Campaigns

• DataPrivacy

• ListsSegments

• Metrics

• Profiles

• Templates

• TrackIdentify

Installation

Build

To build the Ruby code into a gem:

gem build klaviyo_sdk.gemspec

Then install the gem locally:

gem install ./klaviyo_sdk-1.0.5.20220329.gem

Finally add this to the Gemfile:

gem 'klaviyo_sdk', '~> 1.0.5.20220329'

To install directly from rubygems:

gem install klaviyo_sdk

Usage Example

To load the gem

# Load the gem
require 'klaviyo_sdk'

# Setup authorization
Klaviyo.configure do |config|
  config.api_key['ApiKeyAuth'] = 'YOUR API KEY'
  #config.max_retries = 5 # optional
  #config.max_delay = 60 # optional
end

NOTE:

• The SDK retries on resolvable errors, namely: rate limits (common) and server errors on klaviyo (rare).
• max_retry denotes number of attempts the client will make in order to execute the request successfully.
• max_delay denotes total delay (in seconds) across all attempts.

To call the metric-export operation:

metric_id = 'METRIC_ID'
count = 100

begin
  result = Klaviyo::Metrics.metric_export(metric_id, count=count) 
end

Error Handling

This SDK throws an ApiException error when the server returns a non-2XX response.

metric_id = 'METRIC_ID'
count = 100

begin
  result = Klaviyo::Metrics.metric_export(metric_id, count=count) 
rescue Klaviyo::ApiError => e
  puts "Error when calling Metrics.metric_export #{e}"
end

Comprehensive list of Operations & Parameters

NOTE:

• Organization: Resource groups and operation_ids are listed in alphabetical order, first by Resource name, then by OpenAPI Summary. Operation summaries are those listed in the right side bar of the API Reference.
• For example values / data types, as well as whether parameters are required/optional, please reference the corresponding API Reference link.
• Some args are required for the API call to succeed, the API docs above are the source of truth regarding which params are required.

Campaigns

Cancel a Campaign

Klaviyo::Campaigns.cancel_campaign(campaign_id)

Example:

campaign_id = 'CAMPAIGN_ID'
response = Klaviyo::Campaigns.cancel_campaign(campaign_id)

Clone a Campaign

Klaviyo::Campaigns.clone_campaign(campaign_id, name, list_id)

Example:

campaign_id = 'CAMPAIGN_ID'
name        = 'CLONED_CAMPAIGN'
list_id     = 'LIST_ID'

response = Klaviyo::Campaigns.clone_campaign(campaign_id, name, list_id)

Create New Campaign

Klaviyo::Campaigns.create_campaign(list_id, template_id, from_email, from_name, subject, opts)

Example:

list_id     = 'LIST_ID'
template_id = 'TEMPLATE_ID'
from_email  = '[email protected]'
from_name   = 'George Washington'
subject     = 'Happy Fourth!'

opts = {
  'use_smart_sending': true,
  'add_google_analytics': false,
  'name': 'Campaign Name',
}

response = Klaviyo::Campaigns.create_campaign(list_id, template_id, from_email, from_name, subject, opts)

Get Campaign Info

Klaviyo::Campaigns.get_campaign_info(campaign_id)

Example:

campaign_id = 'CAMPAIGN_ID'

response = Klaviyo::Campaigns.get_campaign_info(campaign_id)

Get Campaign Recipients

Klaviyo::Campaigns.get_campaign_recipients(campaign_id, opts)

Example:

campaign_id = 'CAMPAIGN_ID'

# optional parameters
opts = {
  'count': 1, 
  'sort': 'desc',
  # offset: 'offset'
}

response = Klaviyo::Campaigns.get_campaign_recipients(campaign_id, opts)

Get Campaigns

Klaviyo::Campaigns.get_campaigns(opts)

Example:

opts = {
  'page': 1,
  'count': 1
}

response = Klaviyo::Campaigns.get_campaigns(opts)

Schedule a Campaign

Klaviyo::Campaigns.schedule_campaign(campaign_id, send_time)

Example:

campaign_id = 'CAMPAIGN_ID'
send_time = '2030-01-13 00:00:00'

response = Klaviyo::Campaigns.schedule_campaign(campaign_id, send_time)

Send a Campaign Immediately

Klaviyo::Campaigns.send_campaign(campaign_id)

Example:

campaign_id = 'CAMPAIGN_ID'

response = Klaviyo::Campaigns.send_campaign(campaign_id)

Update Campaign

Klaviyo::Campaigns.update_campaign(campaign_id, opts)

Example:

campaign_id = 'CAMPAIGN_ID'

opts = {
  'list_id': 'LIST_ID', 
  'template_id': 'TEMPLATE_ID', 
  'from_email': '[email protected]', 
  'from_name': 'George Washington', 
  'subject': 'Happy Fourth!', 
  'name': 'Campaign Name', 
  'use_smart_sending': true, 
  'add_google_analytics': false
}

response = Klaviyo::Campaigns.update_campaign(campaign_id, opts)

DataPrivacy

Request a Deletion

Klaviyo::DataPrivacy.request_deletion(opts)

Example:

opts = {
  body: {
    'email': '[email protected]'
  }
}

response = Klaviyo::DataPrivacy.request_deletion(opts)

ListsSegments

Add Members to a List

Klaviyo::ListsSegments.add_members(list_id, opts)

Example:

list_id = 'LIST_ID'
opts = {
  body: {
      profiles: [
          {
              'email': '[email protected]'
          }
      ]
  }
}

response = Klaviyo::ListsSegments.add_members(list_id, opts)

Create List

Klaviyo::ListsSegments.create_list(list_name)

Example:

list_name = 'MyNewList'

response = Klaviyo::ListsSegments.create_list(list_name)

Delete List

Klaviyo::ListsSegments.delete_list(list_id)

Example:

list_id = 'LIST_ID'

response = Klaviyo::ListsSegments.delete_list(list_id)

Exclude Profile From All Email

Klaviyo::ListsSegments.exclude_globally(email)

Example:

email = '[email protected]'

response = Klaviyo::ListsSegments.exclude_globally(email)

Get Global Exclusions & Unsubscribes

Klaviyo::ListsSegments.get_global_exclusions(opts)

Example:

opts = {
  query_params: {
    reason: 'manually_excluded',
    sort: 'desc',
    count: 2,
    page: 1
  }
}

response = Klaviyo::ListsSegments.get_global_exclusions(opts)

Get All Exclusions for a List

Klaviyo::ListsSegments.get_list_exclusions(list_id, opts)

Example:

list_id = 'LIST_ID'

opts = {
  query_params: {
      # marker: 12345
  }
}

response = Klaviyo::ListsSegments.get_list_exclusions(list_id, opts)

Get List Info

Klaviyo::ListsSegments.get_list_info(list_id)

Example:

list_id = 'LIST_ID'

response = Klaviyo::ListsSegments.get_list_info(list_id)

Check if Profiles Are in a List

Klaviyo::ListsSegments.get_list_members(list_id, opts)

Example:

list_id = 'LIST_ID'

opts = {
  body: {
    'emails': [
      '[email protected]'
    ]
  }
}

response = Klaviyo::ListsSegments.get_list_members(list_id, opts)

Check if Profiles Are in a List and not Suppressed

Klaviyo::ListsSegments.get_list_subscriptions(list_id, opts)

Example:

list_id = 'LIST_ID'

opts = {
  body: {'emails': ['[email protected]']}
}

response = Klaviyo::ListsSegments.get_list_subscriptions(list_id, opts)

Get Lists

Klaviyo::ListsSegments.get_lists

Example:

response = Klaviyo::ListsSegments.get_lists

Get List and Segment Members

Klaviyo::ListsSegments.get_members(list_or_segment_id, opts)

Example:

list_id = 'LIST_ID'

opts = {
  query_params: {
      # marker: 12345
  }
}
response = Klaviyo::ListsSegments.get_members(list_id)

Check if Profiles Are in a Segment

Klaviyo::ListsSegments.get_segment_members(segment_id, opts)

Example:

segment_id = 'SEGMENT_ID'

opts = {
  body: {'emails': ['[email protected]']}
}
response = Klaviyo::ListsSegments.get_segment_members(segment_id, opts)

Remove Profiles From List

Klaviyo::ListsSegments.remove_members(list_id, opts)

Example:

list_id = 'LIST_ID'

opts = {
  body: {'emails': ['[email protected]']}
}

response = Klaviyo::ListsSegments.remove_members(list_id, opts)

Subscribe Profiles to List

Klaviyo::ListsSegments.subscribe(list_id, opts)

Example:

list_id = 'LIST_ID'

opts = {
  body: {
      profiles: [
          {
              'email': '[email protected]'
          }
      ]
  }
}

response = Klaviyo::ListsSegmentsApi.new.subscribe(list_id, opts)

Unsubscribe Profiles From List

Klaviyo::ListsSegments.unsubscribe(list_id, opts)

Example:

list_id = 'LIST_ID'

opts = {
  body: {
    'emails': [
      '[email protected]'
    ]
  }
}
response = Klaviyo::ListsSegments.unsubscribe(list_id, opts)

Update List Name

Klaviyo::ListsSegments.update_list_name(list_id, list_name)

Example:

list_id   = 'LIST_ID'
list_name = 'MyRenamedList'

response = Klaviyo::ListsSegments.update_list_name(list_id, list_name)

Metrics

Get Metrics Info

Klaviyo::Metrics.get_metrics(opts)

Example:

opts = {
  query_params: {
    page: 0,
    count: 50
  }
}

response = Klaviyo::Metrics.get_metrics(opts)

Query Event Data

Klaviyo::Metrics.metric_export(metric_id, opts)

Example:

metric_id = 'METRIC_ID'
opts = {
  query_params: {
    unit: 'week',
    measurement: 'sum',
    count: 2
  }
}

response = Klaviyo::Metrics.metric_export(metric_id, opts)

Get Events for a Specific Metric

Klaviyo::Metrics.metric_timeline(metric_id, opts)

Example:

metric_id = 'METRIC_ID'

opts = {
  query_params: {
    since: '0000000000',
    count: 2,
    sort: 'asc'
  }
}

response = Klaviyo::Metrics.metric_timeline(metric_id, opts)

Get Events for All Metrics

Klaviyo::Metrics.metrics_timeline(opts)

Example:

opts = {
  query_params: {
    since: '0000000000',
    count: 2,
    sort: 'asc'
  }
}
response = Klaviyo::Metrics.metrics_timeline(opts)

Profiles

Exchange ID for Profile ID

Klaviyo::Profiles.exchange(opts)

Example:

opts = {
  body: {'exchange_id': 'EXCHANGE_ID'}
}

response = Klaviyo::Profiles.exchange(opts)

Get Profile

Klaviyo::Profiles.get_profile(person_id)

Example:

person_id = 'PERSON_ID'

response = Klaviyo::Profiles.get_profile(person_id)

Get Profile ID

Klaviyo::Profiles.get_profile_id(opts)

Example:

opts = {
  query_params: {
    email: '[email protected]',
    phone_number: '555-555-5555',
    external_id: 'EXTERNAL_ID'
  }
}

response = Klaviyo::Profiles.get_profile_id(opts)

Get Profile's Events for a Specific Metric

Klaviyo::Profiles.profile_metric_timeline(person_id, metric_id, opts)

Example:

person_id = 'PERSON_ID'
metric_id = 'METRIC_ID'

opts = {
  query_params: {
    since: '0000000000',
    count: 2,
    sort: 'asc'
  }
}

response = Klaviyo::Profiles.profile_metric_timeline(person_id, metric_id, opts)

Get Profile's Events for all Metrics

Klaviyo::Profiles.profile_metrics_timeline(person_id, opts)

Example:

person_id = 'PERSON_ID'

opts = {
  query_params: {
    since: '0000000000',
    count: 2,
    sort: 'asc'
  }
}

response = Klaviyo::Profiles.profile_metrics_timeline(person_id, opts)

Update Profile

Klaviyo::Profiles.update_profile(person_id, opts)

Example:

person_id = 'PERSON_ID'

opts = {
  query_params: {'$email': '[email protected]'}
}

response = Klaviyo::Profiles.update_profile(person_id, opts)

Templates

Clone Template

Klaviyo::Templates.clone_template(template_id, name)

Example:

template_id = 'TEMPLATE_ID'
name = 'My Cloned Template'

response = Klaviyo::Templates.clone_template(template_id, name)

Create New Template

Klaviyo::Templates.create_template(name, html)

Example:

name = 'New Template Name'
html = '<html><body><p>This is an email for {{ email }}.</p></body></html>'

response = Klaviyo::Templates.create_template(name, html)

Delete Template

Klaviyo::Templates.delete_template(template_id)

Example:

template_id = 'TEMPLATE_ID'

response = Klaviyo::Templates.delete_template(template_id)

Get All Templates

Klaviyo::Templates.get_templates

Example:

response = Klaviyo::Templates.get_templates

Render Template

Klaviyo::Templates.render_template(template_id, opts)

Example:

template_id = 'TEMPLATE_ID'
context = {'name': 'George Washington', 'state': 'VA'}

opts = {
  form_params: {
    context: context.to_json
  }
}

response = Klaviyo::Templates.render_template(template_id, opts)

Render and Send Template

Klaviyo::Templates.send_template(template_id, from_email, from_name, subject, to, opts)

Example:

template_id = 'TEMPLATE_ID'
from_email = '[email protected]'
from_name = 'George Washington'
subject = 'Happy Fourth!'
to = '[email protected]'
context = {'name': 'George Washington', 'state': 'VA'}

opts = {
  form_params: {
    context: context.to_json
  }
}

response = Klaviyo::Templates.send_template(template_id, from_email, from_name, subject, to, opts)

Update Template

Klaviyo::Templates.update_template(template_id, opts)

Example:

template_id = 'TEMPLATE_ID'
opts = {
  form_params: {
    name: 'New Template Name',
    html: '<html><body><p>This is an email for {{ email }}.</p></body></html>'
  }
}

response = Klaviyo::Templates.update_template(template_id, opts)

TrackIdentify

Identify Profile (Legacy)

Klaviyo::TrackIdentify.identify_get(data)

Example:

require 'base64'
identify_payload = {
  'token': 'PUBLIC_KEY', 
  'properties': {
    '$email': '[email protected]',
    '$first_name': 'Abraham',
    '$last_name': 'Lincoln',
    '$city': 'Springfield',
    '$region': 'Illinois'
  }
}

encoded_payload = Base64.encode64(identify_payload.to_json).encode(Encoding::UTF_8)
response = Klaviyo::TrackIdentify.identify_get(encoded_payload)

Identify Profile

Klaviyo::TrackIdentify.identify_post(data)

Example:

identify_payload = {
  'token': 'PUBLIC_KEY', 
  'properties': {
    '$email': '[email protected]',
    '$first_name': 'Abraham',
    '$last_name': 'Lincoln',
    '$city': 'Springfield',
    '$region': 'Illinois'
  }
}

data = identify_payload.to_json
response = Klaviyo::TrackIdentify.identify_post(data)

Track Profile Activity (Legacy)

Klaviyo::TrackIdentify.track_get(data)

Example:

require 'base64'
track_payload = {
  'token': 'PUBLIC_KEY',
  'event': 'Ordered Product',
  'customer_properties': {
    '$email': '[email protected]'
  },
  'properties': {
    'item_name': 'Boots',
    '$value': 100
  }
}

encoded_payload = Base64.encode64(track_payload.to_json).encode(Encoding::UTF_8)
response = Klaviyo::TrackIdentify.track_get(encoded_payload)

Track Profile Activity

Klaviyo::TrackIdentify.track_post(data)

Example:

track_payload = {
  'token': 'PUBLIC_KEY',
  'event': 'Ordered Product',
  'customer_properties': {
    '$email': '[email protected]'
  },
  'properties': {
    'item_name': 'Boots',
    '$value': 100
  }
}

data = track_payload.to_json
response = Klaviyo::TrackIdentify.track_post(data)

Appendix

Limitations

• The api_key is set at the global level: this means that if you manage multiple stores, you will need to run the code for each store in a different environment.