Klaviyo
Read and write a Klaviyo account - profiles and their consent, lists and segments, events and metrics, campaigns and flows - keeping list membership and marketing consent as the separate things Klaviyo makes them.
Connect a Klaviyo account with a private API key to work its profiles and data end to end: search profiles with Klaviyo's own filter syntax, read a profile with its marketing consent and any suppressions, create or update profiles by email, phone or external id, manage list membership, record events against metrics so flows and segments can act on them, and read lists, segments, campaigns, flows and tags. Consent is handled explicitly and separately from membership: adding someone to a list does not make them mailable, subscribing requires stating where the consent came from, and suppressing can be scoped to one list or to the whole account. Klaviyo publishes no collection totals, so nothing here reports one - lists and segments carry their own profile counts instead. Flows are read-only, because setting one live starts it sending with no undo.
Connect
| Credential field | Required | Where it comes from |
|---|---|---|
Private API key (API_KEY) | Yes | From Settings → API keys in Klaviyo - the PRIVATE key, which starts with pk_ (the short six-character value on the same screen is the public site id and cannot read anything). Its scopes are fixed when it is created, so choose them when you make it. |
Tools
| Tool | Access | What it does |
|---|---|---|
Whoami (yekar.klaviyo.whoami) | Read | The Klaviyo account this connection's private API key belongs to - organization, sending defaults, time zone and currency. Call this first to confirm which account is about to be written to, and to see whether it is a TEST account (test accounts cannot reach real recipients). |
List profiles (yekar.klaviyo.list-profiles) | Read | A page of profiles, optionally narrowed by a Klaviyo filter expression. Every profile carries its MARKETING CONSENT and any suppressions - those, not list membership, decide whether Klaviyo will mail the address. Klaviyo reports no collection total, so this returns a page and a cursor and nothing that looks like a count. |
Get profile (yekar.klaviyo.get-profile) | Read | One profile with its identifiers, custom properties, marketing consent and any suppressions. A suppressed profile receives nothing regardless of what its consent says, so both fields matter. |
Create or update profile (yekar.klaviyo.upsert-profile) | Write | Create a profile, or update it if the identifier already exists (Klaviyo's profile import). Repeating the identical call converges rather than creating a second profile. This grants NO marketing consent: a profile written here cannot be mailed until Subscribe profiles records consent, and it will not appear in a subscribers-only segment before that. |
Update profile (yekar.klaviyo.update-profile) | Write | Update an existing profile by id. Only the fields you send change; a property you simply omit keeps its stored value, so removing one takes unsetProperties. Marketing consent cannot be changed here - that is Subscribe profiles. |
List lists (yekar.klaviyo.list-lists) | Read | The lists in the account with Klaviyo's own profile counts. Remember Klaviyo's model: a list is a MEMBERSHIP, not consent - a profile can be on a list and still be unsubscribed or suppressed, in which case it receives nothing. |
List profiles on a list (yekar.klaviyo.list-list-profiles) | Read | A page of the profiles that belong to a list, each with its marketing consent. Membership and consent are separate in Klaviyo - expect to see unsubscribed and suppressed profiles here, and do not treat their presence as permission to mail them. For the list's SIZE use List lists, which carries Klaviyo's own count. |
Add profiles to list (yekar.klaviyo.add-profiles-to-list) | Write | Add existing profiles to a list by id. This is membership, not consent - Klaviyo will still not mail a profile whose subscription state is not SUBSCRIBED. Recording consent is a separate, explicit tool. |
Remove profiles from list (yekar.klaviyo.remove-profiles-from-list) | Write | Take profiles off a list. The profiles themselves are untouched and their consent is unchanged - this is not an unsubscribe, and using it as one leaves them mailable through every other list and flow they are in. |
Subscribe profiles (yekar.klaviyo.subscribe-profiles) | Write | Record marketing consent for people against a list - the only way to make a profile mailable in Klaviyo. Adding someone to a list does NOT do this. Requires a description of where the consent came from, because that is the audit trail. If the list uses double opt-in, this sends a confirmation and the person is not subscribed until they click it. Only call this where consent genuinely exists. |
Suppress profiles (yekar.klaviyo.suppress-profiles) | Write | Stop mailing people: unsubscribe them from one list, or - with no list id - suppress the addresses account-wide so every campaign and flow skips them. Account-wide suppression is the stronger action and is not undone by re-adding them to a list. Use this rather than removing someone from a list when the intent is 'stop emailing this person'. |
List segments (yekar.klaviyo.list-segments) | Read | The segments in the account with Klaviyo's own profile counts. Watch isProcessing: while it is true Klaviyo is still evaluating the definition, so the count and the membership are both incomplete and should not be reported as final. |
List metrics (yekar.klaviyo.list-metrics) | Read | The event metrics this account tracks - 'Placed Order', 'Viewed Product', whatever its integrations and its own API calls have created - with the integration each comes from. Reading and writing events both need a metric NAME or id from here; Klaviyo creates a new metric for any name it has not seen, so guessing one silently fragments the data. |
List events (yekar.klaviyo.list-events) | Read | A page of events - what people did, as Klaviyo recorded it - filterable by profile, metric or time. Each row carries the metric and profile it belongs to. Klaviyo reports no total for events, so this returns a page and a cursor and nothing that reads as a count. |
Create event (yekar.klaviyo.create-event) | Write | Record an event against a person - what they did, with your own properties. Events are what Klaviyo's flows trigger on and its segments read, so this is how an external system drives Klaviyo. Use the exact metric name from List metrics: an unrecognised name creates a NEW metric rather than failing. Pass uniqueId to make retries safe; without it, calling twice records the event twice. |
List campaigns (yekar.klaviyo.list-campaigns) | Read | Campaigns on the account for one channel, with status, schedule and the segments or lists each targets. Klaviyo requires the channel - there is no 'all channels' listing, so ask twice if the account uses both email and SMS. |
Get campaign (yekar.klaviyo.get-campaign) | Read | One campaign's settings: name, status, channel, schedule, and the audiences it includes and excludes. Performance numbers live in Klaviyo's reporting API, which this integration does not cover - this is the campaign's configuration, not its results. |
List flows (yekar.klaviyo.list-flows) | Read | The automated flows in the account with their status and trigger type. Read-only on purpose: setting a flow live starts it sending to everyone matching its trigger, with no preview and no undo, so this integration shows flows and does not switch them. |
List tags (yekar.klaviyo.list-tags) | Read | The tags used to organize this account's lists, segments, campaigns and flows. Klaviyo tags label those OBJECTS - they are not contact tags, and nothing here puts a tag on a profile. |
Notes
- In Klaviyo, go to Settings → API keys → Create Private API Key.
- Choose the scopes deliberately - read-only if Yekar.AI should only report, or a custom set covering exactly the resources these automations touch. Klaviyo fixes a key's scopes at creation and they cannot be widened afterwards; a 403 later means minting a new key.
- Copy the PRIVATE key (it starts with
pk_) and paste it here. The short six-character value on the same screen is the public site id used by the browser SDK - it will not work. - Call Whoami to confirm which Klaviyo account the key resolves to, and whether it is a test account.
- Add one credential per Klaviyo account.