Giters

jr180180 / klaviyo-ruby-sdk

Klaviyo Ruby SDK is a thin wrapper around our API

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Klaviyo Ruby SDK

  • SDK version: 1.0.3.20220329

Helpful Resources

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.3.20220329.gem

Finally add this to the Gemfile:

gem 'klaviyo_sdk', '~> 1.0.3.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  = 'george.washington@klaviyo.com'
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': 'george.washington@klaviyo.com', 
  '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': 'abraham.lincoln@klaviyo.com'
  }
}

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': 'george.washington@klaviyo.com'
          }
      ]
  }
}

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 = 'george.washington@klaviyo.com'

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': [
      'george.washington@klaviyo.com'
    ]
  }
}

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': ['george.washington@klaviyo.com']}
}

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': ['george.washington@klaviyo.com']}
}
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': ['george.washington@klaviyo.com']}
}

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': 'george.washington@klaviyo.com'
          }
      ]
  }
}

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': [
      'george.washington@klaviyo.com'
    ]
  }
}
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 ID

Klaviyo::Profiles.get_profile_id(query_params: { email: contact_email })

Example:

options = {
  query_params: {
    email: 'contact@email.com'
  }
}

response = Klaviyo::Profiles.get_profile_id(options)

Get Profile

Klaviyo::Profiles.get_profile(person_id)

Example:

person_id = 'PERSON_ID'

response = Klaviyo::Profiles.get_profile(person_id)

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': 'george.washington@klaviyo.com'}
}

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 = 'george.washington@klaviyo.com'
from_name = 'George Washington'
subject = 'Happy Fourth!'
to = 'george.washington@klaviyo.com'
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': 'abraham.lincoln@klaviyo.com',
    '$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': 'abraham.lincoln@klaviyo.com',
    '$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': 'abraham.lincoln@klaviyo.com'
  },
  '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': 'abraham.lincoln@klaviyo.com'
  },
  '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.

About

Klaviyo Ruby SDK is a thin wrapper around our API

Languages

Language:Ruby 100.0%