KosmoKrator

communication

Postmark Lua API for KosmoKrator Agents

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

9 functions 7 read 2 write API token auth
Submit Postmark feedback View package source

Lua Namespace

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

Postmark Integration

Authentication

The Postmark integration uses a Server API token. The token is sent via the X-Postmark-Server-Token header on every request.

Find your Server API token: Postmark Dashboard → Server → API Tokens

For account-level operations (listing servers), you may need an Account API token.

Base URL

  • Default: https://api.postmarkapp.com

Response Format

Postmark API responses return JSON. For example, the message list returns:

{
  "TotalCount": 100,
  "Messages": [
    {
      "MessageID": "abc-123",
      "MessageStream": "outbound",
      "To": ["[email protected]"],
      "From": "[email protected]",
      "Subject": "Hello",
      "Status": "Sent",
      "CreatedAt": "2024-01-01T00:00:00.0000000-00:00"
    }
  ]
}

Pagination

List endpoints support count and offset parameters for pagination.

  • count — Number of records to return (default 100, max 500)
  • offset — Number of records to skip

Common Workflows

Send an email

  1. postmark_send_email — Send an email with To, From, Subject, and TextBody or HtmlBody. Optionally add Cc, Bcc, Tag, and ReplyTo.

Track messages

  1. postmark_list_messages — List outbound messages. Filter by recipient, sender, subject, status, or tag.
  2. postmark_get_message — Get full details for a specific message by MessageID.

Manage templates

  1. postmark_list_templates — Browse all templates in the account.
  2. postmark_get_template — View template content including subject, HTML, and text body.

Server management

  1. postmark_list_servers — List servers in the account. Filter by name.
  2. postmark_get_current_user — Get current server info and settings. Useful as a health check.

Message Statuses

Common message statuses for filtering:

  • queued — Message is queued for delivery
  • sent — Message was delivered to the recipient’s server
  • bounced — Message bounced
  • inbound — Message was received inbound
  • opened — Recipient opened the message (requires open tracking)
  • clicked — Recipient clicked a tracked link

Tags

You can attach a tag to outgoing emails for categorization. Pass a Tag string when sending an email. Tags can be used to filter messages in postmark_list_messages.

Sender Signatures

The From email address must correspond to a verified Sender Signature in your Postmark account. Create and verify sender signatures in the Postmark Dashboard.

Multi-Account Usage

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

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

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

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

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

Raw agent markdown 
# Postmark Integration

## Authentication

The Postmark integration uses a Server API token. The token is sent via the `X-Postmark-Server-Token` header on every request.

Find your Server API token: **Postmark Dashboard → Server → API Tokens**

For account-level operations (listing servers), you may need an Account API token.

## Base URL

- Default: `https://api.postmarkapp.com`

## Response Format

Postmark API responses return JSON. For example, the message list returns:

```json
{
  "TotalCount": 100,
  "Messages": [
    {
      "MessageID": "abc-123",
      "MessageStream": "outbound",
      "To": ["[email protected]"],
      "From": "[email protected]",
      "Subject": "Hello",
      "Status": "Sent",
      "CreatedAt": "2024-01-01T00:00:00.0000000-00:00"
    }
  ]
}
```

## Pagination

List endpoints support `count` and `offset` parameters for pagination.

- `count` — Number of records to return (default 100, max 500)
- `offset` — Number of records to skip

## Common Workflows

### Send an email

1. `postmark_send_email` — Send an email with To, From, Subject, and TextBody or HtmlBody. Optionally add Cc, Bcc, Tag, and ReplyTo.

### Track messages

1. `postmark_list_messages` — List outbound messages. Filter by recipient, sender, subject, status, or tag.
2. `postmark_get_message` — Get full details for a specific message by MessageID.

### Manage templates

1. `postmark_list_templates` — Browse all templates in the account.
2. `postmark_get_template` — View template content including subject, HTML, and text body.

### Server management

1. `postmark_list_servers` — List servers in the account. Filter by name.
2. `postmark_get_current_user` — Get current server info and settings. Useful as a health check.

## Message Statuses

Common message statuses for filtering:
- `queued` — Message is queued for delivery
- `sent` — Message was delivered to the recipient's server
- `bounced` — Message bounced
- `inbound` — Message was received inbound
- `opened` — Recipient opened the message (requires open tracking)
- `clicked` — Recipient clicked a tracked link

