Tools API (v2)

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:

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

Execute a tool:

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:

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

Error:

{
  "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:

Available Tools (92 total)

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

curl -X POST https://lumail.io/api/v2/tools/update_subscriber \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subscriber":"[email protected]","name":"Ada"}'

Unsubscribe

Endpoint: POST /api/v2/tools/unsubscribe

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

Parameters:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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":"[email protected]"}'

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:

Example:

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":"[email protected]"}'

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

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:

Example:

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:

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:

Example:

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:

Example:

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:

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:

Example:

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:

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:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

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:

Example:

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:

content, contentType, and markdown are rejected.

Example:

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:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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:

Example:

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 - Create and manage API tokens
• API Limits - Rate limiting information
• MCP Integration - Use tools via Model Context Protocol