The Tools API provides a unified REST interface to execute any Lumail tool. Instead of learning multiple endpoints, you can use a single pattern to access all functionality.

## Quick Start

All tools are available at `/api/v2/tools/{tool_name}`.

**List all available tools:**

```bash
curl https://lumail.io/api/v2/tools \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Execute a tool:**

```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}'
```

## Authentication

All requests require a Bearer token in the Authorization header:

```
Authorization: Bearer lum_your_api_token_here
```

Get your API token from **Settings → API Tokens** in your Lumail dashboard.

## Response Format

All tool responses follow this structure:

**Success:**

```json
{
  "success": true,
  "data": {
    /* tool-specific response */
  }
}
```

**Error:**

```json
{
  "success": false,
  "error": "Error message"
}
```

## Dangerous Action Confirmation

Publishing, activating, archiving, deleting, sending, or otherwise high-impact tools use a two-call confirmation flow. The first request returns `CONFIRMATION_REQUIRED` and a five-digit `confirmationCode`. Repeat the exact same request with that code within five minutes to execute it.

Draft-only tools such as `configure_workflow_draft` do not require confirmation because they never publish or send.

## Rate Limits

Rate limits apply per organization based on your plan:

| Plan       | Requests/minute |
| ---------- | --------------- |
| Free       | 100             |
| Premium    | 700             |
| Enterprise | 2,000           |

## Available Tools (92 total)

| Tool                              | Description                                                          |
| --------------------------------- | -------------------------------------------------------------------- |
| `list_tags`                       | List all tags in your organization.                                  |
| `create_tag`                      | Create a new tag in your organization.                               |
| `delete_tag`                      | Delete a tag by ID or name. This will remove the tag from al...      |
| `get_or_create_tags`              | Get existing tags or create new ones by name. Tags are label...      |
| `list_subscribers`                | List subscribers in your organization. Filter by tag, status...      |
| `query_subscribers`               | List subscribers matching composed filters - the same engine...      |
| `count_subscribers`               | Count subscribers matching composed filters - same engine as...      |
| `get_subscriber`                  | Get detailed information about a specific subscriber by ID o...      |
| `add_subscriber`                  | Add a new subscriber or update an existing one. Supports tag...      |
| `update_subscriber`               | Update a subscriber by ID or email. Omitted resubscribe does...      |
| `unsubscribe`                     | Unsubscribe a subscriber by ID or email. The subscriber will...      |
| `bulk_add_tags`                   | Add one or more tags to multiple subscribers at once. Max 10...      |
| `bulk_remove_tags`                | Remove one or more tags from multiple subscribers. Max 100 s...      |
| `create_event`                    | Create a custom event for a subscriber. Useful for tracking ...      |
| `list_subscriber_events`          | List events for a subscriber. Use this to check if an email ...      |
| `get_subscriber_emails`           | Get emails sent to a subscriber with their delivery status. ...      |
| `list_campaigns`                  | List email campaigns in your organization with optional filt...      |
| `create_campaign`                 | Create a new email campaign. The campaign will be created in...      |
| `get_campaign`                    | Get detailed information about a specific campaign by ID.            |
| `get_campaign_progress`           | Get the sending progress of a campaign that is currently bei...      |
| `get_campaign_analytics`          | Get detailed analytics for a sent campaign including opens, ...      |
| `duplicate_campaign`              | Create a complete copy of a campaign including all content a...      |
| `edit_campaign`                   | The ONLY tool for modifying campaigns (name, subject, previe...      |
| `auto_fit_campaign_images`        | Apply the editor's magic-wand auto-fit to a draft campaign's...      |
| `get_available_filters`           | Get the machine-readable filter schema (types, operators, re...      |
| `update_campaign_filters`         | Update the recipient filters of a DRAFT campaign. Filters ar...      |
| `send_test_email`                 | Send a test email for a campaign to one or more email addres...      |
| `render_campaign`                 | Render a campaign to its final HTML and plain text exactly a...      |
| `schedule_campaign`               | Schedule a DRAFT campaign (status becomes SCHEDULED). The ca...      |
| `cancel_campaign_schedule`        | Cancel a scheduled campaign, reverting it back to DRAFT stat...      |
| `list_campaign_history`           | List version history entries for a campaign. Returns entries...      |
| `get_campaign_history_entry`      | Get a specific campaign history entry with full content. Use...      |
| `restore_campaign_history`        | Restore a campaign to a previous version from its history. T...      |
| `archive_campaign`                | Archive a DRAFT campaign. Archived campaigns are hidden from...      |
| `unarchive_campaign`              | Restore an ARCHIVED campaign back to DRAFT status so it can ...      |
| `list_workflows`                  | List graph-based workflow automations.                               |
| `get_workflow`                    | Get a Workflow draft graph, published version information, s...      |
| `create_workflow`                 | Create a graph-based Workflow draft. It must be configured a...      |
| `configure_workflow_draft`        | Configure an entire Workflow draft (steps, edges, waits, bra...      |
| `update_workflow_draft`           | Replace a Workflow draft graph atomically. The full {steps, ... |
| `publish_workflow`                | Validate and publish the current Workflow draft as a new imm...      |
| `update_workflow_status`          | Activate, pause, or archive a published Workflow.                    |
| `add_subscriber_to_workflow`      | Manually enroll a subscriber in an active, published Workflo...      |
| `add_subscribers_to_workflow`     | Manually enroll a filtered subscriber set — same as Select a...      |
| `remove_subscriber_from_workflow` | Cancel active Workflow runs for a subscriber.                        |
| `get_subscriber_workflow_runs`    | List a subscriber's workflow runs: status, current step, nex...      |
| `fast_forward_workflow_subscriber` | Expire the current WAIT or WAIT_UNTIL and resume the runner now.   |
| `delete_workflow`                 | Delete an unused Workflow draft, or archive it when publishe...      |
| `list_workflow_groups`            | List Workflow groups with their conflict strategy and assign...      |
| `get_workflow_group`              | Get a Workflow group, its assigned workflows, and current ac...      |
| `create_workflow_group`           | Create a Workflow group. The operation is idempotent when a ...      |
| `update_workflow_group`           | Rename a Workflow group or change its conflict strategy for ...      |
| `set_workflow_group`              | Assign a Workflow to an existing group, or detach it with gr...      |
| `delete_workflow_group`           | Permanently delete a Workflow group after a fresh read. Refu...      |
| `list_segments`                   | List saved subscriber segments in your organization.                 |
| `get_segment`                     | Get detailed information about a specific segment including ...      |
| `create_segment`                  | Create a new subscriber segment with filter configuration.           |
| `update_segment`                  | Update a segment's name or filter configuration.                     |
| `delete_segment`                  | Permanently delete a segment.                                        |
| `duplicate_segment`               | Create a copy of a segment with all its filters.                     |
| `get_org_stats`                   | Get overall organization statistics including subscriber cou...      |
| `get_subscriber_growth`           | Analyze subscriber growth over a specified time period. Show...      |
| `get_subscriber_stats`            | Get subscriber growth and status statistics for your organiz...      |
| `get_subscribers_by_tag`          | Get all subscribers that have a specific tag. Useful for und...      |
| `count_subscribers_by_status`     | Get subscriber count by status. Optionally filter by a speci...      |
| `get_writing_style`               | Get the organization's default writing style for content gen...      |
| `update_writing_style`            | Modify writing style settings (persona, audience, vocabulary...      |
| `get_email_senders`               | List all configured email senders (from addresses) for this ...      |
| `get_custom_fields`               | List all custom subscriber field definitions for this organi...      |
| `get_email_snippets`              | List email snippets (reusable content blocks) for this organ...      |
| `get_email_snippet`               | Get a single email snippet by id (snp\_...) including its ful...     |
| `create_email_snippet`            | Create a new email snippet (reusable content block). Content...      |
| `update_email_snippet`            | Update an email snippet by id (snp\_...): name, description, ...     |
| `archive_email_snippet`           | Archive an email snippet by id (snp\_...). Archived snippets ...     |
| `unarchive_email_snippet`         | Restore an archived email snippet by id (snp\_...).                  |
| `update_organization_settings`    | Update organization name and timezone                                |
| `fetch_web_page`                  | Fetch a web page and convert to markdown format                      |
| `send_email`                      | Send a transactional email to a subscriber. The 'from' addre...      |
| `get_available_variables`         | Get all available variables for email content (built-in, org...      |
| `get_skill`                       | Get task-specific documentation. Call it BEFORE writing cont...      |
| `list_domains`                    | List the organization's email sending domains with their ver...      |
| `create_domain`                   | Register a new email sending domain and return the DNS recor...      |
| `get_domain_dns_records`          | Get a domain's DNS records with their per-record verificatio...      |
| `verify_domain`                   | Re-check a domain's verification, DKIM and MAIL FROM state a...      |
| `create_email_sender`             | Create an email sender (from-address) as localPart@domain on...      |
| `get_deliverability_health`       | Assess the organization's deliverability health (sender repu...      |
| `list_suppressed_subscribers`     | List suppressed subscribers (BOUNCED and/or COMPLAINED), mos...      |
| `reactivate_subscriber`           | Reactivate a suppressed subscriber (BOUNCED, COMPLAINED, or ...      |
| `upload_image`                    | Import an image from a public http/https URL into your organ...      |
| `list_images`                     | Search the organization media library. The query matches bot...      |
| `describe_image`                  | Set or update the description of an image already in the med...      |
| `import_subscribers`              | Bulk import subscribers (up to 500 per call). Existing subsc...      |
| `export_subscribers`              | Export subscribers from your organization. Optionally filter...      |

---

## Subscriber Tools

### List Subscribers

**Endpoint:** `POST /api/v2/tools/list_subscribers`

List subscribers in your organization. Filter by tag, status, or search query. Returns results with email, name, status, tags, sorted by creation date descending.

**Parameters:**

| Parameter | Type                                                                                                       | Required | Description                                              |
| --------- | ---------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------- |
| `limit`   | integer                                                                                                    | No       | (default: `50`)                                          |
| `status`  | "all" \| "SUBSCRIBED" \| "UNSUBSCRIBED" \| "PENDING_CONFIRMATION" \| "BOUNCED" \| "BANNED" \| "COMPLAINED" \| "TRANSACTIONAL" | No       | (default: `"all"`)                                       |
| `tag`     | string                                                                                                     | No       | Filter by tag name (case-insensitive)                    |
| `query`   | string                                                                                                     | No       |                                                          |
| `cursor`  | string                                                                                                     | No       | Cursor for pagination (subscriber ID from previous page) |

**Example:**

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

### Query Subscribers

**Endpoint:** `POST /api/v2/tools/query_subscribers`

List subscribers matching composed filters - the same engine the UI uses, cursor-paginated. Use it instead of `list_subscribers` when you need conditional filters (e.g. clicked link X in campaign Y AND is BANNED). Call get_skill({ type: "filters" }) for the filter shapes and operators.

**Parameters:**

| Parameter | Type                                                                                                       | Required | Description                                                                                                                                                                                                                        |
| --------- | ---------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filters` | array                                                                                                      | No       | Array of filter objects - same shape as update_campaign_filters and create_segment. See get_skill({ type: "filters" }). (default: `[]`)                                                                                  |
| `status`  | "PENDING_CONFIRMATION" \| "SUBSCRIBED" \| "UNSUBSCRIBED" \| "BOUNCED" \| "BANNED" \| "COMPLAINED" \| "TRANSACTIONAL" \| "ALL" | No       | Subscriber status filter - applied in addition to the filters array. Defaults to ALL. (default: `"ALL"`)                                                                                                                           |
| `query`   | string                                                                                                     | No       | Free-text search across email, name, and tag name.                                                                                                                                                                                 |
| `limit`   | integer                                                                                                    | No       | (default: `50`)                                                                                                                                                                                                                    |
| `cursor`  | string                                                                                                     | No       | Cursor for pagination (subscriber ID from previous page).                                                                                                                                                                          |
| `fields`  | array                                                                                                      | No       | Subset of fields to include per subscriber. Defaults to id, email, name, status, createdAt, tags. Available: id, email, name, phone, status, createdAt, updatedAt, tags, customFields, revenue, emailCount, openCount, clickCount. |