## Tags

You can attach a tag to outgoing emails for categorization. Pass a `Tag` string when sending an email. Tags can be used to filter messages in `postmark_list_messages`.

## Sender Signatures

The `From` email address must correspond to a verified Sender Signature in your Postmark account. Create and verify sender signatures in the Postmark Dashboard.

---

## Multi-Account Usage

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

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

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

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

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

Metadata-Derived Lua Example

local result = app.integrations.postmark.postmark_list_messages({
  count = 1,
  offset = 1,
  recipient = "example_recipient",
  fromemail = "example_fromemail",
  subject = "example_subject",
  status = "example_status",
  tag = "example_tag"
})
print(result)

Functions

postmark_list_messages

List outbound messages from Postmark. Supports filtering by recipient, sender, subject, status, and tag.

Operation
Read read
Full name
postmark.postmark_list_messages
ParameterTypeRequiredDescription
count integer no Number of messages to return per page (default 100, max 500).
offset integer no Number of messages to skip for pagination.
recipient string no Filter by recipient email address.
fromemail string no Filter by sender email address.
subject string no Filter by email subject.
status string no Filter by status (queued, sent, bounced, etc.).
tag string no Filter by tag.

postmark_get_message

Get details for a specific Postmark outbound message including body, recipients, and delivery status.

Operation
Read read
Full name
postmark.postmark_get_message
ParameterTypeRequiredDescription
message_id string yes The Postmark message ID to look up.

postmark_send_email

Send an email through Postmark. Requires To, From, and Subject. Provide either TextBody or HtmlBody.

Operation
Write write
Full name
postmark.postmark_send_email
ParameterTypeRequiredDescription
To string yes Recipient email address.
From string yes Sender email address (must be a verified sender signature).
Subject string yes Email subject line.
TextBody string no Plain-text body of the email.
HtmlBody string no HTML body of the email.
Cc string no CC recipient(s), comma-separated.
Bcc string no BCC recipient(s), comma-separated.
Tag string no Tag for categorization and tracking.
ReplyTo string no Reply-To email address.

postmark_send_template

Send an email using a Postmark template. Provide either a TemplateId or TemplateAlias along with the template model data.

Operation
Write write
Full name
postmark.postmark_send_template
ParameterTypeRequiredDescription
From string yes Sender email address (must be a verified sender signature). Example: "[email protected]" or "Sender Name <[email protected]>".
To string yes Recipient email address. Multiple recipients separated by commas.
TemplateId integer no The template ID to use. Use this or TemplateAlias.
TemplateAlias string no The template alias to use. Use this or TemplateId.
TemplateModel array no Key-value pairs to fill the template variables. Example: {"name": "John", "company": "Acme"}.
Cc string no CC recipients (comma-separated).
Bcc string no BCC recipients (comma-separated).
ReplyTo string no Reply-to email address.
Tag string no Tag for categorization and analytics.
TrackOpens boolean no Enable open tracking (default: server setting).
TrackLinks string no Link tracking mode: "None", "HtmlAndText", "HtmlOnly", "TextOnly".

postmark_get_delivery_stats

Get email delivery statistics for your Postmark server, including counts of sent, bounced, and spam complaints.

Operation
Read read
Full name
postmark.postmark_get_delivery_stats
ParameterTypeRequiredDescription
No parameters.

postmark_list_templates

List all email templates in Postmark. Supports pagination.

Operation
Read read
Full name
postmark.postmark_list_templates
ParameterTypeRequiredDescription
count integer no Number of templates to return per page (default 100, max 500).
offset integer no Number of templates to skip for pagination.

postmark_get_template

Get details for a Postmark email template including subject, HTML body, and text body.

Operation
Read read
Full name
postmark.postmark_get_template
ParameterTypeRequiredDescription
template_id string yes The Postmark template ID to look up.

postmark_list_servers

List servers in the Postmark account. Supports filtering by name and pagination.

Operation
Read read
Full name
postmark.postmark_list_servers
ParameterTypeRequiredDescription
count integer no Number of servers to return per page (default 100, max 500).
offset integer no Number of servers to skip for pagination.
name string no Filter by server name.

postmark_get_current_user

Get the current Postmark server info including name, settings, and delivery stats. Useful as a health check.

Operation
Read read
Full name
postmark.postmark_get_current_user
ParameterTypeRequiredDescription
No parameters.