KosmoKrator

productivity

EmailOctopus Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.email_octopus.list_lists({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("email-octopus"))' --json
kosmo integrations:lua --eval 'print(docs.read("email-octopus.list_lists"))' --json

Workflow file

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

workflow.lua 
local email_octopus = app.integrations.email_octopus
local result = email_octopus.list_lists({})

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

MCP-only Lua

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

EmailOctopus - Lua API Reference

Namespace: app.integrations["email-octopus"]

This integration targets the public EmailOctopus v1.6 API documentation. API v2 exists in EmailOctopus dashboards, but public method-level docs currently expose the v1.6 routes.

Lists, Tags, And Fields

local lists = app.integrations["email-octopus"].emailoctopus_list_lists({
  limit = 25,
  page = 1
})

local list = app.integrations["email-octopus"].emailoctopus_get_list({
  list_id = "list_123"
})

app.integrations["email-octopus"].emailoctopus_create_tag({
  list_id = "list_123",
  tag = "vip"
})

app.integrations["email-octopus"].emailoctopus_create_field({
  list_id = "list_123",
  tag = "Birthday",
  type = "DATE",
  label = "Birthday"
})

List-scoped tools use the configured default list ID when list_id is omitted.

Contacts

app.integrations["email-octopus"].emailoctopus_create_contact({
  list_id = "list_123",
  email_address = "reader@example.test",
  fields = {
    FirstName = "Ada"
  },
  tags = { "vip" },
  status = "SUBSCRIBED"
})

local contact = app.integrations["email-octopus"].emailoctopus_get_contact({
  list_id = "list_123",
  member_id = "member_123"
})

app.integrations["email-octopus"].emailoctopus_update_contact({
  list_id = "list_123",
  member_id = "member_123",
  tags = {
    vip = true,
    oldTag = false
  }
})

For member_id, EmailOctopus accepts either the list contact ID or the MD5 hash of the lowercase email address.

Bulk update accepts up to 100 contact objects:

app.integrations["email-octopus"].emailoctopus_update_contacts_bulk({
  list_id = "list_123",
  data = {
    {
      id = "member_123",
      status = "UNSUBSCRIBED"
    }
  }
})

Campaigns And Reports

local campaigns = app.integrations["email-octopus"].emailoctopus_list_campaigns({
  limit = 50,
  page = 1
})

local summary = app.integrations["email-octopus"].emailoctopus_get_campaign_report_summary({
  campaign_id = "campaign_123",
})

local opened = app.integrations["email-octopus"].emailoctopus_get_campaign_report_opened({
  campaign_id = "campaign_123",
  limit = 100,
  page = 1
})

Report tools exist for summary, links, bounced, clicked, complained, opened, sent, unsubscribed, not-clicked, and not-opened.

Automations

app.integrations["email-octopus"].emailoctopus_start_automation({
  automation_id = "automation_123",
  list_member_id = "member_123"
})

The automation must use EmailOctopus’s “Started via API” trigger.

Multi-Account Usage

app.integrations["email-octopus"].emailoctopus_list_lists({})
app.integrations["email-octopus"].default.emailoctopus_list_lists({})
app.integrations["email-octopus"].newsletter.emailoctopus_list_lists({})

All account namespaces expose the same tools; only credentials and default list ID differ.

Raw agent markdown 
# EmailOctopus - Lua API Reference

Namespace: `app.integrations["email-octopus"]`

This integration targets the public EmailOctopus v1.6 API documentation. API v2
exists in EmailOctopus dashboards, but public method-level docs currently expose
the v1.6 routes.

## Lists, Tags, And Fields

```lua
local lists = app.integrations["email-octopus"].emailoctopus_list_lists({
  limit = 25,
  page = 1
})

local list = app.integrations["email-octopus"].emailoctopus_get_list({
  list_id = "list_123"
})

app.integrations["email-octopus"].emailoctopus_create_tag({
  list_id = "list_123",
  tag = "vip"
})

app.integrations["email-octopus"].emailoctopus_create_field({
  list_id = "list_123",
  tag = "Birthday",
  type = "DATE",
  label = "Birthday"
})
```

List-scoped tools use the configured default list ID when `list_id` is omitted.

## Contacts

```lua
app.integrations["email-octopus"].emailoctopus_create_contact({
  list_id = "list_123",
  email_address = "reader@example.test",
  fields = {
    FirstName = "Ada"
  },
  tags = { "vip" },
  status = "SUBSCRIBED"
})

local contact = app.integrations["email-octopus"].emailoctopus_get_contact({
  list_id = "list_123",
  member_id = "member_123"
})

app.integrations["email-octopus"].emailoctopus_update_contact({
  list_id = "list_123",
  member_id = "member_123",
  tags = {
    vip = true,
    oldTag = false
  }
})
```

For `member_id`, EmailOctopus accepts either the list contact ID or the MD5 hash
of the lowercase email address.

Bulk update accepts up to 100 contact objects:

```lua
app.integrations["email-octopus"].emailoctopus_update_contacts_bulk({
  list_id = "list_123",
  data = {
    {
      id = "member_123",
      status = "UNSUBSCRIBED"
    }
  }
})
```

## Campaigns And Reports

```lua
local campaigns = app.integrations["email-octopus"].emailoctopus_list_campaigns({
  limit = 50,
  page = 1
})

local summary = app.integrations["email-octopus"].emailoctopus_get_campaign_report_summary({
  campaign_id = "campaign_123",
})

local opened = app.integrations["email-octopus"].emailoctopus_get_campaign_report_opened({
  campaign_id = "campaign_123",
  limit = 100,
  page = 1
})
```

Report tools exist for `summary`, `links`, `bounced`, `clicked`, `complained`,
`opened`, `sent`, `unsubscribed`, `not-clicked`, and `not-opened`.

## Automations

```lua
app.integrations["email-octopus"].emailoctopus_start_automation({
  automation_id = "automation_123",
  list_member_id = "member_123"
})
```

The automation must use EmailOctopus's "Started via API" trigger.

## Multi-Account Usage

```lua
app.integrations["email-octopus"].emailoctopus_list_lists({})
app.integrations["email-octopus"].default.emailoctopus_list_lists({})
app.integrations["email-octopus"].newsletter.emailoctopus_list_lists({})
```

All account namespaces expose the same tools; only credentials and default list
ID differ.
Metadata-derived Lua example 
local result = app.integrations.email_octopus.list_lists({})
print(result)

Functions

list_lists Read

List EmailOctopus mailing lists.

Lua path
app.integrations.email_octopus.list_lists
Full name
email-octopus.emailoctopus_list_lists
ParameterTypeRequiredDescription
No parameters.
get_list Read

Get one mailing list.

Lua path
app.integrations.email_octopus.get_list
Full name
email-octopus.emailoctopus_get_list
ParameterTypeRequiredDescription
No parameters.
create_list Write

Create a mailing list.

Lua path
app.integrations.email_octopus.create_list
Full name
email-octopus.emailoctopus_create_list
ParameterTypeRequiredDescription
No parameters.
update_list Write

Update a mailing list.

Lua path
app.integrations.email_octopus.update_list
Full name
email-octopus.emailoctopus_update_list
ParameterTypeRequiredDescription
No parameters.
delete_list Write

Delete a mailing list.

Lua path
app.integrations.email_octopus.delete_list
Full name
email-octopus.emailoctopus_delete_list
ParameterTypeRequiredDescription
No parameters.
list_tags Read

List list tags.

Lua path
app.integrations.email_octopus.list_tags
Full name
email-octopus.emailoctopus_list_tags
ParameterTypeRequiredDescription
No parameters.
create_tag Write

Create a list tag.

Lua path
app.integrations.email_octopus.create_tag
Full name
email-octopus.emailoctopus_create_tag
ParameterTypeRequiredDescription
No parameters.
update_tag Write

Update a list tag.

Lua path
app.integrations.email_octopus.update_tag
Full name
email-octopus.emailoctopus_update_tag
ParameterTypeRequiredDescription
No parameters.
delete_tag Write

Delete a list tag.

Lua path
app.integrations.email_octopus.delete_tag
Full name
email-octopus.emailoctopus_delete_tag
ParameterTypeRequiredDescription
No parameters.
list_contacts Read

List contacts in a mailing list.

Lua path
app.integrations.email_octopus.list_contacts
Full name
email-octopus.emailoctopus_list_contacts
ParameterTypeRequiredDescription
No parameters.
list_subscribed_contacts Read

List subscribed contacts.

Lua path
app.integrations.email_octopus.list_subscribed_contacts
Full name
email-octopus.emailoctopus_list_subscribed_contacts
ParameterTypeRequiredDescription
No parameters.
list_unsubscribed_contacts Read

List unsubscribed contacts.

Lua path
app.integrations.email_octopus.list_unsubscribed_contacts
Full name
email-octopus.emailoctopus_list_unsubscribed_contacts
ParameterTypeRequiredDescription
No parameters.
list_tagged_contacts Read

List contacts by tag.

Lua path
app.integrations.email_octopus.list_tagged_contacts
Full name
email-octopus.emailoctopus_list_tagged_contacts
ParameterTypeRequiredDescription
No parameters.
get_contact Read

Get one list contact.

Lua path
app.integrations.email_octopus.get_contact
Full name
email-octopus.emailoctopus_get_contact
ParameterTypeRequiredDescription
No parameters.
create_contact Write

Create a list contact.

Lua path
app.integrations.email_octopus.create_contact
Full name
email-octopus.emailoctopus_create_contact
ParameterTypeRequiredDescription
No parameters.
update_contact Write

Update one list contact.

Lua path
app.integrations.email_octopus.update_contact
Full name
email-octopus.emailoctopus_update_contact
ParameterTypeRequiredDescription
No parameters.
delete_contact Write

Delete one list contact.

Lua path
app.integrations.email_octopus.delete_contact
Full name
email-octopus.emailoctopus_delete_contact
ParameterTypeRequiredDescription
No parameters.
update_contacts_bulk Write

Update up to 100 contacts.

Lua path
app.integrations.email_octopus.update_contacts_bulk
Full name
email-octopus.emailoctopus_update_contacts_bulk
ParameterTypeRequiredDescription
No parameters.
create_field Write

Create a list field.

Lua path
app.integrations.email_octopus.create_field
Full name
email-octopus.emailoctopus_create_field
ParameterTypeRequiredDescription
No parameters.
update_field Write

Update a list field.

Lua path
app.integrations.email_octopus.update_field
Full name
email-octopus.emailoctopus_update_field
ParameterTypeRequiredDescription
No parameters.
delete_field Write

Delete a list field.

Lua path
app.integrations.email_octopus.delete_field
Full name
email-octopus.emailoctopus_delete_field
ParameterTypeRequiredDescription
No parameters.
list_campaigns Read

List campaigns.

Lua path
app.integrations.email_octopus.list_campaigns
Full name
email-octopus.emailoctopus_list_campaigns
ParameterTypeRequiredDescription
No parameters.
get_campaign Read

Get one campaign.

Lua path
app.integrations.email_octopus.get_campaign
Full name
email-octopus.emailoctopus_get_campaign
ParameterTypeRequiredDescription
No parameters.
get_campaign_report_summary Read

Get the campaign summary report.

Lua path
app.integrations.email_octopus.get_campaign_report_summary
Full name
email-octopus.emailoctopus_get_campaign_report_summary
ParameterTypeRequiredDescription
No parameters.
get_campaign_report_bounced Read

Get campaign bounced contacts.

Lua path
app.integrations.email_octopus.get_campaign_report_bounced
Full name
email-octopus.emailoctopus_get_campaign_report_bounced
ParameterTypeRequiredDescription
No parameters.
get_campaign_report_clicked Read

Get campaign clicked contacts.

Lua path
app.integrations.email_octopus.get_campaign_report_clicked
Full name
email-octopus.emailoctopus_get_campaign_report_clicked
ParameterTypeRequiredDescription
No parameters.
get_campaign_report_complained Read

Get campaign complained contacts.

Lua path
app.integrations.email_octopus.get_campaign_report_complained
Full name
email-octopus.emailoctopus_get_campaign_report_complained
ParameterTypeRequiredDescription
No parameters.
get_campaign_report_opened Read

Get campaign opened contacts.

Lua path
app.integrations.email_octopus.get_campaign_report_opened
Full name
email-octopus.emailoctopus_get_campaign_report_opened
ParameterTypeRequiredDescription
No parameters.
get_campaign_report_sent Read

Get campaign sent contacts.

Lua path
app.integrations.email_octopus.get_campaign_report_sent
Full name
email-octopus.emailoctopus_get_campaign_report_sent
ParameterTypeRequiredDescription
No parameters.
get_campaign_report_unsubscribed Read

Get campaign unsubscribed contacts.

Lua path
app.integrations.email_octopus.get_campaign_report_unsubscribed
Full name
email-octopus.emailoctopus_get_campaign_report_unsubscribed
ParameterTypeRequiredDescription
No parameters.
get_campaign_report_not_clicked Read

Get contacts who did not click a campaign.

Lua path
app.integrations.email_octopus.get_campaign_report_not_clicked
Full name
email-octopus.emailoctopus_get_campaign_report_not_clicked
ParameterTypeRequiredDescription
No parameters.
get_campaign_report_not_opened Read

Get contacts who did not open a campaign.

Lua path
app.integrations.email_octopus.get_campaign_report_not_opened
Full name
email-octopus.emailoctopus_get_campaign_report_not_opened
ParameterTypeRequiredDescription
No parameters.
start_automation Write

Start an automation for a contact.

Lua path
app.integrations.email_octopus.start_automation
Full name
email-octopus.emailoctopus_start_automation
ParameterTypeRequiredDescription
No parameters.