KosmoKrator

data

Lob Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.lob.list_letters({limit = 1, offset = 1}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("lob"))' --json
kosmo integrations:lua --eval 'print(docs.read("lob.list_letters"))' --json

Workflow file

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

workflow.lua 
local lob = app.integrations.lob
local result = lob.list_letters({limit = 1, offset = 1})

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

MCP-only Lua

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

Lob — Lua API Reference

list_letters

List letters with pagination.

Parameters

NameTypeRequiredDescription
limitintegernoResults per page (default: 10, max: 100)
offsetintegernoNumber of results to skip (default: 0)

Example

local result = app.integrations.lob.list_letters({ limit = 25 })

for _, letter in ipairs(result.data) do
  print(letter.id .. " — " .. letter.status)
end

get_letter

Retrieve a letter by its Lob ID.

Parameters

NameTypeRequiredDescription
idstringyesThe letter ID (e.g., "ltr_abcdef123456")

Example

local result = app.integrations.lob.get_letter({ id = "ltr_abc123" })

print("Status: " .. result.status)
print("Tracking: " .. (result.tracking_number or "N/A"))
print("URL: " .. result.url)

create_letter

Create and send a letter via Lob.

Parameters

NameTypeRequiredDescription
tostringyesRecipient — address ID (e.g., "adr_...") or inline address object
fromstringnoSender — address ID or inline address object
descriptionstringnoInternal description (not printed on the letter)
filestringyesHTML string or template ID for the letter content
colorbooleannoPrint in color (default: true)
double_sidedbooleannoPrint double-sided (default: true)

Example

local result = app.integrations.lob.create_letter({
  to = "adr_abc123",
  from = "adr_def456",
  description = "Welcome letter",
  file = "<html><body><p>Dear {{name}}, welcome!</p></body></html>",
  color = true,
  double_sided = true
})

print("Letter ID: " .. result.id)
print("Expected delivery: " .. result.expected_delivery_date)

Using a template

local result = app.integrations.lob.create_letter({
  to = "adr_abc123",
  from = "adr_def456",
  file = "tmpl_welcome_letter",
  description = "Template letter"
})

list_postcards

List postcards with pagination.

Parameters

NameTypeRequiredDescription
limitintegernoResults per page (default: 10, max: 100)
offsetintegernoNumber of results to skip (default: 0)

Example

local result = app.integrations.lob.list_postcards({ limit = 25 })

for _, postcard in ipairs(result.data) do
  print(postcard.id .. " — " .. postcard.status)
end

get_postcard

Retrieve a postcard by its Lob ID.

Parameters

NameTypeRequiredDescription
idstringyesThe postcard ID (e.g., "psc_abcdef123456")

Example

local result = app.integrations.lob.get_postcard({ id = "psc_abc123" })

print("Status: " .. result.status)
print("Tracking: " .. (result.tracking_number or "N/A"))

create_postcard

Create and send a postcard via Lob.

Parameters

NameTypeRequiredDescription
tostringyesRecipient — address ID or inline address object
fromstringnoSender — address ID or inline address object
descriptionstringnoInternal description (not printed on the postcard)
frontstringyesHTML string or template ID for the front of the postcard
backstringyesHTML string or template ID for the back of the postcard

Example

local result = app.integrations.lob.create_postcard({
  to = "adr_abc123",
  from = "adr_def456",
  description = "Marketing postcard",
  front = "<html><body><h1>Hello!</h1></body></html>",
  back = "<html><body><p>Return: 123 Main St</p></body></html>"
})

print("Postcard ID: " .. result.id)
print("Status: " .. result.status)

Using a template

local result = app.integrations.lob.create_postcard({
  to = "adr_abc123",
  from = "adr_def456",
  front = "tmpl_postcard_front",
  back = "tmpl_postcard_back",
  description = "Template postcard"
})

get_current_user

List saved addresses in the Lob account.

Parameters

None.

Example

local result = app.integrations.lob.get_current_user({})

for _, addr in ipairs(result.data) do
  print(addr.id .. ": " .. addr.description .. " — " .. addr.address_line1)
end

Multi-Account Usage

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

-- Default account (always works)
app.integrations.lob.create_letter({...})

-- Explicit default (portable across setups)
app.integrations.lob.default.create_letter({...})

-- Named accounts
app.integrations.lob.marketing.create_postcard({...})
app.integrations.lob.billing.create_letter({...})

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

Raw agent markdown 
# Lob — Lua API Reference

## list_letters

List letters with pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Results per page (default: 10, max: 100) |
| `offset` | integer | no | Number of results to skip (default: 0) |

### Example

```lua
local result = app.integrations.lob.list_letters({ limit = 25 })

for _, letter in ipairs(result.data) do
  print(letter.id .. " — " .. letter.status)
end
```

---

## get_letter

Retrieve a letter by its Lob ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The letter ID (e.g., `"ltr_abcdef123456"`) |

### Example

```lua
local result = app.integrations.lob.get_letter({ id = "ltr_abc123" })

print("Status: " .. result.status)
print("Tracking: " .. (result.tracking_number or "N/A"))
print("URL: " .. result.url)
```

---

## create_letter

Create and send a letter via Lob.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `to` | string | yes | Recipient — address ID (e.g., `"adr_..."`) or inline address object |
| `from` | string | no | Sender — address ID or inline address object |
| `description` | string | no | Internal description (not printed on the letter) |
| `file` | string | yes | HTML string or template ID for the letter content |
| `color` | boolean | no | Print in color (default: `true`) |
| `double_sided` | boolean | no | Print double-sided (default: `true`) |

### Example