**Example:**

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

### Count Subscribers

**Endpoint:** `POST /api/v2/tools/count_subscribers`

Count subscribers matching composed filters - same engine as query_subscribers but returns only the total. Useful for previews before scheduling a campaign or building a segment.

**Parameters:**

| Parameter | Type                                                                                                       | Required | Description                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `filters` | array                                                                                                      | No       | Array of filter objects - same shape as update_campaign_filters and create_segment. (default: `[]`)      |
| `status`  | "PENDING_CONFIRMATION" \| "SUBSCRIBED" \| "UNSUBSCRIBED" \| "BOUNCED" \| "BANNED" \| "COMPLAINED" \| "TRANSACTIONAL" \| "ALL" | No       | Subscriber status filter - applied in addition to the filters array. Defaults to ALL. (default: `"ALL"`) |
| `query`   | string                                                                                                     | No       | Free-text search across email, name, and tag name.                                                       |

**Example:**

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

### Get Subscriber

**Endpoint:** `POST /api/v2/tools/get_subscriber`

Get detailed information about a specific subscriber by ID or email.

**Parameters:**

| Parameter      | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `subscriberId` | string | No       |             |
| `email`        | string | No       |             |

**Example:**

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

### Add Subscriber

**Endpoint:** `POST /api/v2/tools/add_subscriber`

Add a new subscriber or update an existing one. Supports tags and custom fields.

**Parameters:**

| Parameter     | Type    | Required | Description        |
| ------------- | ------- | -------- | ------------------ |
| `email`            | string  | Yes      |                    |
| `name`             | string  | No       |                    |
| `phone`            | string  | No       |                    |
| `tags`             | array   | No       | (default: `[]`)    |
| `fields`           | object  | No       |                    |
| `replaceTags`      | boolean | No       | (default: `false`) |
| `resubscribe`      | boolean | No       | Re-subscribe if they were unsubscribed. (default: `true`) |
| `triggerWorkflows` | boolean | No       | Fire matching workflows. (default: `true`). Pass `false` to skip. |
| `skipDoubleOptIn`  | boolean | No       | Create or promote as `SUBSCRIBED` even if organization double opt-in is on. Default `false`. Does not resubscribe `UNSUBSCRIBED` alone, and does not write confirmation evidence. |
| `ipAddress`        | string  | No       |                    |
| `country`          | string  | No       | ISO-3166 alpha-2   |

**Example:**

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

### Update Subscriber

**Endpoint:** `POST /api/v2/tools/update_subscriber`

Update a subscriber by ID or email. Same fields as `add_subscriber`, but omitted `resubscribe` / `triggerWorkflows` are left unset (a name-only patch does **not** resubscribe).

**Parameters:**

| Parameter          | Type    | Required | Description |
| ------------------ | ------- | -------- | ----------- |
| `subscriber`       | string  | Yes      | ID or email |
| `email`            | string  | No       |             |
| `name`             | string  | No       |             |
| `phone`            | string  | No       |             |
| `tags`             | array   | No       |             |
| `fields`           | object  | No       |             |
| `replaceTags`      | boolean | No       |             |
| `resubscribe`      | boolean | No       | Default unset / false. Pass `true` to re-subscribe. |
| `triggerWorkflows` | boolean | No       | Pass `false` to skip automations. |
| `skipDoubleOptIn`  | boolean | No       | Promote pending contacts to `SUBSCRIBED` before tag events. Default `false`. |
| `ipAddress`        | string  | No       |             |
| `country`          | string  | No       | ISO-3166 alpha-2 |

