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

```bash
# 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

```json
{
  "success": true,
  "data": { ... }
}
```

## Using with OpenAI Function Calling

```python
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

```typescript
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:

```bash
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](/docs/workflows/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        |

## Related

- [Full V2 Tools Reference](/docs/api-reference/v2-tools)
- [TypeScript SDK](/docs/api-reference/sdk)
- [MCP Server](/docs/api-reference/mcp)