Can I use Klaviyo as a CLI?

Yes. KosmoKrator exposes a Klaviyo CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Klaviyo through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Klaviyo tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Klaviyo credentials stored?

Klaviyo credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Klaviyo MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Klaviyo Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Klaviyo KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.klaviyo.*. Use lua_read_doc("integrations.klaviyo") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Klaviyo workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.klaviyo.create_profile({email = "example_email", phone_number = "example_phone_number", first_name = "example_first_name", last_name = "example_last_name", properties = "example_properties"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("klaviyo"))' --json
kosmo integrations:lua --eval 'print(docs.read("klaviyo.create_profile"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local klaviyo = app.integrations.klaviyo
local result = klaviyo.create_profile({email = "example_email", phone_number = "example_phone_number", first_name = "example_first_name", last_name = "example_last_name", properties = "example_properties"})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.klaviyo, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.klaviyo.default.* or app.integrations.klaviyo.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Klaviyo, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Client for the Klaviyo v2 REST API covering profiles, events, lists, flows, and campaigns — Lua API Reference

klaviyo_create_event

No description.

Parameters

Name	Type	Required	Description
`profile_id`	string	yes	The Klaviyo profile ID to associate the event with.
`event_name`	string	yes	The event name (metric name), e.g.
`properties`	string	no	Event properties as key-value pairs.
`value`	number	no	Numeric value associated with the event (e.g. order total).
`time`	string	no	ISO 8601 timestamp of when the event occurred.

Example

local result = app.integrations.klaviyo.klaviyo_create_event({
  profile_id = ""
  event_name = ""
  properties = ""
})

klaviyo_create_list

No description.

Parameters

Name	Type	Required	Description
`name`	string	yes	The name for the new list.

Example

local result = app.integrations.klaviyo.klaviyo_create_list({
  name = ""
})

klaviyo_create_profile

No description.

Parameters

Name	Type	Required	Description
`email`	string	yes	The profile\
`phone_number`	string	no	Phone number in E.164 format (e.g. +1234567890).
`first_name`	string	no	First name of the profile.
`last_name`	string	no	Last name of the profile.
`properties`	string	no	Custom profile properties as key-value pairs.

Example

local result = app.integrations.klaviyo.klaviyo_create_profile({
  email = ""
  phone_number = ""
  first_name = ""
})

klaviyo_get_event

No description.

Parameters

Name	Type	Required	Description
`event_id`	string	yes	The Klaviyo event ID.

Example

local result = app.integrations.klaviyo.klaviyo_get_event({
  event_id = ""
})

klaviyo_get_flow

No description.

Parameters

Name	Type	Required	Description
`flow_id`	string	yes	The Klaviyo flow ID.

Example

local result = app.integrations.klaviyo.klaviyo_get_flow({
  flow_id = ""
})

klaviyo_get_list

No description.

Parameters

Name	Type	Required	Description
`list_id`	string	yes	The Klaviyo list ID.

Example

local result = app.integrations.klaviyo.klaviyo_get_list({
  list_id = ""
})

klaviyo_get_profile

No description.

Parameters

Name	Type	Required	Description
`profile_id`	string	yes	The Klaviyo profile ID.

Example

local result = app.integrations.klaviyo.klaviyo_get_profile({
  profile_id = ""
})

klaviyo_list_campaigns

No description.

Parameters

Name	Type	Required	Description
`limit`	integer	no	Number of campaigns to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

Example

local result = app.integrations.klaviyo.klaviyo_list_campaigns({
  limit = 0
  page_cursor = ""
})

klaviyo_list_events

No description.

Parameters

Name	Type	Required	Description
`filter`	string	no	Klaviyo filter expression (e.g.
`limit`	integer	no	Number of events to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

Example

local result = app.integrations.klaviyo.klaviyo_list_events({
  filter = ""
  limit = 0
  page_cursor = ""
})

klaviyo_list_flows

No description.

Parameters

Name	Type	Required	Description
`limit`	integer	no	Number of flows to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

Example

local result = app.integrations.klaviyo.klaviyo_list_flows({
  limit = 0
  page_cursor = ""
})

klaviyo_list_list_profiles

No description.

Parameters

Name	Type	Required	Description
`list_id`	string	yes	The Klaviyo list ID.
`limit`	integer	no	Number of profiles to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

Example

local result = app.integrations.klaviyo.klaviyo_list_list_profiles({
  list_id = ""
  limit = 0
  page_cursor = ""
})

klaviyo_list_lists

No description.

Parameters

Name	Type	Required	Description
`limit`	integer	no	Number of lists to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

Example

local result = app.integrations.klaviyo.klaviyo_list_lists({
  limit = 0
  page_cursor = ""
})

klaviyo_list_profiles

No description.

Parameters

Name	Type	Required	Description
`limit`	integer	no	Number of profiles to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

Example

local result = app.integrations.klaviyo.klaviyo_list_profiles({
  limit = 0
  page_cursor = ""
})

klaviyo_subscribe_profile

No description.

Parameters

Name	Type	Required	Description
`list_id`	string	yes	The Klaviyo list ID to subscribe the profile to.
`email`	string	yes	The subscriber\
`phone_number`	string	no	Phone number in E.164 format.
`consented_at`	string	no	ISO 8601 timestamp of when consent was given.

Example

local result = app.integrations.klaviyo.klaviyo_subscribe_profile({
  list_id = ""
  email = ""
  phone_number = ""
})

klaviyo_update_profile

No description.

Parameters

Name	Type	Required	Description
`profile_id`	string	yes	The Klaviyo profile ID to update.
`email`	string	no	New email address for the profile.
`phone_number`	string	no	New phone number in E.164 format.
`first_name`	string	no	Updated first name.
`last_name`	string	no	Updated last name.
`properties`	string	no	Custom profile properties to update as key-value pairs.

Example

local result = app.integrations.klaviyo.klaviyo_update_profile({
  profile_id = ""
  email = ""
  phone_number = ""
})

Multi-Account Usage

If you have multiple klaviyo accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.klaviyo.function_name({...})

-- Explicit default (portable across setups)
app.integrations.klaviyo.default.function_name({...})

-- Named accounts
app.integrations.klaviyo.work.function_name({...})
app.integrations.klaviyo.personal.function_name({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown

# Client for the Klaviyo v2 REST API covering profiles, events, lists, flows, and campaigns — Lua API Reference

## klaviyo_create_event

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `profile_id` | string | yes | The Klaviyo profile ID to associate the event with. |
| `event_name` | string | yes | The event name (metric name), e.g.  |
| `properties` | string | no | Event properties as key-value pairs. |
| `value` | number | no | Numeric value associated with the event (e.g. order total). |
| `time` | string | no | ISO 8601 timestamp of when the event occurred. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_create_event({
  profile_id = ""
  event_name = ""
  properties = ""
})
```

## klaviyo_create_list

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | The name for the new list. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_create_list({
  name = ""
})
```

## klaviyo_create_profile

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | yes | The profile\ |
| `phone_number` | string | no | Phone number in E.164 format (e.g. +1234567890). |
| `first_name` | string | no | First name of the profile. |
| `last_name` | string | no | Last name of the profile. |
| `properties` | string | no | Custom profile properties as key-value pairs. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_create_profile({
  email = ""
  phone_number = ""
  first_name = ""
})
```

## klaviyo_get_event

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `event_id` | string | yes | The Klaviyo event ID. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_get_event({
  event_id = ""
})
```

## klaviyo_get_flow

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `flow_id` | string | yes | The Klaviyo flow ID. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_get_flow({
  flow_id = ""
})
```

## klaviyo_get_list

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | yes | The Klaviyo list ID. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_get_list({
  list_id = ""
})
```

## klaviyo_get_profile

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `profile_id` | string | yes | The Klaviyo profile ID. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_get_profile({
  profile_id = ""
})
```

## klaviyo_list_campaigns

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Number of campaigns to return (default 20, max 100). |
| `page_cursor` | string | no | Pagination cursor from a previous response to fetch the next page. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_list_campaigns({
  limit = 0
  page_cursor = ""
})
```

## klaviyo_list_events

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `filter` | string | no | Klaviyo filter expression (e.g.  |
| `limit` | integer | no | Number of events to return (default 20, max 100). |
| `page_cursor` | string | no | Pagination cursor from a previous response to fetch the next page. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_list_events({
  filter = ""
  limit = 0
  page_cursor = ""
})
```

## klaviyo_list_flows

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Number of flows to return (default 20, max 100). |
| `page_cursor` | string | no | Pagination cursor from a previous response to fetch the next page. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_list_flows({
  limit = 0
  page_cursor = ""
})
```

## klaviyo_list_list_profiles

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | yes | The Klaviyo list ID. |
| `limit` | integer | no | Number of profiles to return (default 20, max 100). |
| `page_cursor` | string | no | Pagination cursor from a previous response to fetch the next page. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_list_list_profiles({
  list_id = ""
  limit = 0
  page_cursor = ""
})
```

## klaviyo_list_lists

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Number of lists to return (default 20, max 100). |
| `page_cursor` | string | no | Pagination cursor from a previous response to fetch the next page. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_list_lists({
  limit = 0
  page_cursor = ""
})
```

## klaviyo_list_profiles

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Number of profiles to return (default 20, max 100). |
| `page_cursor` | string | no | Pagination cursor from a previous response to fetch the next page. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_list_profiles({
  limit = 0
  page_cursor = ""
})
```

## klaviyo_subscribe_profile

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | yes | The Klaviyo list ID to subscribe the profile to. |
| `email` | string | yes | The subscriber\ |
| `phone_number` | string | no | Phone number in E.164 format. |
| `consented_at` | string | no | ISO 8601 timestamp of when consent was given. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_subscribe_profile({
  list_id = ""
  email = ""
  phone_number = ""
})
```

## klaviyo_update_profile

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `profile_id` | string | yes | The Klaviyo profile ID to update. |
| `email` | string | no | New email address for the profile. |
| `phone_number` | string | no | New phone number in E.164 format. |
| `first_name` | string | no | Updated first name. |
| `last_name` | string | no | Updated last name. |
| `properties` | string | no | Custom profile properties to update as key-value pairs. |

### Example

```lua
local result = app.integrations.klaviyo.klaviyo_update_profile({
  profile_id = ""
  email = ""
  phone_number = ""
})
```

---

## Multi-Account Usage

If you have multiple klaviyo accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.klaviyo.function_name({...})

-- Explicit default (portable across setups)
app.integrations.klaviyo.default.function_name({...})

-- Named accounts
app.integrations.klaviyo.work.function_name({...})
app.integrations.klaviyo.personal.function_name({...})
```

All functions are identical across accounts — only the credentials differ.

Metadata-derived Lua example

local result = app.integrations.klaviyo.create_profile({email = "example_email", phone_number = "example_phone_number", first_name = "example_first_name", last_name = "example_last_name", properties = "example_properties"})
print(result)

Functions

create_profile Write

Create a new profile in Klaviyo. Provide at least an email address or phone number. Optionally set first name, last name, and custom properties. Returns the newly created profile with its Klaviyo ID.

Lua path: app.integrations.klaviyo.create_profile
Full name: klaviyo.klaviyo_create_profile

Parameter	Type	Required	Description
`email`	string	yes	The profile's email address.
`phone_number`	string	no	Phone number in E.164 format (e.g. +1234567890).
`first_name`	string	no	First name of the profile.
`last_name`	string	no	Last name of the profile.
`properties`	object	no	Custom profile properties as key-value pairs.

get_profile Read

Retrieve a single Klaviyo profile by its ID. Returns the full profile including email, phone number, name, and custom properties.

Lua path: app.integrations.klaviyo.get_profile
Full name: klaviyo.klaviyo_get_profile

Parameter	Type	Required	Description
`profile_id`	string	yes	The Klaviyo profile ID.

update_profile Write

Update an existing Klaviyo profile by ID. Provide only the fields you want to change — omitted fields are left untouched. Supports updating email, phone number, first name, last name, and custom properties.

Lua path: app.integrations.klaviyo.update_profile
Full name: klaviyo.klaviyo_update_profile

Parameter	Type	Required	Description
`profile_id`	string	yes	The Klaviyo profile ID to update.
`email`	string	no	New email address for the profile.
`phone_number`	string	no	New phone number in E.164 format.
`first_name`	string	no	Updated first name.
`last_name`	string	no	Updated last name.
`properties`	object	no	Custom profile properties to update as key-value pairs.

list_profiles Read

List profiles in Klaviyo with cursor-based pagination. Returns each profile's ID, email, phone number, name, and custom properties. Use the page_cursor from a previous response to fetch the next page of results.

Lua path: app.integrations.klaviyo.list_profiles
Full name: klaviyo.klaviyo_list_profiles

Parameter	Type	Required	Description
`limit`	integer	no	Number of profiles to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

subscribe_profile Write

Subscribe a profile to a Klaviyo list using their email address. Requires a valid list ID and the subscriber's email. Optionally provide a phone number and an ISO 8601 consented_at timestamp.

Lua path: app.integrations.klaviyo.subscribe_profile
Full name: klaviyo.klaviyo_subscribe_profile

Parameter	Type	Required	Description
`list_id`	string	yes	The Klaviyo list ID to subscribe the profile to.
`email`	string	yes	The subscriber's email address.
`phone_number`	string	no	Phone number in E.164 format.
`consented_at`	string	no	ISO 8601 timestamp of when consent was given.

create_event Write

Track a new event for an existing Klaviyo profile. Provide the profile ID, event name, and optional properties, numeric value, and timestamp. Events are used to trigger flows and segment profiles based on behaviour.

Lua path: app.integrations.klaviyo.create_event
Full name: klaviyo.klaviyo_create_event

Parameter	Type	Required	Description
`profile_id`	string	yes	The Klaviyo profile ID to associate the event with.
`event_name`	string	yes	The event name (metric name), e.g. "Placed Order".
`properties`	object	no	Event properties as key-value pairs.
`value`	number	no	Numeric value associated with the event (e.g. order total).
`time`	string	no	ISO 8601 timestamp of when the event occurred.

get_event Read

Retrieve a single Klaviyo event by its ID. Returns the event with its metric name, properties, value, timestamp, and associated profile.

Lua path: app.integrations.klaviyo.get_event
Full name: klaviyo.klaviyo_get_event

Parameter	Type	Required	Description
`event_id`	string	yes	The Klaviyo event ID.

list_events Read

List events in Klaviyo with optional filtering and cursor-based pagination. Supports Klaviyo filter expressions (e.g. "greater-than(timestamp,2024-01-01)") to narrow results. Use page_cursor to paginate through large result sets.

Lua path: app.integrations.klaviyo.list_events
Full name: klaviyo.klaviyo_list_events

Parameter	Type	Required	Description
`filter`	string	no	Klaviyo filter expression (e.g. "greater-than(timestamp,2024-01-01)").
`limit`	integer	no	Number of events to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

list_lists Read

List all lists in the connected Klaviyo account. Returns each list's ID, name, and other metadata. Use cursor-based pagination to iterate through large numbers of lists.

Lua path: app.integrations.klaviyo.list_lists
Full name: klaviyo.klaviyo_list_lists

Parameter	Type	Required	Description
`limit`	integer	no	Number of lists to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

create_list Write

Create a new list in Klaviyo. Provide a name for the list. Returns the newly created list with its ID.

Lua path: app.integrations.klaviyo.create_list
Full name: klaviyo.klaviyo_create_list

Parameter	Type	Required	Description
`name`	string	yes	The name for the new list.

get_list Read

Retrieve a single Klaviyo list by its ID. Returns the list's name, member count, and other metadata.

Lua path: app.integrations.klaviyo.get_list
Full name: klaviyo.klaviyo_get_list

Parameter	Type	Required	Description
`list_id`	string	yes	The Klaviyo list ID.

list_list_profiles Read

List profiles that belong to a specific Klaviyo list. Returns each profile's ID, email, phone number, name, and custom properties. Use cursor-based pagination to iterate through large lists.

Lua path: app.integrations.klaviyo.list_list_profiles
Full name: klaviyo.klaviyo_list_list_profiles

Parameter	Type	Required	Description
`list_id`	string	yes	The Klaviyo list ID.
`limit`	integer	no	Number of profiles to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

list_flows Read

List all flows in the connected Klaviyo account. Returns each flow's ID, name, status, and other metadata. Use cursor-based pagination to iterate through large numbers of flows.

Lua path: app.integrations.klaviyo.list_flows
Full name: klaviyo.klaviyo_list_flows

Parameter	Type	Required	Description
`limit`	integer	no	Number of flows to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

get_flow Read

Retrieve a single Klaviyo flow by its ID. Returns the flow's name, status, trigger type, and other metadata.

Lua path: app.integrations.klaviyo.get_flow
Full name: klaviyo.klaviyo_get_flow

Parameter	Type	Required	Description
`flow_id`	string	yes	The Klaviyo flow ID.

list_campaigns Read

List all campaigns in the connected Klaviyo account. Returns each campaign's ID, name, status, and other metadata. Use cursor-based pagination to iterate through large numbers of campaigns.

Lua path: app.integrations.klaviyo.list_campaigns
Full name: klaviyo.klaviyo_list_campaigns

Parameter	Type	Required	Description
`limit`	integer	no	Number of campaigns to return (default 20, max 100).
`page_cursor`	string	no	Pagination cursor from a previous response to fetch the next page.