**Example:**

```bash
curl -X POST https://lumail.io/api/v2/tools/update_subscriber \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subscriber":"user@example.com","name":"Ada"}'
```

### Unsubscribe

**Endpoint:** `POST /api/v2/tools/unsubscribe`

Unsubscribe a subscriber by ID or email. The subscriber will no longer receive emails.

**Parameters:**

| Parameter      | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `subscriberId` | string | No       |             |
| `email`        | string | No       |             |
| `reason`       | string | No       |             |

**Example:**

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

### Bulk Add Tags

**Endpoint:** `POST /api/v2/tools/bulk_add_tags`

Add one or more tags to multiple subscribers at once. Max 100 subscribers and 20 tags per call. Emits a tag.added event for each newly added tag, so tag-based workflow triggers (including Workflow event triggers) will fire exactly like when tags are added from the app.

**Parameters:**

| Parameter       | Type  | Required | Description |
| --------------- | ----- | -------- | ----------- |
| `subscriberIds` | array | Yes      |             |
| `tagNames`      | array | Yes      |             |

**Example:**

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

### Bulk Remove Tags

**Endpoint:** `POST /api/v2/tools/bulk_remove_tags`

Remove one or more tags from multiple subscribers. Max 100 subscribers and 20 tags per call. Emits a tag.removed event for each removed tag, so tag-based workflow triggers and exit rules react exactly like when tags are removed from the app.

**Parameters:**

| Parameter       | Type  | Required | Description |
| --------------- | ----- | -------- | ----------- |
| `subscriberIds` | array | Yes      |             |
| `tagNames`      | array | Yes      |             |

**Example:**

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

### Create Event

**Endpoint:** `POST /api/v2/tools/create_event`

Create a custom event for a subscriber. Useful for tracking purchases, conversions, or other actions.

**Parameters:**

| Parameter      | Type                                        | Required | Description        |
| -------------- | ------------------------------------------- | -------- | ------------------ |
| `subscriberId` | string                                      | No       |                    |
| `email`        | string                                      | No       |                    |
| `eventType`    | "SUBSCRIBER_PAYMENT" \| "SUBSCRIBER_REFUND" | Yes      |                    |
| `amount`       | number                                      | No       |                    |
| `currency`     | string                                      | No       | (default: `"USD"`) |
| `metadata`     | object                                      | No       |                    |

**Example:**

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

### List Subscriber Events

**Endpoint:** `POST /api/v2/tools/list_subscriber_events`

List events for a subscriber. Use this to check if an email was delivered, opened, clicked, bounced, etc. Filter by event type to find specific events.

**Parameters:**

| Parameter      | Type                                                                                                                                                                                                                                                                                                                                                                      | Required | Description     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------- |
| `subscriberId` | string                                                                                                                                                                                                                                                                                                                                                                    | No       |                 |
| `email`        | string                                                                                                                                                                                                                                                                                                                                                                    | No       |                 |
| `eventType`    | "SUBSCRIBED" \| "UNSUBSCRIBED" \| "TAG_ADDED" \| "TAG_REMOVED" \| "EMAIL_OPENED" \| "EMAIL_CLICKED" \| "EMAIL_SENT" \| "EMAIL_DELIVERY_DELAYED" \| "WORKFLOW_STARTED" \| "WORKFLOW_COMPLETED" \| "WORKFLOW_CANCELED" \| "FIELD_UPDATED" \| "EMAIL_BOUNCED" \| "EMAIL_COMPLAINED" \| "EMAIL_RECEIVED" \| "WEBHOOK_EXECUTED" \| "SUBSCRIBER_PAYMENT" \| "SUBSCRIBER_REFUND" | No       |                 |
| `limit`        | integer                                                                                                                                                                                                                                                                                                                                                                   | No       | (default: `50`) |

**Example:**

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

### Get Subscriber Emails

**Endpoint:** `POST /api/v2/tools/get_subscriber_emails`

Get emails sent to a subscriber with their delivery status. Use this to check if emails were delivered, bounced, or are pending. Shows campaign name, subject, and detailed status.

**Parameters:**

| Parameter      | Type                                                            | Required | Description     |
| -------------- | --------------------------------------------------------------- | -------- | --------------- |
| `subscriberId` | string                                                          | No       |                 |
| `email`        | string                                                          | No       |                 |
| `status`       | "PENDING" \| "SENT" \| "DELIVERED" \| "BOUNCED" \| "COMPLAINED" | No       |                 |
| `limit`        | integer                                                         | No       | (default: `20`) |

**Example:**

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

## Tag Tools

### List Tags

**Endpoint:** `POST /api/v2/tools/list_tags`

List all tags in your organization.

**Parameters:**

No parameters required.

**Example:**

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

### Create Tag

**Endpoint:** `POST /api/v2/tools/create_tag`

Create a new tag in your organization.

**Parameters:**

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `name`    | string | Yes      |             |

**Example:**

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

### Delete Tag

**Endpoint:** `POST /api/v2/tools/delete_tag`

Delete a tag by ID or name. This will remove the tag from all subscribers.

**Parameters:**

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `tagId`   | string | No       |             |
| `name`    | string | No       |             |

**Example:**

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

### Get Or Create Tags

**Endpoint:** `POST /api/v2/tools/get_or_create_tags`

Get existing tags or create new ones by name. Tags are labels used to categorize subscribers and trigger workflows. This tool automatically creates any tags that don't exist yet.

**Parameters:**

| Parameter | Type  | Required | Description                         |
| --------- | ----- | -------- | ----------------------------------- |
| `names`   | array | Yes      | Array of tag names to get or create |

**Example:**

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

## Campaign Tools

### List Campaigns

**Endpoint:** `POST /api/v2/tools/list_campaigns`

List email campaigns in your organization with optional filtering by status and search.

**Parameters:**

| Parameter | Type                                                                    | Required | Description     |
| --------- | ----------------------------------------------------------------------- | -------- | --------------- |
| `limit`   | integer                                                                 | No       | (default: `20`) |
| `page`    | integer                                                                 | No       | (default: `1`)  |
| `status`  | "DRAFT" \| "SCHEDULED" \| "SENDING" \| "SENT" \| "ARCHIVED" \| "FAILED" | No       |                 |
| `query`   | string                                                                  | No       |                 |

**Example:**

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

### Create Campaign

**Endpoint:** `POST /api/v2/tools/create_campaign`

Create a new email campaign. The campaign will be created in DRAFT status. If no senderId is provided, it will use the default sender, then last used sender, then any available sender.

**Parameters:**

