KosmoKrator

productivity

MailerSend Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.mailer_send.mailersendaddblocklistrecipients({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("mailer-send"))' --json
kosmo integrations:lua --eval 'print(docs.read("mailer-send.mailersendaddblocklistrecipients"))' --json

Workflow file

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

workflow.lua 
local mailer_send = app.integrations.mailer_send
local result = mailer_send.mailersendaddblocklistrecipients({})

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

MCP-only Lua

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

MailerSend - Lua API Reference

Namespace: app.integrations["mailer-send"]

This integration uses the MailerSend API V1 with bearer-token authentication. The API returns MailerSend’s native JSON response shapes, commonly data, links, and meta for list endpoints.

Official API reference: https://developers.mailersend.com/api/v1/

Coverage

The integration exposes tools for:

  • Email sending: single email and bulk email.
  • Messages, templates, domains, DNS records, verification, and domain recipients.
  • Activity and analytics by date, country, user-agent, and reading environment.
  • Recipients and suppression lists for hard bounces, spam complaints, unsubscribes, and on-hold entries.
  • Webhooks and inbound email routes.
  • SMTP users for sending domains.

Sending Email

local result = app.integrations["mailer-send"].send_email({
  from = {email = "noreply@example.test", name = "Example"},
  to = {
    {email = "ada@example.test", name = "Ada"}
  },
  subject = "Welcome",
  html = "<p>Hello Ada</p>",
  text = "Hello Ada",
  tags = {"onboarding"},
  personalization = {
    {
      email = "ada@example.test",
      data = {first_name = "Ada"}
    }
  }
})

For batches, pass an array of full MailerSend email payloads:

local bulk = app.integrations["mailer-send"].send_bulk_email({
  messages = {
    {
      from = {email = "noreply@example.test", name = "Example"},
      to = {{email = "ada@example.test"}},
      subject = "Batch 1",
      text = "Hello"
    }
  }
})

Domains

local domains = app.integrations["mailer-send"].list_domains({
  limit = 25,
  page = 1,
  verified = true
})

local dns = app.integrations["mailer-send"].get_domain_dns_records({
  domain_id = "domain_123"
})

local status = app.integrations["mailer-send"].get_domain_verification_status({
  domain_id = "domain_123"
})

Domain writes include create_domain, delete_domain, and update_domain_settings.

Activity And Analytics

MailerSend activity endpoints require a domain and a Unix timestamp range. Analytics data is retained by MailerSend for a limited period.

local activity = app.integrations["mailer-send"].list_activities({
  domain_id = "domain_123",
  date_from = 1778112000,
  date_to = 1778198400,
  event = {"sent", "delivered"},
  limit = 25
})

local by_date = app.integrations["mailer-send"].get_analytics_by_date({
  date_from = 1778112000,
  date_to = 1778198400,
  event = {"sent", "delivered", "opened"},
  group_by = "days"
})

Open analytics tools are available for country, user-agent, and reading environment.

Suppressions

local bounces = app.integrations["mailer-send"].list_hard_bounces({
  domain_id = "domain_123",
  limit = 25
})

app.integrations["mailer-send"].add_unsubscribes({
  domain_id = "domain_123",
  recipients = {"user@example.test"}
})

Deletion tools accept ids or all = true where the upstream endpoint supports bulk deletion.

Webhooks And Inbound Routes

local webhook = app.integrations["mailer-send"].create_webhook({
  domain_id = "domain_123",
  name = "Events",
  url = "https://example.test/hooks/mailersend",
  events = {"activity.sent", "activity.delivered"},
  enabled = true
})

local route = app.integrations["mailer-send"].create_inbound_route({
  domain_id = "domain_123",
  name = "Support replies",
  domain_enabled = true,
  inbound_domain = "inbound.example.test",
  inbound_priority = 10,
  catch_filter = {type = "catch_all", filters = {}},
  match_filter = {type = "match_all", filters = {}},
  forwards = {
    {type = "webhook", value = "https://example.test/hooks/inbound"}
  }
})

SMTP Users

local smtp_users = app.integrations["mailer-send"].list_smtp_users({
  domain_id = "domain_123"
})

Use SMTP user write tools for setup automation only; generated credentials are sensitive and should not be logged.

Multi-Account Usage

app.integrations["mailer-send"].list_messages({})
app.integrations["mailer-send"].default.list_messages({})
app.integrations["mailer-send"].production.list_domains({})

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

Raw agent markdown 
# MailerSend - Lua API Reference

Namespace: `app.integrations["mailer-send"]`

This integration uses the MailerSend API V1 with bearer-token authentication. The API returns MailerSend's native JSON response shapes, commonly `data`, `links`, and `meta` for list endpoints.

Official API reference: https://developers.mailersend.com/api/v1/

## Coverage

The integration exposes tools for:

- Email sending: single email and bulk email.
- Messages, templates, domains, DNS records, verification, and domain recipients.
- Activity and analytics by date, country, user-agent, and reading environment.
- Recipients and suppression lists for hard bounces, spam complaints, unsubscribes, and on-hold entries.
- Webhooks and inbound email routes.
- SMTP users for sending domains.

## Sending Email

```lua
local result = app.integrations["mailer-send"].send_email({
  from = {email = "noreply@example.test", name = "Example"},
  to = {
    {email = "ada@example.test", name = "Ada"}
  },
  subject = "Welcome",
  html = "<p>Hello Ada</p>",
  text = "Hello Ada",
  tags = {"onboarding"},
  personalization = {
    {
      email = "ada@example.test",
      data = {first_name = "Ada"}
    }
  }
})
```

For batches, pass an array of full MailerSend email payloads:

```lua
local bulk = app.integrations["mailer-send"].send_bulk_email({
  messages = {
    {
      from = {email = "noreply@example.test", name = "Example"},
      to = {{email = "ada@example.test"}},
      subject = "Batch 1",
      text = "Hello"
    }
  }
})
```

## Domains

```lua
local domains = app.integrations["mailer-send"].list_domains({
  limit = 25,
  page = 1,
  verified = true
})

local dns = app.integrations["mailer-send"].get_domain_dns_records({
  domain_id = "domain_123"
})

local status = app.integrations["mailer-send"].get_domain_verification_status({
  domain_id = "domain_123"
})
```

Domain writes include `create_domain`, `delete_domain`, and `update_domain_settings`.

## Activity And Analytics

MailerSend activity endpoints require a domain and a Unix timestamp range. Analytics data is retained by MailerSend for a limited period.

```lua
local activity = app.integrations["mailer-send"].list_activities({
  domain_id = "domain_123",
  date_from = 1778112000,
  date_to = 1778198400,
  event = {"sent", "delivered"},
  limit = 25
})

local by_date = app.integrations["mailer-send"].get_analytics_by_date({
  date_from = 1778112000,
  date_to = 1778198400,
  event = {"sent", "delivered", "opened"},
  group_by = "days"
})
```

Open analytics tools are available for country, user-agent, and reading environment.

## Suppressions

```lua
local bounces = app.integrations["mailer-send"].list_hard_bounces({
  domain_id = "domain_123",
  limit = 25
})

app.integrations["mailer-send"].add_unsubscribes({
  domain_id = "domain_123",
  recipients = {"user@example.test"}
})
```

Deletion tools accept `ids` or `all = true` where the upstream endpoint supports bulk deletion.

## Webhooks And Inbound Routes

```lua
local webhook = app.integrations["mailer-send"].create_webhook({
  domain_id = "domain_123",
  name = "Events",
  url = "https://example.test/hooks/mailersend",
  events = {"activity.sent", "activity.delivered"},
  enabled = true
})

local route = app.integrations["mailer-send"].create_inbound_route({
  domain_id = "domain_123",
  name = "Support replies",
  domain_enabled = true,
  inbound_domain = "inbound.example.test",
  inbound_priority = 10,
  catch_filter = {type = "catch_all", filters = {}},
  match_filter = {type = "match_all", filters = {}},
  forwards = {
    {type = "webhook", value = "https://example.test/hooks/inbound"}
  }
})
```

## SMTP Users

```lua
local smtp_users = app.integrations["mailer-send"].list_smtp_users({
  domain_id = "domain_123"
})
```

Use SMTP user write tools for setup automation only; generated credentials are sensitive and should not be logged.

## Multi-Account Usage

```lua
app.integrations["mailer-send"].list_messages({})
app.integrations["mailer-send"].default.list_messages({})
app.integrations["mailer-send"].production.list_domains({})
```

All account namespaces expose the same tools; only credentials differ.
Metadata-derived Lua example 
local result = app.integrations.mailer_send.mailersendaddblocklistrecipients({})
print(result)

Functions

mailersendaddblocklistrecipients Read

Mailersendaddblocklistrecipients

Lua path
app.integrations.mailer_send.mailersendaddblocklistrecipients
Full name
mailer-send.mailersendaddblocklistrecipients
ParameterTypeRequiredDescription
No parameters.
mailersendaddunsubscribes Read

Mailersendaddunsubscribes

Lua path
app.integrations.mailer_send.mailersendaddunsubscribes
Full name
mailer-send.mailersendaddunsubscribes
ParameterTypeRequiredDescription
No parameters.
mailersendcreatedomain Read

Mailersendcreatedomain

Lua path
app.integrations.mailer_send.mailersendcreatedomain
Full name
mailer-send.mailersendcreatedomain
ParameterTypeRequiredDescription
No parameters.
mailersendcreateinboundroute Read

Mailersendcreateinboundroute

Lua path
app.integrations.mailer_send.mailersendcreateinboundroute
Full name
mailer-send.mailersendcreateinboundroute
ParameterTypeRequiredDescription
No parameters.
mailersendcreatesmtpuser Read

Mailersendcreatesmtpuser

Lua path
app.integrations.mailer_send.mailersendcreatesmtpuser
Full name
mailer-send.mailersendcreatesmtpuser
ParameterTypeRequiredDescription
No parameters.
mailersendcreatewebhook Read

Mailersendcreatewebhook

Lua path
app.integrations.mailer_send.mailersendcreatewebhook
Full name
mailer-send.mailersendcreatewebhook
ParameterTypeRequiredDescription
No parameters.
mailersenddeletedomain Read

Mailersenddeletedomain

Lua path
app.integrations.mailer_send.mailersenddeletedomain
Full name
mailer-send.mailersenddeletedomain
ParameterTypeRequiredDescription
No parameters.
mailersenddeleteinboundroute Read

Mailersenddeleteinboundroute

Lua path
app.integrations.mailer_send.mailersenddeleteinboundroute
Full name
mailer-send.mailersenddeleteinboundroute
ParameterTypeRequiredDescription
No parameters.
mailersenddeleteonhold Read

Mailersenddeleteonhold

Lua path
app.integrations.mailer_send.mailersenddeleteonhold
Full name
mailer-send.mailersenddeleteonhold
ParameterTypeRequiredDescription
No parameters.
mailersenddeletesmtpuser Read

Mailersenddeletesmtpuser

Lua path
app.integrations.mailer_send.mailersenddeletesmtpuser
Full name
mailer-send.mailersenddeletesmtpuser
ParameterTypeRequiredDescription
No parameters.
mailersenddeletetemplate Read

Mailersenddeletetemplate

Lua path
app.integrations.mailer_send.mailersenddeletetemplate
Full name
mailer-send.mailersenddeletetemplate
ParameterTypeRequiredDescription
No parameters.
mailersenddeleteunsubscribes Read

Mailersenddeleteunsubscribes

Lua path
app.integrations.mailer_send.mailersenddeleteunsubscribes
Full name
mailer-send.mailersenddeleteunsubscribes
ParameterTypeRequiredDescription
No parameters.
mailersenddeletewebhook Read

Mailersenddeletewebhook

Lua path
app.integrations.mailer_send.mailersenddeletewebhook
Full name
mailer-send.mailersenddeletewebhook
ParameterTypeRequiredDescription
No parameters.
mailersendgetactivity Read

Mailersendgetactivity

Lua path
app.integrations.mailer_send.mailersendgetactivity
Full name
mailer-send.mailersendgetactivity
ParameterTypeRequiredDescription
No parameters.
mailersendgetanalyticsbydate Read

Mailersendgetanalyticsbydate

Lua path
app.integrations.mailer_send.mailersendgetanalyticsbydate
Full name
mailer-send.mailersendgetanalyticsbydate
ParameterTypeRequiredDescription
No parameters.
mailersendgetanalyticsopensbycountry Read

Mailersendgetanalyticsopensbycountry

Lua path
app.integrations.mailer_send.mailersendgetanalyticsopensbycountry
Full name
mailer-send.mailersendgetanalyticsopensbycountry
ParameterTypeRequiredDescription
No parameters.
mailersendgetanalyticsopensbyreadingenvironment Read

Mailersendgetanalyticsopensbyreadingenvironment

Lua path
app.integrations.mailer_send.mailersendgetanalyticsopensbyreadingenvironment
Full name
mailer-send.mailersendgetanalyticsopensbyreadingenvironment
ParameterTypeRequiredDescription
No parameters.
mailersendgetanalyticsopensbyuseragent Read

Mailersendgetanalyticsopensbyuseragent

Lua path
app.integrations.mailer_send.mailersendgetanalyticsopensbyuseragent
Full name
mailer-send.mailersendgetanalyticsopensbyuseragent
ParameterTypeRequiredDescription
No parameters.
get_current_user Write

Verify MailerSend API connectivity by fetching a minimal list of domains. Use this as a health check to confirm the API token is valid and the service is reachable.

Lua path
app.integrations.mailer_send.get_current_user
Full name
mailer-send.mailer_send_get_current_user
ParameterTypeRequiredDescription
No parameters.
mailersendgetdomain Read

Mailersendgetdomain

Lua path
app.integrations.mailer_send.mailersendgetdomain
Full name
mailer-send.mailersendgetdomain
ParameterTypeRequiredDescription
No parameters.
mailersendgetdomaindnsrecords Read

Mailersendgetdomaindnsrecords

Lua path
app.integrations.mailer_send.mailersendgetdomaindnsrecords
Full name
mailer-send.mailersendgetdomaindnsrecords
ParameterTypeRequiredDescription
No parameters.
mailersendgetdomainverificationstatus Read

Mailersendgetdomainverificationstatus

Lua path
app.integrations.mailer_send.mailersendgetdomainverificationstatus
Full name
mailer-send.mailersendgetdomainverificationstatus
ParameterTypeRequiredDescription
No parameters.
mailersendgetinboundroute Read

Mailersendgetinboundroute

Lua path
app.integrations.mailer_send.mailersendgetinboundroute
Full name
mailer-send.mailersendgetinboundroute
ParameterTypeRequiredDescription
No parameters.
get_message Write

Get detailed information about a specific email message by its ID. Returns the full message object including status, recipients, subject, and content.

Lua path
app.integrations.mailer_send.get_message
Full name
mailer-send.mailer_send_get_message
ParameterTypeRequiredDescription
id string yes The unique message ID.
mailersendgetrecipient Read

Mailersendgetrecipient

Lua path
app.integrations.mailer_send.mailersendgetrecipient
Full name
mailer-send.mailersendgetrecipient
ParameterTypeRequiredDescription
No parameters.
mailersendgetsmtpuser Read

Mailersendgetsmtpuser

Lua path
app.integrations.mailer_send.mailersendgetsmtpuser
Full name
mailer-send.mailersendgetsmtpuser
ParameterTypeRequiredDescription
No parameters.
mailersendgettemplate Read

Mailersendgettemplate

Lua path
app.integrations.mailer_send.mailersendgettemplate
Full name
mailer-send.mailersendgettemplate
ParameterTypeRequiredDescription
No parameters.
mailersendgetwebhook Read

Mailersendgetwebhook

Lua path
app.integrations.mailer_send.mailersendgetwebhook
Full name
mailer-send.mailersendgetwebhook
ParameterTypeRequiredDescription
No parameters.
mailersendlistactivities Read

Mailersendlistactivities

Lua path
app.integrations.mailer_send.mailersendlistactivities
Full name
mailer-send.mailersendlistactivities
ParameterTypeRequiredDescription
No parameters.
mailersendlistdomainrecipients Read

Mailersendlistdomainrecipients

Lua path
app.integrations.mailer_send.mailersendlistdomainrecipients
Full name
mailer-send.mailersendlistdomainrecipients
ParameterTypeRequiredDescription
No parameters.
list_domains Write

List sending domains configured in your MailerSend account. Returns domain names, verification statuses, and related settings.

Lua path
app.integrations.mailer_send.list_domains
Full name
mailer-send.mailer_send_list_domains
ParameterTypeRequiredDescription
limit integer no Maximum number of domains to return per page (default: 25).
page integer no Page number for pagination (default: 1).
verified boolean no Filter domains by verification status. Pass true for verified only, false for unverified only.
mailersendlisthardbounces Read

Mailersendlisthardbounces

Lua path
app.integrations.mailer_send.mailersendlisthardbounces
Full name
mailer-send.mailersendlisthardbounces
ParameterTypeRequiredDescription
No parameters.
mailersendlistinboundroutes Read

Mailersendlistinboundroutes

Lua path
app.integrations.mailer_send.mailersendlistinboundroutes
Full name
mailer-send.mailersendlistinboundroutes
ParameterTypeRequiredDescription
No parameters.
list_messages Write

List email messages from your MailerSend account. Returns a paginated list of sent messages with their IDs, subjects, and statuses.

Lua path
app.integrations.mailer_send.list_messages
Full name
mailer-send.mailer_send_list_messages
ParameterTypeRequiredDescription
limit integer no Maximum number of messages to return per page (default: 25).
page integer no Page number for pagination (default: 1).
mailersendlistonhold Read

Mailersendlistonhold

Lua path
app.integrations.mailer_send.mailersendlistonhold
Full name
mailer-send.mailersendlistonhold
ParameterTypeRequiredDescription
No parameters.
list_recipients Write

List recipients (contacts) from your MailerSend account. Returns recipient emails, names, and subscription statuses.

Lua path
app.integrations.mailer_send.list_recipients
Full name
mailer-send.mailer_send_list_recipients
ParameterTypeRequiredDescription
limit integer no Maximum number of recipients to return per page (default: 25).
page integer no Page number for pagination (default: 1).
mailersendlistsmtpusers Read

Mailersendlistsmtpusers

Lua path
app.integrations.mailer_send.mailersendlistsmtpusers
Full name
mailer-send.mailersendlistsmtpusers
ParameterTypeRequiredDescription
No parameters.
mailersendlistspamcomplaints Read

Mailersendlistspamcomplaints

Lua path
app.integrations.mailer_send.mailersendlistspamcomplaints
Full name
mailer-send.mailersendlistspamcomplaints
ParameterTypeRequiredDescription
No parameters.
list_templates Write

List email templates available in your MailerSend account. Returns template IDs, names, and types for use when sending templated emails.

Lua path
app.integrations.mailer_send.list_templates
Full name
mailer-send.mailer_send_list_templates
ParameterTypeRequiredDescription
limit integer no Maximum number of templates to return per page (default: 25).
page integer no Page number for pagination (default: 1).
mailersendlistunsubscribes Read

Mailersendlistunsubscribes

Lua path
app.integrations.mailer_send.mailersendlistunsubscribes
Full name
mailer-send.mailersendlistunsubscribes
ParameterTypeRequiredDescription
No parameters.
mailersendlistwebhooks Read

Mailersendlistwebhooks

Lua path
app.integrations.mailer_send.mailersendlistwebhooks
Full name
mailer-send.mailersendlistwebhooks
ParameterTypeRequiredDescription
No parameters.
bulk_email Write

Send multiple email payloads through the MailerSend bulk email endpoint.

Lua path
app.integrations.mailer_send.bulk_email
Full name
mailer-send.mailer_send_send_bulk_email
ParameterTypeRequiredDescription
messages array yes Array of MailerSend email payloads.
email Write

Send an email through the MailerSend API. Requires a sender (from), one or more recipients (to), and a subject. Optionally provide HTML and/or plain text content.

Lua path
app.integrations.mailer_send.email
Full name
mailer-send.mailer_send_send_email
ParameterTypeRequiredDescription
from object yes Sender object with "email" (required) and "name" (required) keys, e.g. {"email": "noreply@example.com", "name": "Acme Corp"}.
to array yes Array of recipient objects, each with "email" (required) and optional "name" keys, e.g. [{"email": "user@example.com", "name": "John"}].
subject string yes The email subject line.
html string no HTML body content for the email.
text string no Plain text body content for the email.
template_id string no Optional MailerSend template ID.
personalization array no Optional personalization objects.
tags array no Optional message tags.
reply_to object no Optional reply-to object with email and name.
cc array no Optional CC recipient objects.
bcc array no Optional BCC recipient objects.
attachments array no Optional MailerSend attachment objects.
send_at integer no Optional Unix timestamp for scheduled sending.
in_reply_to string no Optional Message-ID this email replies to.
mailersendupdatedomainsettings Read

Mailersendupdatedomainsettings

Lua path
app.integrations.mailer_send.mailersendupdatedomainsettings
Full name
mailer-send.mailersendupdatedomainsettings
ParameterTypeRequiredDescription
No parameters.
mailersendupdateinboundroute Read

Mailersendupdateinboundroute

Lua path
app.integrations.mailer_send.mailersendupdateinboundroute
Full name
mailer-send.mailersendupdateinboundroute
ParameterTypeRequiredDescription
No parameters.
mailersendupdatesmtpuser Read

Mailersendupdatesmtpuser

Lua path
app.integrations.mailer_send.mailersendupdatesmtpuser
Full name
mailer-send.mailersendupdatesmtpuser
ParameterTypeRequiredDescription
No parameters.
mailersendupdatewebhook Read

Mailersendupdatewebhook

Lua path
app.integrations.mailer_send.mailersendupdatewebhook
Full name
mailer-send.mailersendupdatewebhook
ParameterTypeRequiredDescription
No parameters.