Can I use Mautic as a CLI?

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

Can I expose Mautic through MCP?

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

Where are Mautic credentials stored?

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

Can I deny write access for Mautic MCP tools?

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

productivity

Mautic Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.mautic.list_contacts({search = "example_search", limit = 1, start = 1, orderBy = "example_orderBy", orderByDir = "example_orderByDir"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("mautic"))' --json
kosmo integrations:lua --eval 'print(docs.read("mautic.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 mautic = app.integrations.mautic
local result = mautic.list_contacts({search = "example_search", limit = 1, start = 1, orderBy = "example_orderBy", orderByDir = "example_orderByDir"})

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

MCP-only Lua

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

Mautic — Lua API Reference

list_contacts

List contacts in Mautic with optional search, filtering, and pagination.

Parameters

Name	Type	Required	Description
`search`	string	no	Search query (e.g. `"email:john@example.com"` or a name)
`limit`	integer	no	Maximum contacts to return (default: 30, max: 100)
`start`	integer	no	Offset for pagination (default: 0)
`orderBy`	string	no	Field to sort by (e.g. `"email"`, `"firstName"`, `"id"`)
`orderByDir`	string	no	Sort direction: `"asc"` or `"desc"`

Example

local result = app.integrations.mautic.list_contacts({
  search = "example.com",
  limit = 10
})

for _, contact in ipairs(result.contacts) do
  print(contact.email .. " - " .. (contact.firstname or "") .. " " .. (contact.lastname or ""))
end

get_contact

Get a single contact by ID, including all fields and tags.

Parameters

Name	Type	Required	Description
`id`	integer	yes	The Mautic contact ID

Example

local result = app.integrations.mautic.get_contact({ id = 42 })
print("Email: " .. result.email)
print("Name: " .. (result.firstname or "") .. " " .. (result.lastname or ""))

create_contact

Create a new contact in Mautic.

Parameters

Name	Type	Required	Description
`email`	string	yes	Email address
`firstname`	string	no	First name
`lastname`	string	no	Last name
`phone`	string	no	Phone number
`company`	string	no	Company name
`position`	string	no	Job title
`tags`	array	no	Tags to assign (e.g. `{"lead", "newsletter"}`)
`owner`	integer	no	User ID of the contact owner

Additional custom fields can be passed as extra parameters.

Example

local result = app.integrations.mautic.create_contact({
  email = "john@example.com",
  firstname = "John",
  lastname = "Doe",
  company = "Acme Corp",
  tags = { "lead", "website-signup" }
})

print("Created contact ID: " .. result.contact.id)

update_contact

Update an existing contact in Mautic.

Parameters

Name	Type	Required	Description
`id`	integer	yes	The 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
`company`	string	no	Updated company name
`position`	string	no	Updated job title
`tags`	array	no	Tags to set (e.g. `{"customer"}`)
`owner`	integer	no	User ID of the contact owner

Additional custom fields can be passed as extra parameters.

Example

local result = app.integrations.mautic.update_contact({
  id = 42,
  firstname = "Jane",
  company = "New Corp",
  tags = { "customer", "vip" }
})

print("Updated contact: " .. result.contact.email)

delete_contact

Delete a contact from Mautic by ID. This action is permanent.

Parameters

Name	Type	Required	Description
`id`	integer	yes	The contact ID to delete

Example

local result = app.integrations.mautic.delete_contact({ id = 42 })
print(result) -- "Contact 42 has been deleted from Mautic."

list_emails

List marketing emails from Mautic.

Parameters

Name	Type	Required	Description
`search`	string	no	Search query to filter emails
`limit`	integer	no	Maximum emails to return (default: 30)
`start`	integer	no	Offset for pagination (default: 0)
`orderBy`	string	no	Field to sort by (e.g. `"subject"`, `"id"`)
`orderByDir`	string	no	Sort direction: `"asc"` or `"desc"`

Example

local result = app.integrations.mautic.list_emails({ limit = 10 })

for _, email in ipairs(result.emails) do
  print(email.name .. " - " .. (email.subject or "no subject"))
end

list_segments

List contact segments (lists) from Mautic.

Parameters

Name	Type	Required	Description
`search`	string	no	Search query to filter segments
`limit`	integer	no	Maximum segments to return (default: 30)
`start`	integer	no	Offset for pagination (default: 0)
`orderBy`	string	no	Field to sort by (e.g. `"name"`, `"id"`)
`orderByDir`	string	no	Sort direction: `"asc"` or `"desc"`

Example

local result = app.integrations.mautic.list_segments({})

for _, segment in ipairs(result.segments) do
  print(segment.name .. " (" .. (segment.alias or "") .. ") - " .. (segment.contactCount or 0) .. " contacts")
end

list_forms

List forms from Mautic.

Parameters

Name	Type	Required	Description
`search`	string	no	Search query to filter forms
`limit`	integer	no	Maximum forms to return (default: 30)
`start`	integer	no	Offset for pagination (default: 0)
`orderBy`	string	no	Field to sort by (e.g. `"name"`, `"id"`)
`orderByDir`	string	no	Sort direction: `"asc"` or `"desc"`

Example

local result = app.integrations.mautic.list_forms({})

for _, form in ipairs(result.forms) do
  print(form.name .. " - " .. (form.submissionCount or 0) .. " submissions")
end

get_current_user

Get the currently authenticated Mautic user. Useful to verify credentials.

Parameters

None.

Example

local result = app.integrations.mautic.get_current_user({})
print("Authenticated as: " .. result.username .. " (" .. (result.email or "") .. ")")

Multi-Account Usage

If you have multiple Mautic instances configured, use account-specific namespaces:

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

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

-- Named accounts
app.integrations.mautic.production.function_name({...})
app.integrations.mautic.staging.function_name({...})

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

Raw agent markdown

# Mautic — Lua API Reference

## list_contacts

List contacts in Mautic with optional search, filtering, and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | string | no | Search query (e.g. `"email:john@example.com"` or a name) |
| `limit` | integer | no | Maximum contacts to return (default: 30, max: 100) |
| `start` | integer | no | Offset for pagination (default: 0) |
| `orderBy` | string | no | Field to sort by (e.g. `"email"`, `"firstName"`, `"id"`) |
| `orderByDir` | string | no | Sort direction: `"asc"` or `"desc"` |

### Example

```lua
local result = app.integrations.mautic.list_contacts({
  search = "example.com",
  limit = 10
})

for _, contact in ipairs(result.contacts) do
  print(contact.email .. " - " .. (contact.firstname or "") .. " " .. (contact.lastname or ""))
end
```

---

## get_contact

Get a single contact by ID, including all fields and tags.

### Parameters

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

### Example

```lua
local result = app.integrations.mautic.get_contact({ id = 42 })
print("Email: " .. result.email)
print("Name: " .. (result.firstname or "") .. " " .. (result.lastname or ""))
```

---

## create_contact

Create a new contact in Mautic.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | yes | Email address |
| `firstname` | string | no | First name |
| `lastname` | string | no | Last name |
| `phone` | string | no | Phone number |
| `company` | string | no | Company name |
| `position` | string | no | Job title |
| `tags` | array | no | Tags to assign (e.g. `{"lead", "newsletter"}`) |
| `owner` | integer | no | User ID of the contact owner |

Additional custom fields can be passed as extra parameters.

### Example

```lua
local result = app.integrations.mautic.create_contact({
  email = "john@example.com",
  firstname = "John",
  lastname = "Doe",
  company = "Acme Corp",
  tags = { "lead", "website-signup" }
})

print("Created contact ID: " .. result.contact.id)
```

---

## update_contact

Update an existing contact in Mautic.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The 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 |
| `company` | string | no | Updated company name |
| `position` | string | no | Updated job title |
| `tags` | array | no | Tags to set (e.g. `{"customer"}`) |
| `owner` | integer | no | User ID of the contact owner |

Additional custom fields can be passed as extra parameters.

### Example

```lua
local result = app.integrations.mautic.update_contact({
  id = 42,
  firstname = "Jane",
  company = "New Corp",
  tags = { "customer", "vip" }
})

print("Updated contact: " .. result.contact.email)
```

---

## delete_contact

Delete a contact from Mautic by ID. This action is permanent.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The contact ID to delete |

### Example

```lua
local result = app.integrations.mautic.delete_contact({ id = 42 })
print(result) -- "Contact 42 has been deleted from Mautic."
```

---

## list_emails

List marketing emails from Mautic.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | string | no | Search query to filter emails |
| `limit` | integer | no | Maximum emails to return (default: 30) |
| `start` | integer | no | Offset for pagination (default: 0) |
| `orderBy` | string | no | Field to sort by (e.g. `"subject"`, `"id"`) |
| `orderByDir` | string | no | Sort direction: `"asc"` or `"desc"` |

### Example

```lua
local result = app.integrations.mautic.list_emails({ limit = 10 })

for _, email in ipairs(result.emails) do
  print(email.name .. " - " .. (email.subject or "no subject"))
end
```

---

## list_segments

List contact segments (lists) from Mautic.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | string | no | Search query to filter segments |
| `limit` | integer | no | Maximum segments to return (default: 30) |
| `start` | integer | no | Offset for pagination (default: 0) |
| `orderBy` | string | no | Field to sort by (e.g. `"name"`, `"id"`) |
| `orderByDir` | string | no | Sort direction: `"asc"` or `"desc"` |

### Example

```lua
local result = app.integrations.mautic.list_segments({})

for _, segment in ipairs(result.segments) do
  print(segment.name .. " (" .. (segment.alias or "") .. ") - " .. (segment.contactCount or 0) .. " contacts")
end
```

---

## list_forms

List forms from Mautic.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | string | no | Search query to filter forms |
| `limit` | integer | no | Maximum forms to return (default: 30) |
| `start` | integer | no | Offset for pagination (default: 0) |
| `orderBy` | string | no | Field to sort by (e.g. `"name"`, `"id"`) |
| `orderByDir` | string | no | Sort direction: `"asc"` or `"desc"` |

### Example

```lua
local result = app.integrations.mautic.list_forms({})

for _, form in ipairs(result.forms) do
  print(form.name .. " - " .. (form.submissionCount or 0) .. " submissions")
end
```

---

## get_current_user

Get the currently authenticated Mautic user. Useful to verify credentials.

### Parameters

None.

### Example

```lua
local result = app.integrations.mautic.get_current_user({})
print("Authenticated as: " .. result.username .. " (" .. (result.email or "") .. ")")
```

---

## Multi-Account Usage

If you have multiple Mautic instances configured, use account-specific namespaces:

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

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

-- Named accounts
app.integrations.mautic.production.function_name({...})
app.integrations.mautic.staging.function_name({...})
```

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

Metadata-derived Lua example

local result = app.integrations.mautic.list_contacts({search = "example_search", limit = 1, start = 1, orderBy = "example_orderBy", orderByDir = "example_orderByDir"})
print(result)

Functions

list_contacts Read

List contacts in Mautic. Supports search, filtering, pagination, and ordering. Returns contact details including email, name, and custom fields.

Lua path: app.integrations.mautic.list_contacts
Full name: mautic.mautic_list_contacts

Parameter	Type	Required	Description
`search`	string	no	Search query to filter contacts (e.g. "email:john@example.com" or a name).
`limit`	integer	no	Maximum number of contacts to return (default: 30, max: 100).
`start`	integer	no	Offset for pagination (default: 0).
`orderBy`	string	no	Field to order by (e.g. "email", "firstName", "lastName", "id").
`orderByDir`	string	no	Order direction: "asc" or "desc" (default: "asc").

get_contact Read

Get detailed information about a single Mautic contact by ID, including all fields and tags.

Lua path: app.integrations.mautic.get_contact
Full name: mautic.mautic_get_contact

Parameter	Type	Required	Description
`id`	integer	yes	The Mautic contact ID.

create_contact Write

Create a new contact in Mautic. Provide at least an email address; additional fields like first name, last name, phone, company, and tags are optional.

Lua path: app.integrations.mautic.create_contact
Full name: mautic.mautic_create_contact

Parameter	Type	Required	Description
`email`	string	yes	Email address for the contact.
`firstname`	string	no	First name.
`lastname`	string	no	Last name.
`phone`	string	no	Phone number.
`company`	string	no	Company name.
`position`	string	no	Job title / position.
`tags`	array	no	Tags to assign (array of tag names, e.g. ["lead", "newsletter"]).
`owner`	integer	no	User ID of the contact owner.

update_contact Write

Update an existing Mautic contact. Provide the contact ID and the fields to update (e.g. email, firstname, lastname, phone, company, tags).

Lua path: app.integrations.mautic.update_contact
Full name: mautic.mautic_update_contact

Parameter	Type	Required	Description
`id`	integer	yes	The Mautic 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.
`company`	string	no	Updated company name.
`position`	string	no	Updated job title / position.
`tags`	array	no	Tags to set (array of tag names, e.g. ["lead", "newsletter"]).
`owner`	integer	no	User ID of the contact owner.

delete_contact Write

Delete a contact from Mautic by ID. This action is permanent and cannot be undone.

Lua path: app.integrations.mautic.delete_contact
Full name: mautic.mautic_delete_contact

Parameter	Type	Required	Description
`id`	integer	yes	The Mautic contact ID to delete.

list_emails Read

List marketing emails from Mautic. Returns email details including name, subject, and publish status.

Lua path: app.integrations.mautic.list_emails
Full name: mautic.mautic_list_emails

Parameter	Type	Required	Description
`search`	string	no	Search query to filter emails.
`limit`	integer	no	Maximum number of emails to return (default: 30).
`start`	integer	no	Offset for pagination (default: 0).
`orderBy`	string	no	Field to order by (e.g. "subject", "id").
`orderByDir`	string	no	Order direction: "asc" or "desc".

list_segments Read

List contact segments (also known as lists or filters) from Mautic. Returns segment names, aliases, and contact counts.

Lua path: app.integrations.mautic.list_segments
Full name: mautic.mautic_list_segments

Parameter	Type	Required	Description
`search`	string	no	Search query to filter segments.
`limit`	integer	no	Maximum number of segments to return (default: 30).
`start`	integer	no	Offset for pagination (default: 0).
`orderBy`	string	no	Field to order by (e.g. "name", "id").
`orderByDir`	string	no	Order direction: "asc" or "desc".

list_forms Read

List forms from Mautic. Returns form names, aliases, submission counts, and publish status.

Lua path: app.integrations.mautic.list_forms
Full name: mautic.mautic_list_forms

Parameter	Type	Required	Description
`search`	string	no	Search query to filter forms.
`limit`	integer	no	Maximum number of forms to return (default: 30).
`start`	integer	no	Offset for pagination (default: 0).
`orderBy`	string	no	Field to order by (e.g. "name", "id").
`orderByDir`	string	no	Order direction: "asc" or "desc".

get_current_user Read

Get details of the currently authenticated Mautic user — useful to verify credentials and identify which user the integration is acting as.

Lua path: app.integrations.mautic.get_current_user
Full name: mautic.mautic_get_current_user

Parameter	Type	Required	Description
No parameters.