| Parameter     | Type                             | Required | Description                                                                                                                                                                                                               |
| ------------- | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subject`     | string                           | Yes      | Email subject line (required)                                                                                                                                                                                             |
| `name`        | string                           | No       | Campaign name (default: `"Untitled"`)                                                                                                                                                                                     |
| `preview`     | unknown                          | No       | Preview/preheader text shown in email clients                                                                                                                                                                             |
| `content`     | unknown                          | No       | TipTap JSON content (object or JSON-stringified). If not provided, a default template with Hello World and unsubscribe link is used. Call get_skill({ type: "campaign" }) for the full TipTap format reference. |
| `contentType` | "MAILY" \| "PLATE" \| "MARKDOWN" | No       | Content format type (default: `"MAILY"`)                                                                                                                                                                                  |
| `senderId`    | string                           | No       | Email sender ID. If not provided, uses default sender. Call get_email_senders to list available senders.                                                                                                                  |
| `replyTo`     | unknown                          | No       | Reply-to email address                                                                                                                                                                                                    |

**Example:**

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

### Get Campaign

**Endpoint:** `POST /api/v2/tools/get_campaign`

Get detailed information about a specific campaign by ID. Returns `senderId`, `sender` (`id`, `name`, `email`), `replyTo`, `recipientFilters`, `content`, `preview`, and `contentType`.

**Parameters:**

| Parameter    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `campaignId` | string | Yes      |             |

**Example:**

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

### Get Campaign Progress

**Endpoint:** `POST /api/v2/tools/get_campaign_progress`

Get the sending progress of a campaign that is currently being sent.

**Parameters:**

| Parameter    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `campaignId` | string | Yes      |             |

**Example:**

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

### Get Campaign Analytics

**Endpoint:** `POST /api/v2/tools/get_campaign_analytics`

Get detailed analytics for a sent campaign including opens, clicks, and link performance.

**Parameters:**

| Parameter    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `campaignId` | string | Yes      |             |

**Example:**

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

### Duplicate Campaign

**Endpoint:** `POST /api/v2/tools/duplicate_campaign`

Create a complete copy of a campaign including all content and settings. The duplicate will be a DRAFT.

**Parameters:**

| Parameter    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `campaignId` | string | Yes      |             |
| `newName`    | string | No       |             |

**Example:**

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

### Edit Campaign

**Endpoint:** `POST /api/v2/tools/edit_campaign`

The ONLY tool for modifying campaigns (name, subject, preview, senderId, replyTo, content).

TWO exclusive modes:

- "content": full TipTap JSON document ({ type: "doc", content: [...] }) — for new content or a complete rewrite.
- "operations": array of surgical edits on the existing content (replace_text, insert_node, append_node, prepend_node, remove_node, replace_node) — cheaper for a typo, a link, adding a CTA, removing a paragraph.
  Metadata fields (name, subject, preview, senderId, replyTo) can be combined with either mode. NEVER send content and operations together.

BEFORE writing any content or operations, call get_skill({ type: "campaign" }). It documents the TipTap node types, text marks, "Show if" tag conditions, the exact operations syntax and the mandatory rules. Do not guess the format from memory.

WHEN NOT TO USE:

- Listing/searching campaigns -> use list_campaigns
- Getting campaign details -> use get_campaign
- Updating recipient filters -> use update_campaign_filters

**Parameters:**

| Parameter    | Type    | Required | Description                                                                                                                                                                                                                        |
| ------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | string  | Yes      | Campaign ID to update                                                                                                                                                                                                              |
| `name`       | string  | No       | New campaign name                                                                                                                                                                                                                  |
| `subject`    | string  | No       | New subject line                                                                                                                                                                                                                   |
| `preview`    | unknown | No       | New preview/preheader text                                                                                                                                                                                                         |
| `content`    | unknown | No       | Full TipTap JSON document ({ type: 'doc', content: [...] }). Send as a parsed object (preferred) or a JSON-stringified value - both are accepted. Use for complete content rewrites. Cannot be combined with operations. |
| `operations` | array   | No       | Array of surgical edit operations to apply to existing content. Cannot be combined with content.                                                                                                                                   |
| `senderId`   | string  | No       | Email sender ID. Call get_email_senders to list available senders.                                                                                                                                                                 |
| `replyTo`    | unknown | No       | Reply-to email address. Pass null to clear.                                                                                                                                                                                        |
| `contentType` | "MAILY" \| "PLATE" \| "MARKDOWN" | No       | Content format type.                                                                                                                                                                                                               |

**Example:**

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

### Auto Fit Campaign Images

**Endpoint:** `POST /api/v2/tools/auto_fit_campaign_images`

Apply the editor's magic-wand auto-fit to a draft campaign's images: reads each image's natural dimensions and fits it without upscaling. Always run with dryRun=true first to inspect the proposed sizes. Call get_skill({ type: "images" }) for the full sequence, sizing rules and safety limits.

**Parameters:**

| Parameter      | Type    | Required | Description                                                                                                       |
| -------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `campaignId`   | string  | Yes      | Campaign or internal workflow email ID.                                                                           |
| `imageIndexes` | array   | No       | Optional image indexes from this tool's dry-run output. Omit to auto-fit every image in document traversal order. |
| `maxWidth`     | integer | No       | (default: `600`)                                                                                                  |
| `maxHeight`    | integer | No       | (default: `400`)                                                                                                  |
| `dryRun`       | boolean | No       | Inspect and calculate dimensions without changing the campaign. (default: `false`)                                |

**Example:**

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

### Get Available Filters

**Endpoint:** `POST /api/v2/tools/get_available_filters`

Get the machine-readable filter schema (types, operators, required fields) used by update_campaign_filters, query_subscribers and segments. Prefer get_skill({ type: 'filters' }), which also documents how to resolve each ID.

**Parameters:**

No parameters required.

**Example:**

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

### Update Campaign Filters

**Endpoint:** `POST /api/v2/tools/update_campaign_filters`

Update the recipient filters of a DRAFT campaign. Filters are combined with AND. Call get_skill({ type: 'filters' }) first for the filter shapes, operators and how to resolve each ID.

**Parameters:**

| Parameter    | Type   | Required | Description               |
| ------------ | ------ | -------- | ------------------------- |
| `campaignId` | string | Yes      | Campaign ID to update     |
| `filters`    | array  | Yes      | Array of filters to apply |

**Example:**

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

### Send Test Email

**Endpoint:** `POST /api/v2/tools/send_test_email`

Send a test email for a campaign to one or more email addresses (max 5). The test email will have '[Test]' prefix in the subject. Test emails are not tracked in analytics.

**Parameters:**

| Parameter    | Type   | Required | Description                           |
| ------------ | ------ | -------- | ------------------------------------- |
| `campaignId` | string | Yes      | Campaign ID to send test for          |
| `emails`     | array  | Yes      | Email addresses to send test to (1-5) |

**Example:**

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

### Render Campaign

**Endpoint:** `POST /api/v2/tools/render_campaign`

Render a campaign to its final HTML and plain text exactly as delivered (snippets inlined, variables resolved, unsubscribe footer added). Nothing is sent. Use it to self-verify content before schedule_campaign. Pass subscriberId to resolve variables and "Show if" conditions for that subscriber; otherwise all conditional blocks are shown.

**Parameters:**

| Parameter      | Type                       | Required | Description                                                            |
| -------------- | -------------------------- | -------- | ---------------------------------------------------------------------- |
| `campaignId`   | string                     | Yes      | Campaign ID to render                                                  |
| `subscriberId` | string                     | No       | Optional subscriber ID to resolve variables and conditional blocks for |
| `format`       | "html" \| "text" \| "both" | No       | Which output to return (default: both)                                 |

**Example:**

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

### Schedule Campaign

**Endpoint:** `POST /api/v2/tools/schedule_campaign`

Schedule a DRAFT campaign (status becomes SCHEDULED). The campaign must contain an unsubscribe link. No date sends immediately; a date without time sends at midnight in the given timezone.

**Parameters:**

| Parameter    | Type    | Required | Description                                                                                           |
| ------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `campaignId` | string  | Yes      | Campaign ID to schedule                                                                               |
| `date`       | string  | No       | Date to schedule (ISO format, e.g. '2025-03-20'). If omitted, sends immediately.                      |
| `hours`      | integer | No       | Hour to send (0-23)                                                                                   |
| `minutes`    | integer | No       | Minutes (0-59)                                                                                        |
| `timezone`   | string  | No       | Timezone for the scheduled time (e.g. 'Europe/Paris', 'America/New_York') (default: `"Europe/Paris"`) |

**Example:**

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

### Cancel Campaign Schedule

**Endpoint:** `POST /api/v2/tools/cancel_campaign_schedule`

Cancel a scheduled campaign, reverting it back to DRAFT status. Only works on SCHEDULED campaigns (not SENDING or SENT).

**Parameters:**

| Parameter    | Type   | Required | Description                        |
| ------------ | ------ | -------- | ---------------------------------- |
| `campaignId` | string | Yes      | Campaign ID to cancel schedule for |

**Example:**

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

### List Campaign History

**Endpoint:** `POST /api/v2/tools/list_campaign_history`

List version history entries for a campaign. Returns entries sorted by most recent first with cursor-based pagination. Each entry shows when it was saved and the source (autosave, manual, or ai).

**Parameters:**

| Parameter    | Type    | Required | Description                                                       |
| ------------ | ------- | -------- | ----------------------------------------------------------------- |
| `campaignId` | string  | Yes      | Campaign ID to get history for                                    |
| `cursor`     | string  | No       | Cursor for pagination (history entry ID from previous page)       |
| `limit`      | integer | No       | Number of entries to return (default 20, max 100) (default: `20`) |

**Example:**

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

### Get Campaign History Entry

**Endpoint:** `POST /api/v2/tools/get_campaign_history_entry`

Get a specific campaign history entry with full content. Use this to inspect what the campaign looked like at a specific point in time before restoring it.

**Parameters:**

| Parameter    | Type   | Required | Description                  |
| ------------ | ------ | -------- | ---------------------------- |
| `campaignId` | string | Yes      | Campaign ID                  |
| `historyId`  | string | Yes      | History entry ID to retrieve |

**Example:**

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

### Restore Campaign History

**Endpoint:** `POST /api/v2/tools/restore_campaign_history`

Restore a campaign to a previous version from its history. This updates the campaign's subject and content to match the selected history entry, and creates a new history entry recording the restoration.

**Parameters:**

| Parameter    | Type   | Required | Description                      |
| ------------ | ------ | -------- | -------------------------------- |
| `campaignId` | string | Yes      | Campaign ID to restore           |
| `historyId`  | string | Yes      | History entry ID to restore from |

**Example:**

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

### Archive Campaign

**Endpoint:** `POST /api/v2/tools/archive_campaign`

Archive a DRAFT campaign. Archived campaigns are hidden from the main campaign list but can be restored with unarchive_campaign. Only DRAFT campaigns can be archived.

**Parameters:**

| Parameter    | Type   | Required | Description            |
| ------------ | ------ | -------- | ---------------------- |
| `campaignId` | string | Yes      | Campaign ID to archive |

**Example:**

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

### Unarchive Campaign

**Endpoint:** `POST /api/v2/tools/unarchive_campaign`

Restore an ARCHIVED campaign back to DRAFT status so it can be edited and scheduled again.

**Parameters:**

| Parameter    | Type   | Required | Description              |
| ------------ | ------ | -------- | ------------------------ |
| `campaignId` | string | Yes      | Campaign ID to unarchive |

**Example:**

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

## Workflow Tools

### List Workflows

**Endpoint:** `POST /api/v2/tools/list_workflows`

List graph-based workflow automations.

**Parameters:**

| Parameter | Type    | Required | Description     |
| --------- | ------- | -------- | --------------- |
| `limit`   | integer | No       | (default: `20`) |
| `query`   | string  | No       |                 |

**Example:**

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

### Get Workflow

**Endpoint:** `POST /api/v2/tools/get_workflow`

Get a Workflow draft graph, published version information, settings, and active subscriber count.

**Parameters:**

| Parameter    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `workflowId` | string | Yes      |             |

**Example:**

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

### Create Workflow

**Endpoint:** `POST /api/v2/tools/create_workflow`

Create a graph-based Workflow draft. It must be configured and published before it can enroll subscribers.

**Parameters:**

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `name`    | string | Yes      |             |

**Example:**

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

### Configure Workflow Draft

**Endpoint:** `POST /api/v2/tools/configure_workflow_draft`

Configure an entire Workflow draft (steps, edges, waits, branches, actions, goals, settings) in one atomic operation. Never publishes or sends. Call get_skill({ type: 'workflow' }) then get_workflow first - the skill documents the step types, edges, eventFilters keys and the EMAIL-step rule that replaces create_campaign.

**Parameters:**

| Parameter           | Type   | Required | Description                                       |
| ------------------- | ------ | -------- | ------------------------------------------------- |
| `workflowId`        | string | Yes      |                                                   |
| `expectedUpdatedAt` | string | Yes      | Exact updatedAt returned by get_workflow          |
| `settings`          | object | No       |                                                   |
| `steps`             | array  | Yes      | Complete replacement list of Workflow steps       |
| `edges`             | array  | Yes      | Complete replacement list of directed graph edges |
| `successGoals`      | array  | No       |                                                   |

**Example:**

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

### Update Workflow Draft

**Endpoint:** `POST /api/v2/tools/update_workflow_draft`

Replace a Workflow draft graph atomically. The full {steps, edges} definition is validated before it is saved. Every EMAIL step is ownership-checked; foreign or broadcast campaign IDs are duplicated into dedicated internal WORKFLOW emails before saving.

**Parameters:**

| Parameter           | Type   | Required | Description                                                                                                                                                                                                             |
| ------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflowId`        | string | Yes      |                                                                                                                                                                                                                         |
| `expectedUpdatedAt` | string | Yes      |                                                                                                                                                                                                                         |
| `definition`        | object | Yes      | Complete Workflow graph. Use configure_workflow_draft to add EMAIL steps with inline content. Existing campaign IDs are ownership-checked and duplicated rather than linked when they do not belong to that exact step. |

