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.

15 functions 10 read 5 write API key auth

Submit Klaviyo feedback View package source

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.

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

`klaviyo_create_profile`

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.

Operation: Write write
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.

`klaviyo_get_profile`

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

Operation: Read read
Full name: klaviyo.klaviyo_get_profile

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

`klaviyo_update_profile`

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.

Operation: Write write
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.

`klaviyo_list_profiles`

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.

Operation: Read read
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.

`klaviyo_subscribe_profile`

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.

Operation: Write write
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.

`klaviyo_create_event`

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.

Operation: Write write
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.

`klaviyo_get_event`

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

Operation: Read read
Full name: klaviyo.klaviyo_get_event

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

`klaviyo_list_events`

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.

Operation: Read read
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.

`klaviyo_list_lists`

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.

Operation: Read read
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.

`klaviyo_create_list`

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

Operation: Write write
Full name: klaviyo.klaviyo_create_list

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

`klaviyo_get_list`

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

Operation: Read read
Full name: klaviyo.klaviyo_get_list

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

`klaviyo_list_list_profiles`

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.

Operation: Read read
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.

`klaviyo_list_flows`

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.

Operation: Read read
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.

`klaviyo_get_flow`

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

Operation: Read read
Full name: klaviyo.klaviyo_get_flow

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

`klaviyo_list_campaigns`

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.

Operation: Read read
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.