KosmoKrator

productivity

Mailchimp Lua API for KosmoKrator Agents

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

18 functions 9 read 9 write API key auth

Lua Namespace

Agents call this integration through app.integrations.mailchimp.*. Use lua_read_doc("integrations.mailchimp") 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.

Client for the Mailchimp Marketing API covering audiences, subscribers, campaigns, segments, and reports — Lua API Reference

mailchimp_add_subscriber

No description.

Parameters

NameTypeRequiredDescription
list_idstringyesThe audience (list) ID to add the subscriber to.
emailstringyesThe subscriber\
statusstringnoSubscription status: subscribed, unsubscribed, cleaned, or pending.
merge_fieldsstringnoMerge field values (e.g. {
tagsarraynoTag names to apply to the subscriber.

Example

local result = app.integrations.mailchimp.mailchimp_add_subscriber({
  list_id = ""
  email = ""
  status = ""
})

mailchimp_add_to_segment

No description.

Parameters

NameTypeRequiredDescription
list_idstringyesThe audience (list) ID.
segment_idstringyesThe segment ID to add the subscriber to.
emailstringyesThe subscriber\

Example

local result = app.integrations.mailchimp.mailchimp_add_to_segment({
  list_id = ""
  segment_id = ""
  email = ""
})

mailchimp_create_audience

No description.

Parameters

NameTypeRequiredDescription
namestringyesThe name of the audience.
contactstringyesContact information for the audience (company, address1, city, state, zip, country).
address1stringnoStreet address.
citystringnoCity.
statestringnoState or province.
zipstringnoPostal / ZIP code.
countrystringnoCountry code (e.g. US).
permission_reminderstringyesPermission reminder text explaining why the subscriber is on this list.
email_type_optionbooleannoWhether to allow subscribers to choose HTML or plain-text email.
campaign_defaultsstringyesDefault values for campaigns created from this audience.
from_emailstringnoDefault
subjectstringnoDefault email subject.
languagestringnoDefault language code (e.g. en).

Example

local result = app.integrations.mailchimp.mailchimp_create_audience({
  name = ""
  contact = ""
  address1 = ""
})

mailchimp_create_campaign

No description.

Parameters

NameTypeRequiredDescription
typestringyesCampaign type: regular, plaintext, absplit, rss, or variate.
list_idstringyesThe audience (list) ID to send the campaign to.
settings_subjectstringnoThe email subject line.
settings_titlestringnoInternal campaign title (visible in Mailchimp dashboard only).
settings_from_namestringnoThe
settings_reply_tostringnoThe reply-to email address.

Example

local result = app.integrations.mailchimp.mailchimp_create_campaign({
  type = ""
  list_id = ""
  settings_subject = ""
})

mailchimp_get_audience

No description.

Parameters

NameTypeRequiredDescription
idstringyesThe audience (list) ID.

Example

local result = app.integrations.mailchimp.mailchimp_get_audience({
  id = ""
})

mailchimp_get_campaign

No description.

Parameters

NameTypeRequiredDescription
idstringyesThe campaign ID.

Example

local result = app.integrations.mailchimp.mailchimp_get_campaign({
  id = ""
})

mailchimp_get_campaign_report

No description.

Parameters

NameTypeRequiredDescription
idstringyesThe campaign ID.

Example

local result = app.integrations.mailchimp.mailchimp_get_campaign_report({
  id = ""
})

mailchimp_get_current_user

No description.

Example

local result = app.integrations.mailchimp.mailchimp_get_current_user({
})

mailchimp_get_subscriber

No description.

Parameters

NameTypeRequiredDescription
list_idstringyesThe audience (list) ID.
emailstringyesThe subscriber\

Example

local result = app.integrations.mailchimp.mailchimp_get_subscriber({
  list_id = ""
  email = ""
})

mailchimp_list_audiences

No description.

Parameters

NameTypeRequiredDescription
countintegernoNumber of audiences to return (max 1000).
offsetintegernoNumber of audiences to skip for pagination.

Example

local result = app.integrations.mailchimp.mailchimp_list_audiences({
  count = 0
  offset = 0
})

mailchimp_list_campaigns

No description.

Parameters

NameTypeRequiredDescription
countintegernoNumber of campaigns to return.
offsetintegernoNumber of campaigns to skip for pagination.
statusstringnoFilter by campaign status.
typestringnoFilter by campaign type.

Example

local result = app.integrations.mailchimp.mailchimp_list_campaigns({
  count = 0
  offset = 0
  status = ""
})

mailchimp_list_segments

No description.

Parameters

NameTypeRequiredDescription
list_idstringyesThe audience (list) ID.
countintegernoNumber of segments to return.

Example

local result = app.integrations.mailchimp.mailchimp_list_segments({
  list_id = ""
  count = 0
})

mailchimp_remove_subscriber

No description.

Parameters

NameTypeRequiredDescription
list_idstringyesThe audience (list) ID.
emailstringyesThe subscriber\

Example

local result = app.integrations.mailchimp.mailchimp_remove_subscriber({
  list_id = ""
  email = ""
})

mailchimp_search_subscribers

No description.

Parameters

NameTypeRequiredDescription
querystringyesSearch query — email address, name, or other subscriber data.
list_idstringnoOptional audience (list) ID to scope the search.
countintegernoNumber of results to return.

Example

local result = app.integrations.mailchimp.mailchimp_search_subscribers({
  query = ""
  list_id = ""
  count = 0
})

mailchimp_send_campaign

No description.

Parameters

NameTypeRequiredDescription
idstringyesThe campaign ID to send.

Example

local result = app.integrations.mailchimp.mailchimp_send_campaign({
  id = ""
})

mailchimp_tag_subscriber

No description.

Parameters

NameTypeRequiredDescription
list_idstringyesThe audience (list) ID.
emailstringyesThe subscriber\
tagsarrayyesArray of tag objects, each with
statusstringno

Example

local result = app.integrations.mailchimp.mailchimp_tag_subscriber({
  list_id = ""
  email = ""
  tags = {}
})

mailchimp_update_campaign

No description.

Parameters

NameTypeRequiredDescription
idstringyesThe campaign ID.
settingsstringyesCampaign settings to update (e.g. subject_line, title, from_name, reply_to).

Example

local result = app.integrations.mailchimp.mailchimp_update_campaign({
  id = ""
  settings = ""
})

mailchimp_update_subscriber

No description.

Parameters

NameTypeRequiredDescription
list_idstringyesThe audience (list) ID.
emailstringyesThe subscriber\
merge_fieldsstringnoMerge field values to update (e.g. {
statusstringnoNew subscription status: subscribed, unsubscribed, cleaned, or pending.

Example

local result = app.integrations.mailchimp.mailchimp_update_subscriber({
  list_id = ""
  email = ""
  merge_fields = ""
})

Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.mailchimp.work.function_name({...})
app.integrations.mailchimp.personal.function_name({...})

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

Raw agent markdown
# Client for the Mailchimp Marketing API covering audiences, subscribers, campaigns, segments, and reports — Lua API Reference

## mailchimp_add_subscriber

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | yes | The audience (list) ID to add the subscriber to. |
| `email` | string | yes | The subscriber\ |
| `status` | string | no | Subscription status: subscribed, unsubscribed, cleaned, or pending. |
| `merge_fields` | string | no | Merge field values (e.g. { |
| `tags` | array | no | Tag names to apply to the subscriber. |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_add_subscriber({
  list_id = ""
  email = ""
  status = ""
})
```

## mailchimp_add_to_segment

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | yes | The audience (list) ID. |
| `segment_id` | string | yes | The segment ID to add the subscriber to. |
| `email` | string | yes | The subscriber\ |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_add_to_segment({
  list_id = ""
  segment_id = ""
  email = ""
})
```

## mailchimp_create_audience

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | The name of the audience. |
| `contact` | string | yes | Contact information for the audience (company, address1, city, state, zip, country). |
| `address1` | string | no | Street address. |
| `city` | string | no | City. |
| `state` | string | no | State or province. |
| `zip` | string | no | Postal / ZIP code. |
| `country` | string | no | Country code (e.g. US). |
| `permission_reminder` | string | yes | Permission reminder text explaining why the subscriber is on this list. |
| `email_type_option` | boolean | no | Whether to allow subscribers to choose HTML or plain-text email. |
| `campaign_defaults` | string | yes | Default values for campaigns created from this audience. |
| `from_email` | string | no | Default  |
| `subject` | string | no | Default email subject. |
| `language` | string | no | Default language code (e.g. en). |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_create_audience({
  name = ""
  contact = ""
  address1 = ""
})
```

## mailchimp_create_campaign

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | yes | Campaign type: regular, plaintext, absplit, rss, or variate. |
| `list_id` | string | yes | The audience (list) ID to send the campaign to. |
| `settings_subject` | string | no | The email subject line. |
| `settings_title` | string | no | Internal campaign title (visible in Mailchimp dashboard only). |
| `settings_from_name` | string | no | The  |
| `settings_reply_to` | string | no | The reply-to email address. |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_create_campaign({
  type = ""
  list_id = ""
  settings_subject = ""
})
```

## mailchimp_get_audience

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The audience (list) ID. |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_get_audience({
  id = ""
})
```

## mailchimp_get_campaign

No description.

### Parameters

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

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_get_campaign({
  id = ""
})
```

## mailchimp_get_campaign_report

No description.

### Parameters

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

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_get_campaign_report({
  id = ""
})
```

## mailchimp_get_current_user

No description.

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_get_current_user({
})
```

## mailchimp_get_subscriber

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | yes | The audience (list) ID. |
| `email` | string | yes | The subscriber\ |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_get_subscriber({
  list_id = ""
  email = ""
})
```

## mailchimp_list_audiences

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `count` | integer | no | Number of audiences to return (max 1000). |
| `offset` | integer | no | Number of audiences to skip for pagination. |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_list_audiences({
  count = 0
  offset = 0
})
```

## mailchimp_list_campaigns

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `count` | integer | no | Number of campaigns to return. |
| `offset` | integer | no | Number of campaigns to skip for pagination. |
| `status` | string | no | Filter by campaign status. |
| `type` | string | no | Filter by campaign type. |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_list_campaigns({
  count = 0
  offset = 0
  status = ""
})
```

## mailchimp_list_segments

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | yes | The audience (list) ID. |
| `count` | integer | no | Number of segments to return. |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_list_segments({
  list_id = ""
  count = 0
})
```

## mailchimp_remove_subscriber

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | yes | The audience (list) ID. |
| `email` | string | yes | The subscriber\ |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_remove_subscriber({
  list_id = ""
  email = ""
})
```

## mailchimp_search_subscribers

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | yes | Search query — email address, name, or other subscriber data. |
| `list_id` | string | no | Optional audience (list) ID to scope the search. |
| `count` | integer | no | Number of results to return. |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_search_subscribers({
  query = ""
  list_id = ""
  count = 0
})
```

## mailchimp_send_campaign

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The campaign ID to send. |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_send_campaign({
  id = ""
})
```

## mailchimp_tag_subscriber

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | yes | The audience (list) ID. |
| `email` | string | yes | The subscriber\ |
| `tags` | array | yes | Array of tag objects, each with  |
| `status` | string | no |  |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_tag_subscriber({
  list_id = ""
  email = ""
  tags = {}
})
```

## mailchimp_update_campaign

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The campaign ID. |
| `settings` | string | yes | Campaign settings to update (e.g. subject_line, title, from_name, reply_to). |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_update_campaign({
  id = ""
  settings = ""
})
```

## mailchimp_update_subscriber

No description.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `list_id` | string | yes | The audience (list) ID. |
| `email` | string | yes | The subscriber\ |
| `merge_fields` | string | no | Merge field values to update (e.g. { |
| `status` | string | no | New subscription status: subscribed, unsubscribed, cleaned, or pending. |

### Example

```lua
local result = app.integrations.mailchimp.mailchimp_update_subscriber({
  list_id = ""
  email = ""
  merge_fields = ""
})
```

---

## Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.mailchimp.work.function_name({...})
app.integrations.mailchimp.personal.function_name({...})
```

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

Metadata-Derived Lua Example

local result = app.integrations.mailchimp.mailchimp_list_audiences({
  count = 1,
  offset = 1
})
print(result)

Functions

mailchimp_list_audiences

List all audiences (lists) in the connected Mailchimp account. Returns each audience's ID, name, subscriber count, and other metadata. Supports offset-based pagination via the count and offset parameters.

Operation
Read read
Full name
mailchimp.mailchimp_list_audiences
ParameterTypeRequiredDescription
count integer no Number of audiences to return (max 1000).
offset integer no Number of audiences to skip for pagination.

mailchimp_get_audience

Get full details for a single Mailchimp audience (list) by its ID. Returns the audience name, contact information, subscription stats, and default settings.

Operation
Read read
Full name
mailchimp.mailchimp_get_audience
ParameterTypeRequiredDescription
id string yes The audience (list) ID.

mailchimp_create_audience

Create a new audience (list) in Mailchimp. Requires a name, contact information, permission reminder, and campaign defaults. Returns the newly created audience with its ID.

Operation
Write write
Full name
mailchimp.mailchimp_create_audience
ParameterTypeRequiredDescription
name string yes The name of the audience.
contact object yes Contact information for the audience (company, address1, city, state, zip, country).
permission_reminder string yes Permission reminder text explaining why the subscriber is on this list.
email_type_option boolean no Whether to allow subscribers to choose HTML or plain-text email.
campaign_defaults object yes Default values for campaigns created from this audience.

mailchimp_add_subscriber

Add a new subscriber or update an existing one in a Mailchimp audience. Uses a PUT upsert based on the subscriber's email address (MD5 hash). Optionally set merge fields and initial tags. Returns the subscriber record with their ID and status.

Operation
Write write
Full name
mailchimp.mailchimp_add_subscriber
ParameterTypeRequiredDescription
list_id string yes The audience (list) ID to add the subscriber to.
email string yes The subscriber's email address.
status string no Subscription status: subscribed, unsubscribed, cleaned, or pending.
merge_fields object no Merge field values (e.g. {"FNAME": "John", "LNAME": "Doe"}).
tags array no Tag names to apply to the subscriber.

mailchimp_get_subscriber

Retrieve a subscriber's details from a Mailchimp audience by their email address. Returns the subscriber's status, merge fields, tags, and activity timestamps.

Operation
Read read
Full name
mailchimp.mailchimp_get_subscriber
ParameterTypeRequiredDescription
list_id string yes The audience (list) ID.
email string yes The subscriber's email address.

mailchimp_update_subscriber

Update an existing subscriber's merge fields and/or status in a Mailchimp audience. Provide the subscriber's email address to identify the record. Returns the updated subscriber details.

Operation
Write write
Full name
mailchimp.mailchimp_update_subscriber
ParameterTypeRequiredDescription
list_id string yes The audience (list) ID.
email string yes The subscriber's email address.
merge_fields object no Merge field values to update (e.g. {"FNAME": "Jane"}).
status string no New subscription status: subscribed, unsubscribed, cleaned, or pending.

mailchimp_search_subscribers

Search for subscribers by email address or name across all audiences or within a specific list. Returns matching subscriber records with their list membership and status.

Operation
Read read
Full name
mailchimp.mailchimp_search_subscribers
ParameterTypeRequiredDescription
query string yes Search query — email address, name, or other subscriber data.
list_id string no Optional audience (list) ID to scope the search.
count integer no Number of results to return.

mailchimp_remove_subscriber

Remove (archive) a subscriber from a Mailchimp audience by their email address. This archives the member; it does not permanently delete it.

Operation
Write write
Full name
mailchimp.mailchimp_remove_subscriber
ParameterTypeRequiredDescription
list_id string yes The audience (list) ID.
email string yes The subscriber's email address.

mailchimp_create_campaign

Create a new campaign in Mailchimp. Requires a campaign type and the target list_id. Optional settings include subject line, title, from name, and reply-to address. Returns the newly created campaign with its ID and web_id.

Operation
Write write
Full name
mailchimp.mailchimp_create_campaign
ParameterTypeRequiredDescription
type string yes Campaign type: regular, plaintext, absplit, rss, or variate.
list_id string yes The audience (list) ID to send the campaign to.
settings_subject string no The email subject line.
settings_title string no Internal campaign title (visible in Mailchimp dashboard only).
settings_from_name string no The "from" name for the email.
settings_reply_to string no The reply-to email address.

mailchimp_get_campaign

Get details for a single Mailchimp campaign by its ID. Returns the campaign type, status, settings, recipient list, and send times.

Operation
Read read
Full name
mailchimp.mailchimp_get_campaign
ParameterTypeRequiredDescription
id string yes The campaign ID.

mailchimp_update_campaign

Update a Mailchimp campaign's settings such as subject line, title, from name, or reply-to. Provide the campaign ID and a settings object with the fields to update. Returns the updated campaign details.

Operation
Write write
Full name
mailchimp.mailchimp_update_campaign
ParameterTypeRequiredDescription
id string yes The campaign ID.
settings object yes Campaign settings to update (e.g. subject_line, title, from_name, reply_to).

mailchimp_send_campaign

Send a Mailchimp campaign immediately. The campaign must already have content configured and be in a "save" or "paused" state. This action is irreversible — once sent, the campaign cannot be recalled.

Operation
Write write
Full name
mailchimp.mailchimp_send_campaign
ParameterTypeRequiredDescription
id string yes The campaign ID to send.

mailchimp_list_campaigns

List campaigns in the Mailchimp account with offset-based pagination and optional filters. Filter by status (save, paused, schedule, sending, sent) or type (regular, plaintext, absplit, rss, variate). Returns each campaign's ID, title, status, and send time.

Operation
Read read
Full name
mailchimp.mailchimp_list_campaigns
ParameterTypeRequiredDescription
count integer no Number of campaigns to return.
offset integer no Number of campaigns to skip for pagination.
status string no Filter by campaign status.
type string no Filter by campaign type.

mailchimp_tag_subscriber

Add or remove tags on a Mailchimp subscriber. Provide an array of tags, each with a name and status ("active" to add, "inactive" to remove).

Operation
Write write
Full name
mailchimp.mailchimp_tag_subscriber
ParameterTypeRequiredDescription
list_id string yes The audience (list) ID.
email string yes The subscriber's email address.
tags array yes Array of tag objects, each with "name" and "status" ("active" or "inactive").

mailchimp_list_segments

List all segments (static and dynamic) for a Mailchimp audience. Returns each segment's ID, name, type, and member count.

Operation
Read read
Full name
mailchimp.mailchimp_list_segments
ParameterTypeRequiredDescription
list_id string yes The audience (list) ID.
count integer no Number of segments to return.

mailchimp_add_to_segment

Add a subscriber to a Mailchimp static segment by email address. The segment must be a static (not dynamic) segment. Returns the segment membership details.

Operation
Write write
Full name
mailchimp.mailchimp_add_to_segment
ParameterTypeRequiredDescription
list_id string yes The audience (list) ID.
segment_id string yes The segment ID to add the subscriber to.
email string yes The subscriber's email address.

mailchimp_get_campaign_report

Get a detailed report for a sent Mailchimp campaign. Returns send stats (emails sent, bounces), open rates, click rates, and industry benchmarks.

Operation
Read read
Full name
mailchimp.mailchimp_get_campaign_report
ParameterTypeRequiredDescription
id string yes The campaign ID.

mailchimp_get_current_user

Get the authenticated Mailchimp user's account information. Returns account name, email, total subscribers, industry stats, and plan details. Useful for verifying the connection and understanding the account scope.

Operation
Read read
Full name
mailchimp.mailchimp_get_current_user
ParameterTypeRequiredDescription
No parameters.