**Example:**

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

### Publish Workflow

**Endpoint:** `POST /api/v2/tools/publish_workflow`

Validate and publish the current Workflow draft as a new immutable version. Activation: publishing never deactivates a live workflow and never re-activates a paused one; pass activate:true to go live, activate:false to publish paused. When omitted, only a first publish (DRAFT) activates.

**Parameters:**

| Parameter    | Type    | Required | Description                                                                                                                         |
| ------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `workflowId` | string  | Yes      |                                                                                                                                     |
| `activate`   | boolean | No       | true: activate after publishing. false: keep the workflow paused. Omitted: first publish activates, a paused workflow stays paused. |

**Example:**

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

### Update Workflow Status

**Endpoint:** `POST /api/v2/tools/update_workflow_status`

Activate, pause, or archive a published Workflow.

**Parameters:**

| Parameter    | Type                               | Required | Description |
| ------------ | ---------------------------------- | -------- | ----------- |
| `workflowId` | string                             | Yes      |             |
| `status`     | "ACTIVE" \| "PAUSED" \| "ARCHIVED" | Yes      |             |

**Example:**

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

### Add Subscriber To Workflow

**Endpoint:** `POST /api/v2/tools/add_subscriber_to_workflow`

Manually enroll a subscriber in an active, published Workflow.

**Parameters:**

| Parameter      | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `workflowId`   | string | Yes      |             |
| `subscriberId` | string | No       |             |
| `email`        | string | No       |             |
| `stepId`       | string | No       | Published step to start from |

**Example:**

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

### Add Subscribers To Workflow

**Endpoint:** `POST /api/v2/tools/add_subscribers_to_workflow`

Manually enroll a filtered subscriber set in an active published Workflow — same as Subscribers → Select all → Add to workflow. Call with `dryRun: true` first.

**Parameters:**

| Parameter       | Type    | Required | Description |
| --------------- | ------- | -------- | ----------- |
| `workflowId`    | string  | Yes      |             |
| `stepId`        | string  | No       | Published step to start from |
| `filters`       | array   | No       | Same filters as `query_subscribers` |
| `query`         | string  | No       | Free-text search |
| `status`        | string  | No       | Defaults to `SUBSCRIBED` |
| `subscriberIds` | array   | No       | Explicit IDs instead of filters. Max 500 |
| `dryRun`        | boolean | No       | Preview match count and published steps |

**Example:**

```bash
curl -X POST https://lumail.io/api/v2/tools/add_subscribers_to_workflow \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflowId":"workflow-id","dryRun":true,"filters":[]}'
```

### Remove Subscriber From Workflow

**Endpoint:** `POST /api/v2/tools/remove_subscriber_from_workflow`

