This SDK is set to be deprecated + retired on 2024-06-30.
We have a NEW python 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
For a comparison between our old and new APIs, check out this guide.
- SDK version: 1.0.7.20220329
This SDK is a thin wrapper around our API. See our API Reference for full documentation on API behavior.
This SDK exactly mirrors the organization and naming convention of the above language-agnostic resources, with a few namespace changes to make it Pythonic (details in Appendix).
This SDK is organized into the following resources:
- Campaigns
- DataPrivacy
- ListsSegments
- Metrics
- Profiles
- Templates
- TrackIdentify
You can install this library using pip
.
Depending on your system configuration, you will need to run one of the following shell commands:
pip install klaviyo-sdk
OR
pip3 install klaviyo-sdk
Alternatively, you can also run this using this repo as source code, by running one of the following shell commands within the cloned repo:
pip install -r requirements.txt
OR
pip3 install -r requirements.txt
and then running python from the cloned repo.
from klaviyo_sdk import Client
client = Client( "YOUR API KEY HERE", max_delay=60, max_retries=3)
NOTE:
- The SDK retries on resolvable errors, namely: rate limits (common) and server errors on klaviyo (rare).
- The keyword arguments define retry behavior; the example is populated with the default values.
max_delay
denotes total delay (in seconds) across all attempts.
metric_id = "METRIC_ID"
count = 100
client.Metrics.metric_export(metric_id, count=count)
This SDK throws an ApiException
error when the server returns a non-2XX
response.
An ApiException
consists of the following attributes:
status
:int
reason
:str
body
:bytes
- this can be decoded into a native python dictionary as follows:
# to decode to a dictionary import json BODY_DICT = json.loads(YOUR_EXCEPTION.body) # to decode to a string BODY_STRING = YOUR_EXCEPTION.body.decode('utf-8')
- this can be decoded into a native python dictionary as follows:
headers
: class 'urllib3._collections.HTTPHeaderDict'- This can be interacted with as a normal dictionary:
- ex:
date = YOUR_EXCEPTION.headers['Date'] keys = YOUR_EXCEPTION.headers.keys() values = YOUR_EXCEPTION.headers.values()
- ex:
- This can be interacted with as a normal dictionary:
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 keyword args are required for the API call to succeed, the API docs above are the source of truth regarding which keyword params are required.
- JSON payloads should be passed in as native python dictionaries.
client.Campaigns.cancel_campaign(campaign_id)
client.Campaigns.clone_campaign(campaign_id, name=name, list_id=list_id)
client.Campaigns.create_campaign(list_id=list_id, template_id=template_id, from_email=from_email, from_name=from_name, subject=subject, name=name, use_smart_sending=use_smart_sending, add_google_analytics=add_google_analytics)
client.Campaigns.get_campaign_info(campaign_id)
client.Campaigns.get_campaign_recipients(campaign_id, count=count, sort=sort, offset=offset)
client.Campaigns.get_campaigns(page=page, count=count)
client.Campaigns.schedule_campaign(campaign_id, send_time=send_time)
client.Campaigns.send_campaign(campaign_id)
client.Campaigns.update_campaign(campaign_id, list_id=list_id, template_id=template_id, from_email=from_email, from_name=from_name, subject=subject, name=name, use_smart_sending=use_smart_sending, add_google_analytics=add_google_analytics)
client.DataPrivacy.request_deletion(body=body)
client.ListsSegments.add_members(list_id, body=body)
client.ListsSegments.create_list(list_name=list_name)
client.ListsSegments.delete_list(list_id)
client.ListsSegments.exclude_globally(email=email)
client.ListsSegments.get_global_exclusions(reason=reason, sort=sort, count=count, page=page)
client.ListsSegments.get_list_exclusions(list_id, marker=marker)
client.ListsSegments.get_list_info(list_id)
client.ListsSegments.get_list_members(list_id, body=body)
client.ListsSegments.get_list_subscriptions(list_id, body=body)
client.ListsSegments.get_lists()
client.ListsSegments.get_members(list_or_segment_id, marker=marker)
client.ListsSegments.get_segment_members(segment_id, body=body)
client.ListsSegments.remove_members(list_id, body=body)
client.ListsSegments.subscribe(list_id, body=body)
client.ListsSegments.unsubscribe(list_id, body=body)
client.ListsSegments.update_list_name(list_id, list_name=list_name)
client.Metrics.get_metrics(page=page, count=count)
client.Metrics.metric_export(metric_id, start_date=start_date, end_date=end_date, unit=unit, measurement=measurement, where=where, by=by, count=count)
client.Metrics.metric_timeline(metric_id, since=since, count=count, sort=sort)
client.Metrics.metrics_timeline(since=since, count=count, sort=sort)
client.Profiles.exchange(body=body)
client.Profiles.get_profile(person_id)
client.Profiles.get_profile_id(email=email, phone_number=phone_number, external_id=external_id)
client.Profiles.profile_metric_timeline(person_id, metric_id, since=since, count=count, sort=sort)
client.Profiles.profile_metrics_timeline(person_id, since=since, count=count, sort=sort)
client.Profiles.update_profile(person_id, params=params)
client.Templates.clone_template(template_id, name=name)
client.Templates.create_template(name=name, html=html)
client.Templates.delete_template(template_id)
client.Templates.get_templates(page=page, count=count)
client.Templates.render_template(template_id, context=context)
client.Templates.send_template(template_id, from_email=from_email, from_name=from_name, subject=subject, to=to, context=context)
client.Templates.update_template(template_id, name=name, html=html)
client.TrackIdentify.identify_get(data)
client.TrackIdentify.identify_post(data=data)
client.TrackIdentify.track_get(data)
client.TrackIdentify.track_post(data=data)
- 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
try:
YOUR_CALL
except Exception as e:
print(e.status)
print(e.reason)
print(e.body)
print(e.headers)
In the interest of making the SDK Pythonic, we made the following namespace changes relative to the language agnostic resources up top.
- dashes
-
become underscores_
- all other non-alphanumeric symbols, including spaces, are removed.
For example:
get-campaigns
becomesget_campaigns
Track & Identify
becomesTrackIdentify
The parameters follow the same naming conventions as the resource groups and operations.
We stick to the following convention for parameters/arguments
- All parameters are passed as function args.
- All optional params, as well as all Body and Form Data params (including required ones), are passed as keyword args.
- All query and path params that are tagged as
required
in the docs are passed as positional args. - There is no need to pass in your private
api_key
for any operations, as it is defined upon client instantiation; public key is still required where.