KosmoKrator

productivity

Amazon SES Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.amazon_ses.send_email({from_email_address = "example_from_email_address", destination = "example_destination", subject = "example_subject", html_body = "example_html_body", text_body = "example_text_body", template_name = "example_template_name", template_data = "example_template_data", reply_to_addresses = "example_reply_to_addresses"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("amazon-ses"))' --json
kosmo integrations:lua --eval 'print(docs.read("amazon-ses.send_email"))' --json

Workflow file

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

workflow.lua 
local amazon_ses = app.integrations.amazon_ses
local result = amazon_ses.send_email({from_email_address = "example_from_email_address", destination = "example_destination", subject = "example_subject", html_body = "example_html_body", text_body = "example_text_body", template_name = "example_template_name", template_data = "example_template_data", reply_to_addresses = "example_reply_to_addresses"})

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

MCP-only Lua

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

Amazon SES Lua Reference

Namespace: amazon-ses

Amazon SES uses AWS Signature Version 4. Configure access_key_id, secret_access_key, region, and optional session_token; do not use bearer tokens.

Core Tools

local sent = app.integrations["amazon-ses"].send_email({
  from_email_address = "hello@example.test",
  destination = { ToAddresses = { "user@example.test" } },
  subject = "Welcome",
  text_body = "Thanks for signing up",
})

local account = app.integrations["amazon-ses"].get_account({})
local identities = app.integrations["amazon-ses"].list_identities({ page_size = 50 })
local identity = app.integrations["amazon-ses"].get_identity({ identity = "example.test" })
local config_sets = app.integrations["amazon-ses"].list_configuration_sets({})
local suppressions = app.integrations["amazon-ses"].list_suppressions({ reason = "BOUNCE" })

Template tools:

app.integrations["amazon-ses"].create_template({
  template_name = "welcome",
  subject = "Welcome, {{name}}",
  html_content = "<p>Hello {{name}}</p>",
  text_content = "Hello {{name}}",
})

local template = app.integrations["amazon-ses"].get_template({
  name = "welcome",
})

app.integrations["amazon-ses"].update_template({
  template_name = "welcome",
  subject = "Updated subject",
  text_content = "Updated text",
})

app.integrations["amazon-ses"].delete_template({
  template_name = "welcome",
})

Generic Signed API

Use generic tools for SES v2 endpoints without a dedicated wrapper. Paths must start with /v2/.

local result = app.integrations["amazon-ses"].api_get({
  path = "/v2/email/account",
})

local updated = app.integrations["amazon-ses"].api_put({
  path = "/v2/email/account/suppression",
  body = {
    SuppressedReasons = { "BOUNCE", "COMPLAINT" },
  },
})

Generic tools return raw SES JSON. Refer to the official SES v2 API reference for request and response shapes.

Raw agent markdown 
# Amazon SES Lua Reference

Namespace: `amazon-ses`

Amazon SES uses AWS Signature Version 4. Configure `access_key_id`,
`secret_access_key`, `region`, and optional `session_token`; do not use bearer
tokens.

## Core Tools

```lua
local sent = app.integrations["amazon-ses"].send_email({
  from_email_address = "hello@example.test",
  destination = { ToAddresses = { "user@example.test" } },
  subject = "Welcome",
  text_body = "Thanks for signing up",
})

local account = app.integrations["amazon-ses"].get_account({})
local identities = app.integrations["amazon-ses"].list_identities({ page_size = 50 })
local identity = app.integrations["amazon-ses"].get_identity({ identity = "example.test" })
local config_sets = app.integrations["amazon-ses"].list_configuration_sets({})
local suppressions = app.integrations["amazon-ses"].list_suppressions({ reason = "BOUNCE" })
```

Template tools:

```lua
app.integrations["amazon-ses"].create_template({
  template_name = "welcome",
  subject = "Welcome, {{name}}",
  html_content = "<p>Hello {{name}}</p>",
  text_content = "Hello {{name}}",
})

local template = app.integrations["amazon-ses"].get_template({
  name = "welcome",
})

app.integrations["amazon-ses"].update_template({
  template_name = "welcome",
  subject = "Updated subject",
  text_content = "Updated text",
})

app.integrations["amazon-ses"].delete_template({
  template_name = "welcome",
})
```

## Generic Signed API

Use generic tools for SES v2 endpoints without a dedicated wrapper. Paths must
start with `/v2/`.

```lua
local result = app.integrations["amazon-ses"].api_get({
  path = "/v2/email/account",
})

local updated = app.integrations["amazon-ses"].api_put({
  path = "/v2/email/account/suppression",
  body = {
    SuppressedReasons = { "BOUNCE", "COMPLAINT" },
  },
})
```

Generic tools return raw SES JSON. Refer to the official SES v2 API reference
for request and response shapes.
Metadata-derived Lua example 
local result = app.integrations.amazon_ses.send_email({from_email_address = "example_from_email_address", destination = "example_destination", subject = "example_subject", html_body = "example_html_body", text_body = "example_text_body", template_name = "example_template_name", template_data = "example_template_data", reply_to_addresses = "example_reply_to_addresses"})
print(result)

Functions

send_email Write

Send an email via Amazon SES. Specify the sender, recipient(s), subject, and body (HTML and/or plain text). Optionally reference a template or add reply-to addresses.

Lua path
app.integrations.amazon_ses.send_email
Full name
amazon-ses.amazonses_send_email
ParameterTypeRequiredDescription
from_email_address string yes The sender email address (must be verified in SES). e.g., "sender@example.com" or "Sender Name <sender@example.com>".
destination object yes Recipient addresses. Object with "ToAddresses" (array), "CcAddresses" (array, optional), and "BccAddresses" (array, optional).
subject string no The email subject line. Required unless using a template.
html_body string no HTML content of the email body.
text_body string no Plain text content of the email body.
template_name string no Name of an existing SES email template to use. If provided, subject/html_body/text_body are ignored.
template_data object no Key-value pairs to substitute into the template placeholders.
reply_to_addresses array no List of email addresses for reply-to.
configuration_set_name string no The SES configuration set to associate with this email for tracking and analytics.
get_account Read

Get Amazon SES account-level sending details.

Lua path
app.integrations.amazon_ses.get_account
Full name
amazon-ses.amazonses_get_account
ParameterTypeRequiredDescription
No parameters.
get_template Read

Retrieve an email template from Amazon SES by its name. Returns the template subject, HTML body, and text body.

Lua path
app.integrations.amazon_ses.get_template
Full name
amazon-ses.amazonses_get_template
ParameterTypeRequiredDescription
name string yes The name of the email template to retrieve.
list_templates Read

List all email templates in Amazon SES. Returns template names and creation timestamps. Supports pagination.

Lua path
app.integrations.amazon_ses.list_templates
Full name
amazon-ses.amazonses_list_templates
ParameterTypeRequiredDescription
page_size integer no Maximum number of templates to return per page (default: 10, max: 100).
next_token string no Pagination token from a previous response to fetch the next page of results.
create_template Write

Create a new email template in Amazon SES. Templates can include HTML and plain text content with optional substitution variables (e.g., {{name}}).

Lua path
app.integrations.amazon_ses.create_template
Full name
amazon-ses.amazonses_create_template
ParameterTypeRequiredDescription
template_name string yes A unique name for the template.
subject string yes The email subject line. Supports substitution variables (e.g., "Welcome, {{name}}!").
html_content string no HTML body of the template. Supports substitution variables using {{variable}} syntax.
text_content string no Plain text body of the template. Supports substitution variables using {{variable}} syntax.
update_template Write

Update an existing Amazon SES email template.

Lua path
app.integrations.amazon_ses.update_template
Full name
amazon-ses.amazonses_update_template
ParameterTypeRequiredDescription
template_name string yes Template name.
subject string yes Template subject.
html_content string no HTML template body.
text_content string no Text template body.
delete_template Write

Delete an Amazon SES email template by name.

Lua path
app.integrations.amazon_ses.delete_template
Full name
amazon-ses.amazonses_delete_template
ParameterTypeRequiredDescription
template_name string yes Template name.
list_suppressions Read

List email addresses on the Amazon SES account-level suppression list. Suppressed addresses will not receive emails.

Lua path
app.integrations.amazon_ses.list_suppressions
Full name
amazon-ses.amazonses_list_suppressions
ParameterTypeRequiredDescription
page_size integer no Maximum number of suppressed addresses to return per page.
next_token string no Pagination token from a previous response to fetch the next page of results.
reason string no Optional suppression reason filter.
list_identities Read

List Amazon SES verified email and domain identities.

Lua path
app.integrations.amazon_ses.list_identities
Full name
amazon-ses.amazonses_list_identities
ParameterTypeRequiredDescription
page_size integer no Maximum identities to return.
next_token string no Pagination token.
get_identity Read

Get Amazon SES identity details for an email address or domain.

Lua path
app.integrations.amazon_ses.get_identity
Full name
amazon-ses.amazonses_get_identity
ParameterTypeRequiredDescription
identity string yes Email address or domain identity.
list_configuration_sets Read

List Amazon SES configuration sets.

Lua path
app.integrations.amazon_ses.list_configuration_sets
Full name
amazon-ses.amazonses_list_configuration_sets
ParameterTypeRequiredDescription
page_size integer no Maximum configuration sets to return.
next_token string no Pagination token.
api_get Read

Call any signed Amazon SES v2 GET endpoint.

Lua path
app.integrations.amazon_ses.api_get
Full name
amazon-ses.amazonses_api_get
ParameterTypeRequiredDescription
path string yes SES API path beginning with /v2/.
params object no Query parameters.
api_post Write

Call any signed Amazon SES v2 POST endpoint.

Lua path
app.integrations.amazon_ses.api_post
Full name
amazon-ses.amazonses_api_post
ParameterTypeRequiredDescription
path string yes SES API path beginning with /v2/.
body object no JSON body.
api_put Write

Call any signed Amazon SES v2 PUT endpoint.

Lua path
app.integrations.amazon_ses.api_put
Full name
amazon-ses.amazonses_api_put
ParameterTypeRequiredDescription
path string yes SES API path beginning with /v2/.
body object no JSON body.
api_delete Write

Call any signed Amazon SES v2 DELETE endpoint.

Lua path
app.integrations.amazon_ses.api_delete
Full name
amazon-ses.amazonses_api_delete
ParameterTypeRequiredDescription
path string yes SES API path beginning with /v2/.
body object no JSON body.