Cancel active Workflow runs for a subscriber.

**Parameters:**

| Parameter      | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `workflowId`   | string | Yes      |             |
| `subscriberId` | string | No       |             |
| `email`        | string | No       |             |

**Example:**

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

### Get Subscriber Workflow Runs

**Endpoint:** `POST /api/v2/tools/get_subscriber_workflow_runs`

List a subscriber's workflow runs in this organization: status, current step, and nextActionAt. Active and waiting runs first, then recent completed or failed runs.

**Parameters:**

| Parameter      | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `subscriberId` | string | No       |             |
| `email`        | string | No       |             |
| `workflowId`   | string | No       | If set, only return runs for this workflow. |

**Example:**

```bash
curl -X POST https://lumail.io/api/v2/tools/get_subscriber_workflow_runs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
```

### Fast Forward Workflow Subscriber

**Endpoint:** `POST /api/v2/tools/fast_forward_workflow_subscriber`

Expire the current WAIT or WAIT_UNTIL timer on one subscriber's run and resume the runner immediately. The next EMAIL or ACTION executes for real. One call completes one wait. WAIT_UNTIL follows the TIMEOUT edge.

**Parameters:**

| Parameter               | Type   | Required | Description |
| ----------------------- | ------ | -------- | ----------- |
| `workflowId`            | string | Yes      |             |
| `subscriberId`          | string | No       |             |
| `email`                 | string | No       |             |
| `workflowSubscriberId`  | string | No       | Required when more than one waiting run exists |

**Example:**

```bash
curl -X POST https://lumail.io/api/v2/tools/fast_forward_workflow_subscriber \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflowId":"workflow-id","email":"you@example.com"}'
```

### Delete Workflow

**Endpoint:** `POST /api/v2/tools/delete_workflow`

Delete an unused Workflow draft, or archive it when published versions or run history must be preserved.

**Parameters:**

| Parameter    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `workflowId` | string | Yes      |             |

**Example:**

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

### List Workflow Groups

**Endpoint:** `POST /api/v2/tools/list_workflow_groups`

List Workflow groups with their conflict strategy and assigned workflow count. Call this before assigning a groupId; never invent a group ID.

**Parameters:**

| Parameter | Type    | Required | Description     |
| --------- | ------- | -------- | --------------- |
| `query`   | string  | No       |                 |
| `limit`   | integer | No       | (default: `50`) |

**Example:**

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

### Get Workflow Group

**Endpoint:** `POST /api/v2/tools/get_workflow_group`

Get a Workflow group, its assigned workflows, and current active-run counts.

**Parameters:**

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `groupId` | string | Yes      |             |

**Example:**

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

### Create Workflow Group

**Endpoint:** `POST /api/v2/tools/create_workflow_group`

Create a Workflow group. The operation is idempotent when a case-insensitive name match already has the requested strategy.

**Parameters:**

| Parameter          | Type                                                | Required | Description                    |
| ------------------ | --------------------------------------------------- | -------- | ------------------------------ |
| `name`             | string                                              | Yes      |                                |
| `conflictStrategy` | "CANCEL_EXISTING" \| "SKIP_NEW" \| "RUN_FIRST_STEP" | No       | (default: `"CANCEL_EXISTING"`) |

**Example:**

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

### Update Workflow Group

**Endpoint:** `POST /api/v2/tools/update_workflow_group`

Rename a Workflow group or change its conflict strategy for future enrollments. Requires a fresh get_workflow_group read and optimistic concurrency.

**Parameters:**

| Parameter           | Type                                                | Required | Description |
| ------------------- | --------------------------------------------------- | -------- | ----------- |
| `groupId`           | string                                              | Yes      |             |
| `expectedUpdatedAt` | string                                              | Yes      |             |
| `name`              | string                                              | No       |             |
| `conflictStrategy`  | "CANCEL_EXISTING" \| "SKIP_NEW" \| "RUN_FIRST_STEP" | No       |             |

**Example:**

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

### Set Workflow Group

**Endpoint:** `POST /api/v2/tools/set_workflow_group`

Assign a Workflow to an existing group, or detach it with groupId:null, without replacing its graph or publishing. The change affects future enrollments only.

**Parameters:**

| Parameter           | Type    | Required | Description |
| ------------------- | ------- | -------- | ----------- |
| `workflowId`        | string  | Yes      |             |
| `expectedUpdatedAt` | string  | Yes      |             |
| `groupId`           | unknown | Yes      |             |

**Example:**

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

### Delete Workflow Group

**Endpoint:** `POST /api/v2/tools/delete_workflow_group`

Permanently delete a Workflow group after a fresh read. Refuses to delete an assigned group unless unassignWorkflows:true is explicit.

**Parameters:**

| Parameter           | Type    | Required | Description        |
| ------------------- | ------- | -------- | ------------------ |
| `groupId`           | string  | Yes      |                    |
| `expectedName`      | string  | Yes      |                    |
| `expectedUpdatedAt` | string  | Yes      |                    |
| `unassignWorkflows` | boolean | No       | (default: `false`) |

**Example:**

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

## Segment Tools

### List Segments

**Endpoint:** `POST /api/v2/tools/list_segments`

List saved subscriber segments in your organization.

**Parameters:**

| Parameter | Type    | Required | Description     |
| --------- | ------- | -------- | --------------- |
| `limit`   | integer | No       | (default: `20`) |

**Example:**

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

### Get Segment

**Endpoint:** `POST /api/v2/tools/get_segment`

Get detailed information about a specific segment including all filter configurations.

**Parameters:**

| Parameter   | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `segmentId` | string | Yes      |             |

**Example:**

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

### Create Segment

**Endpoint:** `POST /api/v2/tools/create_segment`

Create a new subscriber segment with filter configuration.

**Parameters:**

| Parameter | Type   | Required | Description     |
| --------- | ------ | -------- | --------------- |
| `name`    | string | Yes      |                 |
| `filters` | array  | No       | (default: `[]`) |

**Example:**

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

### Update Segment

**Endpoint:** `POST /api/v2/tools/update_segment`

Update a segment's name or filter configuration.

**Parameters:**

| Parameter   | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `segmentId` | string | Yes      |             |
| `name`      | string | No       |             |
| `filters`   | array  | No       |             |

**Example:**

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

### Delete Segment

**Endpoint:** `POST /api/v2/tools/delete_segment`

Permanently delete a segment.

**Parameters:**

| Parameter   | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `segmentId` | string | Yes      |             |

**Example:**

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

### Duplicate Segment

**Endpoint:** `POST /api/v2/tools/duplicate_segment`

Create a copy of a segment with all its filters.

**Parameters:**

| Parameter   | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `segmentId` | string | Yes      |             |
| `newName`   | string | No       |             |

**Example:**

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

## Analytics Tools

### Get Org Stats

**Endpoint:** `POST /api/v2/tools/get_org_stats`

Get overall organization statistics including subscriber counts, campaign metrics, and resource totals.

**Parameters:**

No parameters required.

**Example:**

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

### Get Subscriber Growth

**Endpoint:** `POST /api/v2/tools/get_subscriber_growth`

Analyze subscriber growth over a specified time period. Shows new subscribers, unsubscribes, and net growth.

**Parameters:**

| Parameter | Type    | Required | Description     |
| --------- | ------- | -------- | --------------- |
| `days`    | integer | No       | (default: `30`) |

**Example:**

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

### Get Subscriber Stats

**Endpoint:** `POST /api/v2/tools/get_subscriber_stats`

Get subscriber growth and status statistics for your organization.

**Parameters:**

No parameters required.

**Example:**

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

### Get Subscribers By Tag

**Endpoint:** `POST /api/v2/tools/get_subscribers_by_tag`

Get all subscribers that have a specific tag. Useful for understanding tag usage.

**Parameters:**

