KosmoKrator

productivity

Freshmarketer Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.freshmarketer.*. Use lua_read_doc("integrations.freshmarketer") 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 Freshmarketer workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.freshmarketer.list_campaigns({page = 1, limit = 1, status = "example_status"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("freshmarketer"))' --json
kosmo integrations:lua --eval 'print(docs.read("freshmarketer.list_campaigns"))' --json

Workflow file

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

workflow.lua 
local freshmarketer = app.integrations.freshmarketer
local result = freshmarketer.list_campaigns({page = 1, limit = 1, status = "example_status"})

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.freshmarketer, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.freshmarketer.default.* or app.integrations.freshmarketer.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Freshmarketer, 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.

Freshmarketer — Lua API Reference

list_campaigns

List marketing campaigns with pagination and optional status filter.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination (default: 1)
limitintegernoNumber of campaigns per page (default: 20)
statusstringnoFilter by status (e.g., "active", "completed", "draft")

Examples

-- List first 20 campaigns
local result = app.integrations.freshmarketer.list_campaigns({
  page = 1,
  limit = 20
})

-- Filter active campaigns only
local result = app.integrations.freshmarketer.list_campaigns({
  status = "active"
})

get_campaign

Get detailed information about a specific campaign.

Parameters

NameTypeRequiredDescription
idintegeryesThe campaign ID

Example

local result = app.integrations.freshmarketer.get_campaign({
  id = 123
})

create_campaign

Create a new marketing campaign.

Parameters

NameTypeRequiredDescription
namestringyesCampaign name
channel_listarraynoChannels (e.g., {"email"})
scheduleobjectnoSchedule config (e.g., {type = "immediate"} or {type = "scheduled", scheduled_at = "2025-06-01T09:00:00Z"})

Examples

-- Create an immediate email campaign
local result = app.integrations.freshmarketer.create_campaign({
  name = "Welcome Series",
  channel_list = {"email"},
  schedule = { type = "immediate" }
})

-- Create a scheduled campaign
local result = app.integrations.freshmarketer.create_campaign({
  name = "Monthly Newsletter",
  channel_list = {"email"},
  schedule = {
    type = "scheduled",
    scheduled_at = "2025-06-01T09:00:00Z"
  }
})

list_segments

List contact segments with pagination.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
limitintegernoResults per page (default: 20)

Example

local result = app.integrations.freshmarketer.list_segments({
  page = 1,
  limit = 20
})

get_segment

Get details of a specific contact segment.

Parameters

NameTypeRequiredDescription
idintegeryesThe segment ID

Example

local result = app.integrations.freshmarketer.get_segment({
  id = 456
})

list_users

List all users in the Freshmarketer account.

Parameters

None.

Example

local result = app.integrations.freshmarketer.list_users({})

get_current_user

Get the currently authenticated user’s profile.

Parameters

None.

Example

local result = app.integrations.freshmarketer.get_current_user({})
local user = result.user
print("Logged in as: " .. user.email)

Multi-Account Usage

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

-- Default account (always works)
app.integrations.freshmarketer.list_campaigns({page = 1, limit = 20})

-- Explicit default (portable across setups)
app.integrations.freshmarketer.default.list_campaigns({page = 1, limit = 20})

-- Named accounts
app.integrations.freshmarketer.work.list_campaigns({page = 1, limit = 20})
app.integrations.freshmarketer.personal.list_campaigns({page = 1, limit = 20})

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

Raw agent markdown 
# Freshmarketer — Lua API Reference

## list_campaigns

List marketing campaigns with pagination and optional status filter.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (default: 1) |
| `limit` | integer | no | Number of campaigns per page (default: 20) |
| `status` | string | no | Filter by status (e.g., `"active"`, `"completed"`, `"draft"`) |

### Examples

```lua
-- List first 20 campaigns
local result = app.integrations.freshmarketer.list_campaigns({
  page = 1,
  limit = 20
})

-- Filter active campaigns only
local result = app.integrations.freshmarketer.list_campaigns({
  status = "active"
})
```

---

## get_campaign

Get detailed information about a specific campaign.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The campaign ID |

### Example

```lua
local result = app.integrations.freshmarketer.get_campaign({
  id = 123
})
```

---

## create_campaign

Create a new marketing campaign.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | Campaign name |
| `channel_list` | array | no | Channels (e.g., `{"email"}`) |
| `schedule` | object | no | Schedule config (e.g., `{type = "immediate"}` or `{type = "scheduled", scheduled_at = "2025-06-01T09:00:00Z"}`) |

### Examples

```lua
-- Create an immediate email campaign
local result = app.integrations.freshmarketer.create_campaign({
  name = "Welcome Series",
  channel_list = {"email"},
  schedule = { type = "immediate" }
})

-- Create a scheduled campaign
local result = app.integrations.freshmarketer.create_campaign({
  name = "Monthly Newsletter",
  channel_list = {"email"},
  schedule = {
    type = "scheduled",
    scheduled_at = "2025-06-01T09:00:00Z"
  }
})
```

---

## list_segments

List contact segments with pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `limit` | integer | no | Results per page (default: 20) |

### Example

```lua
local result = app.integrations.freshmarketer.list_segments({
  page = 1,
  limit = 20
})
```

---

## get_segment

Get details of a specific contact segment.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The segment ID |

### Example

```lua
local result = app.integrations.freshmarketer.get_segment({
  id = 456
})
```

---

## list_users

List all users in the Freshmarketer account.

### Parameters

None.

### Example

```lua
local result = app.integrations.freshmarketer.list_users({})
```

---

## get_current_user

Get the currently authenticated user's profile.

### Parameters

None.

### Example

```lua
local result = app.integrations.freshmarketer.get_current_user({})
local user = result.user
print("Logged in as: " .. user.email)
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.freshmarketer.list_campaigns({page = 1, limit = 20})

-- Explicit default (portable across setups)
app.integrations.freshmarketer.default.list_campaigns({page = 1, limit = 20})

-- Named accounts
app.integrations.freshmarketer.work.list_campaigns({page = 1, limit = 20})
app.integrations.freshmarketer.personal.list_campaigns({page = 1, limit = 20})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.freshmarketer.list_campaigns({page = 1, limit = 1, status = "example_status"})
print(result)

Functions

list_campaigns Read

List marketing campaigns from Freshmarketer. Supports pagination and filtering by status (e.g., "active", "completed", "draft").

Lua path
app.integrations.freshmarketer.list_campaigns
Full name
freshmarketer.freshmarketer_list_campaigns
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
limit integer no Number of campaigns per page (default: 20).
status string no Filter campaigns by status (e.g., "active", "completed", "draft").
get_campaign Read

Get detailed information about a specific marketing campaign by its ID.

Lua path
app.integrations.freshmarketer.get_campaign
Full name
freshmarketer.freshmarketer_get_campaign
ParameterTypeRequiredDescription
id integer yes The campaign ID to retrieve.
create_campaign Write

Create a new marketing campaign in Freshmarketer. Specify the campaign name, channels (e.g., "email"), and an optional schedule.

Lua path
app.integrations.freshmarketer.create_campaign
Full name
freshmarketer.freshmarketer_create_campaign
ParameterTypeRequiredDescription
name string yes Name of the campaign.
channel_list array no List of channels for the campaign (e.g., ["email"]).
schedule object no Schedule configuration for the campaign (e.g., {"type": "immediate"} or {"type": "scheduled", "scheduled_at": "2025-06-01T09:00:00Z"}).
list_segments Read

List contact segments in Freshmarketer. Supports pagination to browse through all segments.

Lua path
app.integrations.freshmarketer.list_segments
Full name
freshmarketer.freshmarketer_list_segments
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
limit integer no Number of segments per page (default: 20).
get_segment Read

Get detailed information about a specific contact segment by its ID.

Lua path
app.integrations.freshmarketer.get_segment
Full name
freshmarketer.freshmarketer_get_segment
ParameterTypeRequiredDescription
id integer yes The segment ID to retrieve.
list_users Read

List all users in the Freshmarketer account.

Lua path
app.integrations.freshmarketer.list_users
Full name
freshmarketer.freshmarketer_list_users
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Get the profile of the currently authenticated Freshmarketer user.

Lua path
app.integrations.freshmarketer.get_current_user
Full name
freshmarketer.freshmarketer_get_current_user
ParameterTypeRequiredDescription
No parameters.