Can I use ActiveCampaign as a CLI?

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

Can I expose ActiveCampaign through MCP?

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

Where are ActiveCampaign credentials stored?

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

Can I deny write access for ActiveCampaign MCP tools?

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

productivity

ActiveCampaign Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.activecampaign.list_contacts({limit = 1, offset = 1, search = "example_search", filters = "example_filters"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("activecampaign"))' --json
kosmo integrations:lua --eval 'print(docs.read("activecampaign.list_contacts"))' --json

Workflow file

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

workflow.lua

local activecampaign = app.integrations.activecampaign
local result = activecampaign.list_contacts({limit = 1, offset = 1, search = "example_search", filters = "example_filters"})

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

MCP-only Lua

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

ActiveCampaign Lua API Reference

Namespace: app.integrations.activecampaign

This integration targets the ActiveCampaign API v3 under https://{account}.api-us1.com/api/3 and sends credentials with the Api-Token header. It covers common contact, tag, custom-field, list, deal, campaign, account, automation, note, user, and generic API workflows.

Contacts And Lists

local contacts = app.integrations.activecampaign.list_contacts({
  limit = 25,
  search = "person@example.test"
})

local contact = app.integrations.activecampaign.get_contact({ contact_id = 123 })

local synced = app.integrations.activecampaign.sync_contact({
  contact = {
    email = "person@example.test",
    firstName = "Person",
    lastName = "Example",
    phone = "+15555550100"
  }
})

app.integrations.activecampaign.add_contact_to_list({
  contact_id = 123,
  list_id = 5
})

Use sync_contact when you want ActiveCampaign to create or update by email. Use create_contact only when you explicitly want the create endpoint.

Tags And Custom Fields

local tags = app.integrations.activecampaign.list_tags({
  params = { limit = 100 }
})

local tag = app.integrations.activecampaign.create_tag({
  tag = "vip",
  description = "High-value contact"
})

app.integrations.activecampaign.add_contact_tag({
  contact_id = 123,
  tag_id = tag.tag.id
})

local fields = app.integrations.activecampaign.list_fields({
  params = { limit = 100 }
})

app.integrations.activecampaign.create_field_value({
  contact_id = 123,
  field_id = 42,
  value = "Enterprise"
})

remove_contact_tag expects the contact-tag relationship ID, not the tag ID. List a contact’s tags first when you need that relationship ID.

Deals And Accounts

local pipelines = app.integrations.activecampaign.list_deal_groups({})
local stages = app.integrations.activecampaign.list_deal_stages({})

local deal = app.integrations.activecampaign.create_deal({
  title = "Expansion",
  value = 25000,
  contact_id = 123,
  stage = 7
})

local accounts = app.integrations.activecampaign.list_accounts({
  params = { limit = 50 }
})

Deal status values follow ActiveCampaign’s v3 API: 0 open, 1 won, 2 lost. Some accounts require Deals permissions for deal endpoints.

Campaigns, Messages, Automations, And Users

local campaigns = app.integrations.activecampaign.list_campaigns({
  params = { limit = 20 }
})

local campaign = app.integrations.activecampaign.get_campaign({
  campaign_id = 123
})

local messages = app.integrations.activecampaign.list_messages({})
local automations = app.integrations.activecampaign.list_automations({})
local user = app.integrations.activecampaign.get_current_user({})

Campaign and message tools are read-only wrappers for inspection/reporting workflows. Use generic API helpers for less-common campaign subresources.

Generic API Helpers

local raw = app.integrations.activecampaign.api_get({
  path = "/contacts",
  params = { limit = 1 }
})

local posted = app.integrations.activecampaign.api_post({
  path = "/tags",
  payload = { tag = { tag = "customer" } }
})

Generic helpers call documented /api/3 endpoints directly:

api_get({ path, params? })
api_post({ path, payload? })
api_put({ path, payload? })
api_delete({ path, payload? })

Prefer named tools where available because they validate IDs and shape the common payloads.

Multi-Account Usage

app.integrations.activecampaign.list_contacts({})
app.integrations.activecampaign.default.list_contacts({})
app.integrations.activecampaign.production.list_contacts({})

All account namespaces expose the same tools; only stored credentials differ.

Raw agent markdown

# ActiveCampaign Lua API Reference

Namespace: `app.integrations.activecampaign`

This integration targets the ActiveCampaign API v3 under `https://{account}.api-us1.com/api/3` and sends credentials with the `Api-Token` header. It covers common contact, tag, custom-field, list, deal, campaign, account, automation, note, user, and generic API workflows.

## Contacts And Lists

```lua
local contacts = app.integrations.activecampaign.list_contacts({
  limit = 25,
  search = "person@example.test"
})

local contact = app.integrations.activecampaign.get_contact({ contact_id = 123 })

local synced = app.integrations.activecampaign.sync_contact({
  contact = {
    email = "person@example.test",
    firstName = "Person",
    lastName = "Example",
    phone = "+15555550100"
  }
})

app.integrations.activecampaign.add_contact_to_list({
  contact_id = 123,
  list_id = 5
})
```

Use `sync_contact` when you want ActiveCampaign to create or update by email. Use `create_contact` only when you explicitly want the create endpoint.

## Tags And Custom Fields

```lua
local tags = app.integrations.activecampaign.list_tags({
  params = { limit = 100 }
})

local tag = app.integrations.activecampaign.create_tag({
  tag = "vip",
  description = "High-value contact"
})

app.integrations.activecampaign.add_contact_tag({
  contact_id = 123,
  tag_id = tag.tag.id
})

local fields = app.integrations.activecampaign.list_fields({
  params = { limit = 100 }
})

app.integrations.activecampaign.create_field_value({
  contact_id = 123,
  field_id = 42,
  value = "Enterprise"
})
```

`remove_contact_tag` expects the contact-tag relationship ID, not the tag ID. List a contact's tags first when you need that relationship ID.

## Deals And Accounts

```lua
local pipelines = app.integrations.activecampaign.list_deal_groups({})
local stages = app.integrations.activecampaign.list_deal_stages({})

local deal = app.integrations.activecampaign.create_deal({
  title = "Expansion",
  value = 25000,
  contact_id = 123,
  stage = 7
})

local accounts = app.integrations.activecampaign.list_accounts({
  params = { limit = 50 }
})
```

Deal status values follow ActiveCampaign's v3 API: `0` open, `1` won, `2` lost. Some accounts require Deals permissions for deal endpoints.

## Campaigns, Messages, Automations, And Users

```lua
local campaigns = app.integrations.activecampaign.list_campaigns({
  params = { limit = 20 }
})

local campaign = app.integrations.activecampaign.get_campaign({
  campaign_id = 123
})

local messages = app.integrations.activecampaign.list_messages({})
local automations = app.integrations.activecampaign.list_automations({})
local user = app.integrations.activecampaign.get_current_user({})
```

Campaign and message tools are read-only wrappers for inspection/reporting workflows. Use generic API helpers for less-common campaign subresources.

## Generic API Helpers

```lua
local raw = app.integrations.activecampaign.api_get({
  path = "/contacts",
  params = { limit = 1 }
})

local posted = app.integrations.activecampaign.api_post({
  path = "/tags",
  payload = { tag = { tag = "customer" } }
})
```

Generic helpers call documented `/api/3` endpoints directly:

- `api_get({ path, params? })`
- `api_post({ path, payload? })`
- `api_put({ path, payload? })`
- `api_delete({ path, payload? })`

Prefer named tools where available because they validate IDs and shape the common payloads.

## Multi-Account Usage

```lua
app.integrations.activecampaign.list_contacts({})
app.integrations.activecampaign.default.list_contacts({})
app.integrations.activecampaign.production.list_contacts({})
```

All account namespaces expose the same tools; only stored credentials differ.

Metadata-derived Lua example

local result = app.integrations.activecampaign.list_contacts({limit = 1, offset = 1, search = "example_search", filters = "example_filters"})
print(result)

Functions

list_contacts Read

List contacts from ActiveCampaign. Supports pagination, search by email or name, and filtering by list, status, and other criteria.

Lua path: app.integrations.activecampaign.list_contacts
Full name: activecampaign.activecampaign_list_contacts

Parameter	Type	Required	Description
`limit`	integer	no	Number of contacts to return per page (default: 20, max: 100).
`offset`	integer	no	Offset for pagination (e.g., 20 to skip the first page).
`search`	string	no	Search term to filter contacts by email, name, or other fields.
`filters`	object	no	Additional filters as key-value pairs (e.g., {"status": "-1"} for unsubscribed, {"listid": 5}).

get_contact Read

Get details of a specific ActiveCampaign contact by ID, including email, name, phone, and custom fields.

Lua path: app.integrations.activecampaign.get_contact
Full name: activecampaign.activecampaign_get_contact

Parameter	Type	Required	Description
`contact_id`	integer	yes	The ActiveCampaign contact ID.

create_contact Write

Create a new contact in ActiveCampaign. Requires an email address; firstName, lastName, and phone are optional.

Lua path: app.integrations.activecampaign.create_contact
Full name: activecampaign.activecampaign_create_contact

Parameter	Type	Required	Description
`email`	string	yes	The contact email address.
`firstName`	string	no	The contact first name.
`lastName`	string	no	The contact last name.
`phone`	string	no	The contact phone number.

update_contact Write

Update an existing contact in ActiveCampaign. Provide the contact ID and any fields to update (email, firstName, lastName, phone, or custom fields).

Lua path: app.integrations.activecampaign.update_contact
Full name: activecampaign.activecampaign_update_contact

Parameter	Type	Required	Description
`contact_id`	integer	yes	The ActiveCampaign contact ID to update.
`email`	string	no	Updated email address.
`firstName`	string	no	Updated first name.
`lastName`	string	no	Updated last name.
`phone`	string	no	Updated phone number.
`fields`	object	no	Custom field values as key-value pairs (e.g., {"field[1]": "value"}).

delete_contact Write

Delete a contact from ActiveCampaign. This action is permanent and cannot be undone.

Lua path: app.integrations.activecampaign.delete_contact
Full name: activecampaign.activecampaign_delete_contact

Parameter	Type	Required	Description
`contact_id`	integer	yes	The ActiveCampaign contact ID to delete.

list_lists Read

List all contact lists in ActiveCampaign. Returns list IDs, names, and subscriber counts.

Lua path: app.integrations.activecampaign.list_lists
Full name: activecampaign.activecampaign_list_lists

Parameter	Type	Required	Description
`limit`	integer	no	Number of lists to return per page (default: 20).
`offset`	integer	no	Offset for pagination.

get_list Read

Get details of a specific ActiveCampaign list by ID, including name, subscriber count, and settings.

Lua path: app.integrations.activecampaign.get_list
Full name: activecampaign.activecampaign_get_list

Parameter	Type	Required	Description
`list_id`	integer	yes	The ActiveCampaign list ID.

add_contact_list Write

Subscribe a contact to a list in ActiveCampaign. The contact will be added to the specified list.

Lua path: app.integrations.activecampaign.add_contact_list
Full name: activecampaign.activecampaign_add_contact_to_list

Parameter	Type	Required	Description
`contact_id`	integer	yes	The ActiveCampaign contact ID.
`list_id`	integer	yes	The ActiveCampaign list ID to subscribe the contact to.

remove_contact_from_list Write

Unsubscribe a contact from a list in ActiveCampaign. The contact will be removed from the specified list.

Lua path: app.integrations.activecampaign.remove_contact_from_list
Full name: activecampaign.activecampaign_remove_contact_from_list

Parameter	Type	Required	Description
`contact_id`	integer	yes	The ActiveCampaign contact ID.
`list_id`	integer	yes	The ActiveCampaign list ID to unsubscribe the contact from.

list_deals Read

List deals from ActiveCampaign. Supports pagination, search, and filtering by pipeline, stage, status, or owner.

Lua path: app.integrations.activecampaign.list_deals
Full name: activecampaign.activecampaign_list_deals

Parameter	Type	Required	Description
`limit`	integer	no	Number of deals to return per page (default: 20).
`offset`	integer	no	Offset for pagination.
`search`	string	no	Search term to filter deals by title.
`filters`	object	no	Additional filters (e.g., {"pipeline": 1, "stage": 2, "status": 0}, status: 0=open, 1=won, 2=lost, 3=abandoned).

get_deal Read

Get details of a specific ActiveCampaign deal by ID, including title, value, stage, pipeline, and associated contact.

Lua path: app.integrations.activecampaign.get_deal
Full name: activecampaign.activecampaign_get_deal

Parameter	Type	Required	Description
`deal_id`	integer	yes	The ActiveCampaign deal ID.

create_deal Write

Create a new deal in ActiveCampaign. Requires a title, value, contact ID, and stage. Optionally specify a pipeline.

Lua path: app.integrations.activecampaign.create_deal
Full name: activecampaign.activecampaign_create_deal

Parameter	Type	Required	Description
`title`	string	yes	The deal title.
`value`	number	yes	The deal value (e.g., 5000 for $5,000).
`contact_id`	integer	yes	The associated contact ID.
`stage`	integer	yes	The pipeline stage ID to place the deal in.
`pipeline`	integer	no	The pipeline ID. If omitted, the default pipeline is used.

update_deal Write

Update an existing deal in ActiveCampaign. Provide the deal ID and any fields to update (title, value, stage, pipeline, status, etc.).

Lua path: app.integrations.activecampaign.update_deal
Full name: activecampaign.activecampaign_update_deal

Parameter	Type	Required	Description
`deal_id`	integer	yes	The ActiveCampaign deal ID to update.
`title`	string	no	Updated deal title.
`value`	number	no	Updated deal value.
`stage`	integer	no	Updated pipeline stage ID.
`pipeline`	integer	no	Updated pipeline ID.
`status`	integer	no	Deal status: 0=open, 1=won, 2=lost, 3=abandoned.
`owner`	string	no	Updated deal owner (user ID).
`percent`	integer	no	Updated deal percentage (custom field).
`fields`	object	no	Additional custom fields as key-value pairs.

list_automations Read

List all automations in ActiveCampaign. Returns automation IDs, names, status, and trigger counts.

Lua path: app.integrations.activecampaign.list_automations
Full name: activecampaign.activecampaign_list_automations

Parameter	Type	Required	Description
`limit`	integer	no	Number of automations to return per page (default: 20).
`offset`	integer	no	Offset for pagination.

create_note Write

Create a note attached to a contact in ActiveCampaign. Provide the contact ID and note text.

Lua path: app.integrations.activecampaign.create_note
Full name: activecampaign.activecampaign_create_note

Parameter	Type	Required	Description
`contact_id`	integer	yes	The ActiveCampaign contact ID to attach the note to.
`note`	string	yes	The note text content.

get_current_user Read

Get the authenticated ActiveCampaign user.

Lua path: app.integrations.activecampaign.get_current_user
Full name: activecampaign.activecampaign_get_current_user

Parameter	Type	Required	Description
No parameters.

list_users Read

List users in the ActiveCampaign account.

Lua path: app.integrations.activecampaign.list_users
Full name: activecampaign.activecampaign_list_users

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters.

sync_contact Write

Create or update a contact by email using /contact/sync.

Lua path: app.integrations.activecampaign.sync_contact
Full name: activecampaign.activecampaign_sync_contact

Parameter	Type	Required	Description
`contact`	object	yes	ActiveCampaign contact payload.

list_tags Read

List ActiveCampaign tags.

Lua path: app.integrations.activecampaign.list_tags
Full name: activecampaign.activecampaign_list_tags

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters.

create_tag Write

Create an ActiveCampaign tag.

Lua path: app.integrations.activecampaign.create_tag
Full name: activecampaign.activecampaign_create_tag

Parameter	Type	Required	Description
`tag`	string	yes	Tag name.
`description`	string	no	Optional tag description.
`tagType`	string	no	Optional tag type.

add_contact_tag Write

Add an existing tag to an existing contact.

Lua path: app.integrations.activecampaign.add_contact_tag
Full name: activecampaign.activecampaign_add_contact_tag

Parameter	Type	Required	Description
`contact_id`	integer	yes
`tag_id`	integer	yes

remove_contact_tag Write

Remove a tag relationship from a contact by contactTag ID.

Lua path: app.integrations.activecampaign.remove_contact_tag
Full name: activecampaign.activecampaign_remove_contact_tag

Parameter	Type	Required	Description
`contact_tag_id`	integer	yes

list_contact_tags Read

List tags applied to a contact.

Lua path: app.integrations.activecampaign.list_contact_tags
Full name: activecampaign.activecampaign_list_contact_tags

Parameter	Type	Required	Description
`contact_id`	integer	yes

list_fields Read

List custom contact fields.

Lua path: app.integrations.activecampaign.list_fields
Full name: activecampaign.activecampaign_list_fields

Parameter	Type	Required	Description
`params`	object	no	Query parameters such as limit or filters[perstag].

create_field Write

Create a custom contact field.

Lua path: app.integrations.activecampaign.create_field
Full name: activecampaign.activecampaign_create_field

Parameter	Type	Required	Description
`field`	object	yes	ActiveCampaign field payload.

create_field_value Write

Create a contact custom field value.

Lua path: app.integrations.activecampaign.create_field_value
Full name: activecampaign.activecampaign_create_field_value

Parameter	Type	Required
`contact_id`	integer	yes
`field_id`	integer	yes
`value`	string	yes

update_field_value Write

Update an existing contact custom field value.

Lua path: app.integrations.activecampaign.update_field_value
Full name: activecampaign.activecampaign_update_field_value

Parameter	Type	Required	Description
`field_value_id`	integer	yes
`value`	string	yes

list Read

List ActiveCampaign campaigns.

Lua path: app.integrations.activecampaign.list
Full name: activecampaign.activecampaign_list_campaigns

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters.

get Read

Get an ActiveCampaign campaign by ID.

Lua path: app.integrations.activecampaign.get
Full name: activecampaign.activecampaign_get_campaign

Parameter	Type	Required	Description
`campaign_id`	integer	yes

list_messages Read

List ActiveCampaign email messages.

Lua path: app.integrations.activecampaign.list_messages
Full name: activecampaign.activecampaign_list_messages

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters.

list_accounts Read

List ActiveCampaign CRM accounts.

Lua path: app.integrations.activecampaign.list_accounts
Full name: activecampaign.activecampaign_list_accounts

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters.

get_account Read

Get an ActiveCampaign CRM account by ID.

Lua path: app.integrations.activecampaign.get_account
Full name: activecampaign.activecampaign_get_account

Parameter	Type	Required	Description
`account_id`	integer	yes

create_account Write

Create an ActiveCampaign CRM account.

Lua path: app.integrations.activecampaign.create_account
Full name: activecampaign.activecampaign_create_account

Parameter	Type	Required	Description
`account`	object	yes	Account payload.

update_account Write

Update an ActiveCampaign CRM account.

Lua path: app.integrations.activecampaign.update_account
Full name: activecampaign.activecampaign_update_account

Parameter	Type	Required	Description
`account_id`	integer	yes
`account`	object	yes	Account payload.

list_deal_groups Read

List ActiveCampaign deal pipelines.

Lua path: app.integrations.activecampaign.list_deal_groups
Full name: activecampaign.activecampaign_list_deal_groups

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters.

list_deal_stages Read

List ActiveCampaign deal stages.

Lua path: app.integrations.activecampaign.list_deal_stages
Full name: activecampaign.activecampaign_list_deal_stages

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters.

delete_deal Write

Delete an ActiveCampaign deal.

Lua path: app.integrations.activecampaign.delete_deal
Full name: activecampaign.activecampaign_delete_deal

Parameter	Type	Required	Description
`deal_id`	integer	yes

api_get Read

Call a documented ActiveCampaign GET endpoint under /api/3.

Lua path: app.integrations.activecampaign.api_get
Full name: activecampaign.activecampaign_api_get

Parameter	Type	Required	Description
`path`	string	yes
`params`	object	no	Query parameters.

api_post Write

Call a documented ActiveCampaign POST endpoint under /api/3.

Lua path: app.integrations.activecampaign.api_post
Full name: activecampaign.activecampaign_api_post

Parameter	Type	Required	Description
`path`	string	yes
`payload`	object	no	JSON request body.

api_put Write

Call a documented ActiveCampaign PUT endpoint under /api/3.

Lua path: app.integrations.activecampaign.api_put
Full name: activecampaign.activecampaign_api_put

Parameter	Type	Required	Description
`path`	string	yes
`payload`	object	no	JSON request body.

api_delete Write

Call a documented ActiveCampaign DELETE endpoint under /api/3.

Lua path: app.integrations.activecampaign.api_delete
Full name: activecampaign.activecampaign_api_delete

Parameter	Type	Required	Description
`path`	string	yes
`payload`	object	no	Optional JSON request body.