`lumail@2.1.0` · [`lumail.tools`](/docs/sdk/v2/tools)

```typescript
tools.run<T>(toolName: string, params?: Record<string, unknown>, options?: { autoConfirm?: boolean }): Promise<LumailResult<RunToolResponse<T>>>
```

`autoConfirm: true` retries once with `confirmationCode` from `error.details` when the first response is `confirmation_required`. Dangerous tools (send, delete, unsubscribe) challenge unless you pass that code.

## Path Parameters

| Name | Type | Description |
| ---------- | ------ | ----------------------------------------- |
| `toolName` | string | **Required.** Tool name (`^[a-z0-9_]+$`). |

## Body Parameters

| Name | Type | Description |
| -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `params` | `Record` | Second argument. Tool input, sent as the JSON body. Defaults to `{}`. Shape is the tool's `inputSchema`. Dangerous retries may include `confirmationCode`. |

## Options

| Name | Type | Description |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autoConfirm` | boolean | Third-argument option. When `true` and the first error is `confirmation_required`, the SDK POSTs again with `confirmationCode` from `error.details`. |

## Response Fields

| Field | Type | Description |
| ----------------- | ---- | ----------------------------------------------------------------------------------------------------- |
| *(tool-specific)* | `T` | HTTP JSON body of the tool. Example: `list_subscribers` returns `{ object: "list", data, has_more }`. |

When confirmation is required, `error` is `{ name: "confirmation_required", message, statusCode: 403, details: { action, confirmationCode, instruction } }`.


## API Reference
**Method:** POST
**Endpoint:** /api/v2/tools/:toolName

### SDK
```ts
import { Lumail } from "lumail";

const lumail = new Lumail({ apiKey: process.env.LUMAIL_API_KEY });
const { data, error } = await lumail.tools.run(
  "list_subscribers",
  { limit: 10 },
  { autoConfirm: true },
);
if (error) {
  throw error;
}
console.log(data);
```

### cURL
```bash
curl -X POST https://lumail.io/api/v2/tools/list_subscribers \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit":10}'
```

### JavaScript
```javascript
const response = await fetch("https://lumail.io/api/v2/tools/list_subscribers", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ limit: 10 }),
});
const data = await response.json();
```

### Success Response
```json
{
  "object": "list",
  "has_more": false,
  "data": []
}
```

### Error Response
```json
{
  "name": "confirmation_required",
  "message": "This action requires confirmation",
  "statusCode": 403,
  "details": {
    "action": "send_email",
    "confirmationCode": 482910,
    "instruction": "Retry with confirmationCode"
  }
}
```