| Parameter | Type    | Required | Description     |
| --------- | ------- | -------- | --------------- |
| `tagName` | string  | Yes      |                 |
| `limit`   | integer | No       | (default: `10`) |

**Example:**

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

### Count Subscribers By Status

**Endpoint:** `POST /api/v2/tools/count_subscribers_by_status`

Get subscriber count by status. Optionally filter by a specific status.

**Parameters:**

| Parameter | Type                                                                    | Required | Description |
| --------- | ----------------------------------------------------------------------- | -------- | ----------- |
| `status`  | "SUBSCRIBED" \| "UNSUBSCRIBED" \| "BOUNCED" \| "BANNED" \| "COMPLAINED" | No       |             |

**Example:**

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

## Settings Tools

### Get Writing Style

**Endpoint:** `POST /api/v2/tools/get_writing_style`

Get the organization's default writing style for content generation including persona, audience, vocabulary, and rules.

**Parameters:**

No parameters required.

**Example:**

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

### Update Writing Style

**Endpoint:** `POST /api/v2/tools/update_writing_style`

Modify writing style settings (persona, audience, vocabulary, rules)

**Parameters:**

| Parameter    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `name`       | string | No       |             |
| `persona`    | string | No       |             |
| `audience`   | string | No       |             |
| `vocabulary` | string | No       |             |
| `rules`      | string | No       |             |

**Example:**

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

### Get Email Senders

**Endpoint:** `POST /api/v2/tools/get_email_senders`

List all configured email senders (from addresses) for this organization.

**Parameters:**

No parameters required.

**Example:**

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

### Get Custom Fields

**Endpoint:** `POST /api/v2/tools/get_custom_fields`

List all custom subscriber field definitions for this organization.

**Parameters:**

No parameters required.

**Example:**

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

### Get Email Snippets

**Endpoint:** `POST /api/v2/tools/get_email_snippets`

List email snippets (reusable content blocks) for this organization. Use get_email_snippet to read a snippet's content.

**Parameters:**

| Parameter         | Type    | Required | Description                                |
| ----------------- | ------- | -------- | ------------------------------------------ |
| `includeArchived` | boolean | No       | Include archived snippets (default: false) |

**Example:**

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

### Get Email Snippet

**Endpoint:** `POST /api/v2/tools/get_email_snippet`

Get a single email snippet by id (snp\_...) including its full TipTap JSON content. Use this before update_email_snippet to read the current content.

**Parameters:**

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `id`      | string | Yes      | Snippet id, e.g. snp\_... |

**Example:**

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

### Create Email Snippet

**Endpoint:** `POST /api/v2/tools/create_email_snippet`

Create a new email snippet (reusable content block). Content is TipTap JSON with the same node types as campaigns: { type: "doc", content: [...] }. Snippets can then be referenced inside campaign content.

**Parameters:**

| Parameter     | Type    | Required | Description                                                                                      |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------ |
| `name`        | string  | Yes      | Snippet name                                                                                     |
| `description` | string  | No       | Optional description                                                                             |
| `content`     | unknown | No       | TipTap JSON content: { type: "doc", content: [...] }. Omit to create an empty snippet. |

**Example:**

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

### Update Email Snippet

**Endpoint:** `POST /api/v2/tools/update_email_snippet`

Update an email snippet by id (snp\_...): name, description, and/or its TipTap JSON content ({ type: "doc", content: [...] }, same node types as campaigns). Content updates apply everywhere the snippet is used. Read the current content with get_email_snippet first when editing.

**Parameters:**

| Parameter     | Type    | Required | Description                                                                                              |
| ------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `id`          | string  | Yes      | Snippet id, e.g. snp\_...                                                                                |
| `name`        | string  | No       | New snippet name                                                                                         |
| `description` | string  | No       | New description                                                                                          |
| `content`     | unknown | No       | New TipTap JSON content: { type: "doc", content: [...] }. Replaces the entire snippet content. |

**Example:**

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

### Archive Email Snippet

**Endpoint:** `POST /api/v2/tools/archive_email_snippet`

Archive an email snippet by id (snp\_...). Archived snippets are hidden from the snippet list but existing campaigns referencing them keep working. Restore with unarchive_email_snippet.

**Parameters:**

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `id`      | string | Yes      | Snippet id, e.g. snp\_... |

**Example:**

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

### Unarchive Email Snippet

**Endpoint:** `POST /api/v2/tools/unarchive_email_snippet`

Restore an archived email snippet by id (snp\_...).

**Parameters:**

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `id`      | string | Yes      | Snippet id, e.g. snp\_... |

**Example:**

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

### Update Organization Settings

**Endpoint:** `POST /api/v2/tools/update_organization_settings`

Update organization name and timezone

**Parameters:**

| Parameter  | Type   | Required | Description             |
| ---------- | ------ | -------- | ----------------------- |
| `name`     | string | No       | Organization name       |
| `timezone` | string | No       | Timezone in IANA format |

**Example:**

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

## Skill Tools

### Get Available Variables

**Endpoint:** `POST /api/v2/tools/get_available_variables`

Get all available variables for email content (built-in, organization, custom fields, snippets)

**Parameters:**

No parameters required.

**Example:**

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

### Get Skill

**Endpoint:** `POST /api/v2/tools/get_skill`

Get task-specific documentation. Call it BEFORE writing content, filters, or a workflow graph - never guess a format from memory. Types: 'campaign' (TipTap content + edit_campaign operations), 'filters' (subscriber/recipient filter shapes), 'workflow' (draft graph), 'sending' (domain, DNS and sender setup), 'images', 'snippets', 'templates', 'variables', 'copywriter', 'onboarding', 'docs' (full product docs catalog, or one page with `page`).

**Parameters:**

| Parameter | Type                                                                                                                                       | Required | Description            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ---------------------- |
| `type`    | "campaign" \| "snippets" \| "templates" \| "variables" \| "copywriter" \| "filters" \| "images" \| "sending" \| "workflow" \| "onboarding" \| "docs" | Yes      | Skill type to retrieve |
| `page`    | string                                                                                                                                     | No       | With `type: "docs"`, the page slug (example: `workflows/workflow-manual-enrollment`) |

**Example:**

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

## Email Tools

### Send Email

**Endpoint:** `POST /api/v2/tools/send_email`

Send a transactional email to a subscriber. The 'from' address must use a verified domain.

**Parameters:**

| Parameter        | Type    | Required | Description |
| ---------------- | ------- | -------- | ----------- |
| `from`           | string  | Yes      | Verified domain mailbox |
| `to`             | string  | Yes      | One address, or a one-item array |
| `subject`        | string  | Yes      |             |
| `html`           | string  | No       | Exactly one of `html` or `tiptap` |
| `tiptap`         | unknown | No       | Exactly one of `html` or `tiptap` |
| `text`           | string  | No       | Generated from HTML when omitted. `""` skips generation |
| `reply_to`       | string  | No       | Single address (string or one-item array) |
| `replyTo`        | string  | No       | Alias of `reply_to` |
| `cc`             | array   | No       |             |
| `headers`        | object  | No       |             |
| `tags`           | array   | No       | `{ name, value }` |
| `preview`        | string  | No       |             |
| `idempotencyKey` | string  | No       |             |

`content`, `contentType`, and `markdown` are rejected.

**Example:**

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

## Domain Tools

### List Domains

**Endpoint:** `POST /api/v2/tools/list_domains`

List the organization's email sending domains with their verification status. Call get_skill({ type: 'sending' }) for the full domain and sender setup flow.

**Parameters:**

No parameters required.

**Example:**

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

### Create Domain

**Endpoint:** `POST /api/v2/tools/create_domain`

Register a new email sending domain and return the DNS records the user must add. Call get_skill({ type: 'sending' }) first for the full setup flow.

**Parameters:**

| Parameter | Type   | Required | Description                                   |
| --------- | ------ | -------- | --------------------------------------------- |
| `domain`  | string | Yes      | The domain to register, e.g. mail.example.com |

