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.

marketing

Mautic Lua API for KosmoKrator Agents

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

9 functions 6 read 3 write Username and password auth

Submit Mautic feedback View package source

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.

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:[email protected]"` 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 = "[email protected]",
  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:[email protected]"` 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 = "[email protected]",
  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.mautic_list_contacts({
  search = "example_search",
  limit = 1,
  start = 1,
  orderBy = "example_orderBy",
  orderByDir = "example_orderByDir"
})
print(result)

Functions

`mautic_list_contacts`

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

Operation: Read read
Full name: mautic.mautic_list_contacts

Parameter	Type	Required	Description
`search`	string	no	Search query to filter contacts (e.g. "email:[email protected]" 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").

`mautic_get_contact`

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

Operation: Read read
Full name: mautic.mautic_get_contact

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

`mautic_create_contact`

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.

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

`mautic_update_contact`

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

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

`mautic_delete_contact`

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

Operation: Write write
Full name: mautic.mautic_delete_contact

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

`mautic_list_emails`

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

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

`mautic_list_segments`

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

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

`mautic_list_forms`

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

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

`mautic_get_current_user`

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

Operation: Read read
Full name: mautic.mautic_get_current_user

Parameter	Type	Required	Description
No parameters.