Tools API (v2)
Call any Lumail tool via a single REST endpoint - works with any language or AI framework.
The Tools API exposes Lumail's organization-aware tool catalog through a single REST pattern. Workflow tools are available to every organization. It works with any language, framework, or AI agent that can make HTTP requests.
Quick Start
# List all tools
curl https://lumail.io/api/v2/tools \
-H "Authorization: Bearer lum_your_token"
# Run a tool
curl -X POST https://lumail.io/api/v2/tools/list_subscribers \
-H "Authorization: Bearer lum_your_token" \
-H "Content-Type: application/json" \
-d '{"limit": 10, "status": "SUBSCRIBED"}'Pattern
All tools follow the same URL pattern:
POST https://lumail.io/api/v2/tools/{tool_name}
With request body containing the tool's parameters as JSON.
Response Format
{
"success": true,
"data": { ... }
}Using with OpenAI Function Calling
import openai
import requests
LUMAIL_TOKEN = "lum_..."
# Define Lumail tools as OpenAI functions
tools = [{
"type": "function",
"function": {
"name": "add_subscriber",
"description": "Add a subscriber to Lumail",
"parameters": {
"type": "object",
"properties": {
"email": {"type": "string"},
"name": {"type": "string"},
"tags": {"type": "array", "items": {"type": "string"}}
},
"required": ["email"]
}
}
}]
# When OpenAI calls the function, forward to Lumail
def handle_tool_call(name, args):
response = requests.post(
f"https://lumail.io/api/v2/tools/{name}",
headers={"Authorization": f"Bearer {LUMAIL_TOKEN}"},
json=args,
)
return response.json()Using with LangChain
import { DynamicTool } from "langchain/tools";
const lumailTool = new DynamicTool({
name: "lumail_add_subscriber",
description: "Add a subscriber to the email list",
func: async (input: string) => {
const params = JSON.parse(input);
const res = await fetch("https://lumail.io/api/v2/tools/add_subscriber", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.LUMAIL_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(params),
});
return JSON.stringify(await res.json());
},
});Tool Categories
| Category | Tools |
|---|---|
| Subscribers | list_subscribers, add_subscriber, get_subscriber, update_subscriber, delete_subscriber, unsubscribe, add_tags, remove_tags |
| Campaigns | list_campaigns, create_campaign, get_campaign, edit_campaign, send_campaign, delete_campaign |
| Tags | list_tags, create_tag, get_tag, update_tag |
| Emails | send_email, verify_email |
| Events | track_event, list_events |
| Workflows | Complete Workflow graph, lifecycle, enrollment, and group-management tools |
| Analytics | get_dashboard_stats, get_campaign_stats |
Workflow
Workflow tools expose the canonical graph, lifecycle, enrollment, and group APIs for /workflows/ resources.
Complete tool set
| Area | Tools |
|---|---|
| Read/create | list_workflows, get_workflow, create_workflow |
| Draft graph | configure_workflow_draft, update_workflow_draft |
| Lifecycle | publish_workflow, update_workflow_status, delete_workflow |
| Enrollment | add_subscriber_to_workflow, add_subscribers_to_workflow, remove_subscriber_from_workflow |
| Runs | get_subscriber_workflow_runs, fast_forward_workflow_subscriber |
| Groups | list_workflow_groups, get_workflow_group, create_workflow_group, update_workflow_group, set_workflow_group, delete_workflow_group |
Read schemas dynamically instead of hard-coding them:
curl https://lumail.io/api/v2/tools/configure_workflow_draft \
-H "Authorization: Bearer lum_your_token"
curl https://lumail.io/api/v2/tools/create_workflow_group \
-H "Authorization: Bearer lum_your_token"For complete graph work, call get_skill with { "type": "workflow" }, read the workflow, and pass its exact updatedAt as expectedUpdatedAt. configure_workflow_draft replaces the full graph atomically but never publishes or sends.
For groups, list and read before mutation. Group updates and workflow assignment use optimistic concurrency. Group deletion is confirmation-gated and refuses assigned workflows unless unassignWorkflows: true is explicit.
See Workflow for every event, step, edge, setting, status, goal, exit, and verification rule.
Rate Limits
| Plan | Requests/min |
|---|---|
| Free | 100 |
| Premium | 700 |
| Business | 2,000 |