```lua
local result = app.integrations.lob.create_letter({
  to = "adr_abc123",
  from = "adr_def456",
  description = "Welcome letter",
  file = "<html><body><p>Dear {{name}}, welcome!</p></body></html>",
  color = true,
  double_sided = true
})

print("Letter ID: " .. result.id)
print("Expected delivery: " .. result.expected_delivery_date)
```

### Using a template

```lua
local result = app.integrations.lob.create_letter({
  to = "adr_abc123",
  from = "adr_def456",
  file = "tmpl_welcome_letter",
  description = "Template letter"
})
```

---

## list_postcards

List postcards with pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Results per page (default: 10, max: 100) |
| `offset` | integer | no | Number of results to skip (default: 0) |

### Example

```lua
local result = app.integrations.lob.list_postcards({ limit = 25 })

for _, postcard in ipairs(result.data) do
  print(postcard.id .. " — " .. postcard.status)
end
```

---

## get_postcard

Retrieve a postcard by its Lob ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The postcard ID (e.g., `"psc_abcdef123456"`) |

### Example

```lua
local result = app.integrations.lob.get_postcard({ id = "psc_abc123" })

print("Status: " .. result.status)
print("Tracking: " .. (result.tracking_number or "N/A"))
```

---

## create_postcard

Create and send a postcard via Lob.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `to` | string | yes | Recipient — address ID or inline address object |
| `from` | string | no | Sender — address ID or inline address object |
| `description` | string | no | Internal description (not printed on the postcard) |
| `front` | string | yes | HTML string or template ID for the front of the postcard |
| `back` | string | yes | HTML string or template ID for the back of the postcard |

### Example

```lua
local result = app.integrations.lob.create_postcard({
  to = "adr_abc123",
  from = "adr_def456",
  description = "Marketing postcard",
  front = "<html><body><h1>Hello!</h1></body></html>",
  back = "<html><body><p>Return: 123 Main St</p></body></html>"
})

print("Postcard ID: " .. result.id)
print("Status: " .. result.status)
```

### Using a template

```lua
local result = app.integrations.lob.create_postcard({
  to = "adr_abc123",
  from = "adr_def456",
  front = "tmpl_postcard_front",
  back = "tmpl_postcard_back",
  description = "Template postcard"
})
```

---

## get_current_user

List saved addresses in the Lob account.

### Parameters

None.

### Example

```lua
local result = app.integrations.lob.get_current_user({})

for _, addr in ipairs(result.data) do
  print(addr.id .. ": " .. addr.description .. " — " .. addr.address_line1)
end
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.lob.create_letter({...})

-- Explicit default (portable across setups)
app.integrations.lob.default.create_letter({...})

-- Named accounts
app.integrations.lob.marketing.create_postcard({...})
app.integrations.lob.billing.create_letter({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.lob.list_letters({limit = 1, offset = 1})
print(result)

Functions

list_letters Read

List letters with pagination. Returns a page of letter objects sorted by creation date (newest first).

Lua path
app.integrations.lob.list_letters
Full name
lob.lob_list_letters
ParameterTypeRequiredDescription
limit integer no Number of results per page (default: 10, max: 100).
offset integer no Number of results to skip for pagination (default: 0).
get_letter Read

Retrieve details of a specific letter by its Lob ID, including delivery status, tracking info, and the letter URL.

Lua path
app.integrations.lob.get_letter
Full name
lob.lob_get_letter
ParameterTypeRequiredDescription
id string yes The letter ID (e.g., "ltr_abcdef123456").
create_letter Write

Create and send a letter via Lob. Provide recipient and sender addresses (as address IDs or inline address objects), plus an HTML file or template ID for the letter content.

Lua path
app.integrations.lob.create_letter
Full name
lob.lob_create_letter
ParameterTypeRequiredDescription
to string yes Recipient — an address ID (e.g., "adr_...") or an inline address object.
from string no Sender — an address ID or inline address object. Optional if a default return address is configured.
description string no An internal description for the letter (not printed on the letter itself).
file string yes HTML string or template ID for the letter content (e.g., "<html>...</html>" or "tmpl_...").
color boolean no Print in color (default: true). Set to false for black & white.
double_sided boolean no Print double-sided (default: true). Set to false for single-sided.
list_postcards Read

List postcards with pagination. Returns a page of postcard objects sorted by creation date (newest first).

Lua path
app.integrations.lob.list_postcards
Full name
lob.lob_list_postcards
ParameterTypeRequiredDescription
limit integer no Number of results per page (default: 10, max: 100).
offset integer no Number of results to skip for pagination (default: 0).
get_postcard Read

Retrieve details of a specific postcard by its Lob ID, including delivery status, tracking info, and thumbnails.

Lua path
app.integrations.lob.get_postcard
Full name
lob.lob_get_postcard
ParameterTypeRequiredDescription
id string yes The postcard ID (e.g., "psc_abcdef123456").
create_postcard Write

Create and send a postcard via Lob. Provide recipient and sender addresses (as address IDs or inline address objects), plus HTML or template IDs for the front and back.

Lua path
app.integrations.lob.create_postcard
Full name
lob.lob_create_postcard
ParameterTypeRequiredDescription
to string yes Recipient — an address ID (e.g., "adr_...") or an inline address object (name, address_line1, city, state, zip).
from string no Sender — an address ID or inline address object. Optional if a default return address is configured.
description string no An internal description for the postcard (not printed on the postcard itself).
front string yes HTML string or template ID for the front of the postcard (e.g., "<html>...</html>" or "tmpl_...").
back string yes HTML string or template ID for the back of the postcard.
get_addresses Read

List saved addresses in the Lob account. Returns all verified addresses that can be used as sender or recipient for letters and postcards.

Lua path
app.integrations.lob.get_addresses
Full name
lob.lob_get_current_user
ParameterTypeRequiredDescription
No parameters.