**Example:**

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

### Get Domain Dns Records

**Endpoint:** `POST /api/v2/tools/get_domain_dns_records`

Get a domain's DNS records with their per-record verification status, to show the user what to configure and what is still pending.

**Parameters:**

| Parameter  | Type   | Required | Description       |
| ---------- | ------ | -------- | ----------------- |
| `domainId` | string | Yes      | The MailDomain id |

**Example:**

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

### Verify Domain

**Endpoint:** `POST /api/v2/tools/verify_domain`

Re-check a domain's verification, DKIM and MAIL FROM state and return the updated per-record DNS statuses. Call get_skill({ type: 'sending' }) for what to do with the result.

**Parameters:**

| Parameter  | Type   | Required | Description       |
| ---------- | ------ | -------- | ----------------- |
| `domainId` | string | Yes      | The MailDomain id |

**Example:**

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

### Create Email Sender

**Endpoint:** `POST /api/v2/tools/create_email_sender`

Create an email sender (from-address) as localPart@domain on an already VERIFIED domain. Call get_skill({ type: 'sending' }) for the prerequisites.

**Parameters:**

| Parameter     | Type    | Required | Description                                              |
| ------------- | ------- | -------- | -------------------------------------------------------- |
| `displayName` | string  | Yes      | The display name shown in the From header                |
| `localPart`   | string  | Yes      | The part before the @, e.g. 'hello' in hello@example.com |
| `domainId`    | string  | Yes      | The verified MailDomain id                               |
| `replyTo`     | unknown | No       | Optional reply-to email address                          |

**Example:**

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

## Deliverability Tools

### Get Deliverability Health

**Endpoint:** `POST /api/v2/tools/get_deliverability_health`

Assess the organization's deliverability health (sender reputation). Omit sinceDays for the all-time trust score; pass it for a windowed sent/delivered/bounced/complained report with verdicts.

**Parameters:**

| Parameter   | Type    | Required | Description |
| ----------- | ------- | -------- | ----------- |
| `sinceDays` | integer | No       |             |

**Example:**

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

### List Suppressed Subscribers

**Endpoint:** `POST /api/v2/tools/list_suppressed_subscribers`

List suppressed subscribers (BOUNCED and/or COMPLAINED), most recently suppressed first, with pagination. Each entry includes the most recent bounce/complaint event details (bounceCategory, reason, bounceType, provider, complaintFeedbackType).

**Parameters:**

| Parameter  | Type                      | Required | Description     |
| ---------- | ------------------------- | -------- | --------------- |
| `status`   | "BOUNCED" \| "COMPLAINED" | No       |                 |
| `page`     | integer                   | No       | (default: `1`)  |
| `pageSize` | integer                   | No       | (default: `50`) |

**Example:**

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

### Reactivate Subscriber

**Endpoint:** `POST /api/v2/tools/reactivate_subscriber`

Reactivate a suppressed subscriber (BOUNCED, COMPLAINED, or UNSUBSCRIBED) by setting their status back to SUBSCRIBED. Refuses hard bounces (bounceCategory NO_SUCH_USER or INTERNAL / SES suppression list) unless 'force' is true.

**Parameters:**

| Parameter      | Type    | Required | Description |
| -------------- | ------- | -------- | ----------- |
| `subscriberId` | string  | Yes      |             |
| `force`        | boolean | No       |             |

**Example:**

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

## Image Tools

### Upload Image

**Endpoint:** `POST /api/v2/tools/upload_image`

Import an image from a public http/https URL into your organization media library. Fetches the image, validates it is an image under 2MB, uploads it to storage, and returns the hosted image with a URL that can be used directly in campaign image blocks.

**Parameters:**

| Parameter     | Type   | Required | Description                                                                                                                                                      |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`         | string | Yes      | Public http(s) URL of the image to import.                                                                                                                       |
| `name`        | string | No       | Optional display name for the imported image.                                                                                                                    |
| `description` | string | No       | Short description of what the image shows (subject, colors, intended usage). Strongly recommended: this is what makes the image findable later with list_images. |

**Example:**

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

### List Images

**Endpoint:** `POST /api/v2/tools/list_images`

Search the organization media library. The query matches both the image name and its description, so you can search by what the image shows (e.g. 'logo', 'hero photo'). Newest first.

**Parameters:**

| Parameter       | Type    | Required | Description                                                                               |
| --------------- | ------- | -------- | ----------------------------------------------------------------------------------------- |
| `query`         | string  | No       | Optional case-insensitive search matched against both the image name and its description. |
| `capturePageId` | string  | No       | Only return images uploaded for this capture page. Omit to search the whole library.      |
| `page`          | integer | No       | (default: `1`)                                                                            |
| `pageSize`      | integer | No       | (default: `50`)                                                                           |

**Example:**

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

### Describe Image

**Endpoint:** `POST /api/v2/tools/describe_image`

Set or update the description of an image already in the media library. Use it right after a user uploads an image so it becomes findable later with list_images. Accepts either the image id or its URL.

**Parameters:**

| Parameter     | Type   | Required | Description                                                                            |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `imageId`     | string | No       | Id of the image. Provide either imageId or url.                                        |
| `url`         | string | No       | URL of the image. Provide either imageId or url.                                       |
| `description` | string | Yes      | What the image shows: subject, dominant colors, and how it should be used on the page. |
| `name`        | string | No       | Optional human-readable name replacing the raw filename.                               |

**Example:**

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

## Import and export Tools

### Import Subscribers

**Endpoint:** `POST /api/v2/tools/import_subscribers`

Bulk import subscribers (up to 500 per call). Existing subscribers are updated, new ones created, and workflows are NOT triggered by default. Returns imported/updated/failed counts with per-row errors.

**Parameters:**

| Parameter          | Type    | Required | Description                                                                                    |
| ------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------- |
| `subscribers`      | array   | Yes      |                                                                                                |
| `resubscribe`      | boolean | No       | Re-subscribe previously unsubscribed contacts. (default: `false`)                              |
| `triggerWorkflows` | boolean | No       | Trigger automation workflows on import. Defaults to false for bulk imports. (default: `false`) |

**Example:**

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

### Export Subscribers

**Endpoint:** `POST /api/v2/tools/export_subscribers`

Export subscribers from your organization. Optionally filter by status and tag name. Returns JSON objects or a CSV string with email, name, phone, status, tags, custom fields, and creation date. Respects a configurable limit (default 1000, max 10000).

**Parameters:**

| Parameter | Type                                                                                              | Required | Description                            |
| --------- | ------------------------------------------------------------------------------------------------- | -------- | -------------------------------------- |
| `status`  | "PENDING_CONFIRMATION" \| "SUBSCRIBED" \| "UNSUBSCRIBED" \| "BOUNCED" \| "BANNED" \| "COMPLAINED" \| "TRANSACTIONAL" | No       |                                        |
| `tag`     | string                                                                                            | No       | Filter by tag name (case-insensitive). |
| `format`  | "json" \| "csv"                                                                                   | No       | (default: `"json"`)                    |
| `limit`   | integer                                                                                           | No       | (default: `1000`)                      |

**Example:**

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

## Web Tools

### Fetch Web Page

**Endpoint:** `POST /api/v2/tools/fetch_web_page`

Fetch a web page and convert to markdown format

**Parameters:**

| Parameter | Type   | Required | Description                                                                 |
| --------- | ------ | -------- | --------------------------------------------------------------------------- |
| `url`     | string | Yes      | The full URL of the web page to fetch (must start with http:// or https://) |

**Example:**

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

## Related Documentation

- [API Tokens](/docs/api-reference/api-tokens) - Create and manage API tokens
- [API Limits](/docs/api-reference/api-limits) - Rate limiting information
- [MCP Integration](/docs/api-reference/mcp) - Use tools via Model Context Protocol