Call this server's tools from your browser. Nothing to install.
https://api.chatwithhal.com/mcp
Bearer <key>: an account MCP key or a project MCP key (hal_mk_…), created in HAL under Settings → API.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
cancel_broadcast
Cancel a scheduled, in-progress, or paused broadcast. Recipients not yet sent to are marked cancelled.
Target project ID
Target project slug (helpdesk slug)
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Configure a custom sender domain for visitor-facing email on this project (Starter plan and above). Returns DNS records (DKIM CNAMEs, and MX/TXT if a mail-from subdomain is set) that the user must add themselves at their DNS provider before the domain can verify. Reply-To stays on the HAL inbound address so inbound routing keeps working, unless a Reply-To override is set afterwards with update_sender_identity.
Argument
Type
Description
domain*
string
The domain to send from, e.g. mail.yourcompany.com
local_part*
string
The local part of the From address, e.g. "support"
project_id
string
Target project ID
sender_name
string
Display name to use in From. Defaults to the project name.
project_slug
string
Target project slug (helpdesk slug)
mail_from_subdomain
string
Optional custom MAIL FROM subdomain label, e.g. "bounce"
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"domain",
"local_part"
],
"properties": {
"domain": {
"type": "string",
"description": "The domain to send from, e.g. mail.yourcompany.com"
},
"local_part": {
"type": "string",
"description": "The local part of the From address, e.g. \"support\""
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"sender_name": {
"type": "string",
"description": "Display name to use in From. Defaults to the project name."
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"mail_from_subdomain": {
"type": "string",
"description": "Optional custom MAIL FROM subdomain label, e.g. \"bounce\""
}
}
}
create_article
Create an article with an initial translation
Argument
Type
Description
slug*
string
URL-friendly slug
title*
string
Article title
locale
string
Locale for the initial translation
content*
string
Article content (Markdown)
group_id
string | null
Group ID (null for ungrouped)
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
show_in_helpdesk
boolean
Whether to show this article in the helpdesk (defaults to true)
New to HAL email? Call get_email_capabilities_overview first. Create a draft (or scheduled, if scheduled_at is set) one-off email broadcast. Does not send anything.
Argument
Type
Description
name*
string
theme
object
blocks
array
Shortcut for template_document.blocks
ab_test
object
Optional automatic A/B test: a random test group gets variant A (the main email) or B; after duration_hours the variant with the better winner_metric is sent to everyone else. Needs track_engagement on and at least 10 recipients.
subject*
string
Email subject
audience
object
Defaults to all contacts with an email
category
string
EmailCategory key (see list_email_categories); defaults to "marketing"
preheader
string
Email preheader
project_id
string
Target project ID
create_company
Create a new company
Argument
Type
Description
name*
string
Company name
notes
string
Notes
domain
string
Company domain
industry
string
Industry
metadata
object
Flat custom metadata (max 50 keys, 10KB). Values: string, number, boolean, or null. Replaces entire object on write.
Create a deal for a company. The company's own stage and value follow its primary deal (its newest open new-business deal).
Argument
Type
Description
name
string
Deal name. Defaults to the company name.
notes
string | null
amount
any
Deal amount in the project's sales currency and value unit
source
string | null
Where the deal came from, e.g. inbound, outbound, referral
contacts
array
People involved in the deal
stage_id
string | null
CRM stage ID (see list_crm_stages). A 100% stage means won, 0% means lost.
deal_type
string
new_business, expansion or renewal
next_step
string | null
The next action to move the deal
company_id*
string
project_id
string
Target project ID
create_email_campaign
New to HAL email? Call get_email_capabilities_overview first. Create an email campaign using campaign language instead of workflow graph internals.
Argument
Type
Description
name*
string
enabled
boolean
trigger*
object
frequency
string
conditions
array
project_id
string
Target project ID
template_id
string
email_design
object
project_slug
string
Target project slug (helpdesk slug)
delay_seconds
number
email_category
string
Defaults to "marketing" if omitted
create_email_template
New to HAL email? Call get_email_capabilities_overview first. Create a reusable workflow email template.
Argument
Type
Description
name*
string
theme
object
blocks
array
Shortcut for template_document.blocks
subject*
string
Email subject
preheader
string
Email preheader
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
template_document
object
Structured email document
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name",
"subject"
],
"properties": {
"name": {
"type": "string"
},
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"preheader": {
"type": "string",
"description": "Email preheader"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
},
"description": "Structured email document"
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
create_guide
Create a new guide
Argument
Type
Description
name*
string
Guide name (internal label, not shown to visitors). A slug for host-page calls is generated from it and returned.
steps*
array
Guide steps
title
object
Guide title by locale, e.g. {"en":"Change your plan"}. Shown to visitors.
enabled
boolean
Whether enabled
frequency
string
How often to show
start_url
string
Where this guide runs, as a same-origin path template against the visitor's stored properties, e.g. "{{app_base_path}}/documents/add/invoice". When a visitor starts the guide from elsewhere, the widget navigates there first (via the host router when available). Same-origin paths only; missing properties fail closed to popup mode.
conditions
object
Audience conditions, evaluated server-side: an ineligible visitor receives nothing at all. guide.completed:<id> and event.count:<name> enable completion-style targeting (e.g. not_exists on guide.completed:<onboarding-id>).
project_id
string
Target project ID
create_webhook
Create a new webhook
Argument
Type
Description
url*
string
The webhook URL to receive events
events*
array
Event types to subscribe to (e.g. conversation.created, message.created)
New to HAL email? Call get_email_capabilities_overview first. Create a visitor workflow: a trigger plus a branching graph of condition/send_widget_message/send_email/trigger_campaign/end nodes. Call get_workflow_builder_reference first.
Argument
Type
Description
name*
string
enabled
boolean
priority
integer
frequency
string
definition*
object
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
trigger_mode
string
trigger_type*
string
trigger_config
object
Shape depends on trigger_type; call get_workflow_builder_reference first.
delete_broadcast
Delete a broadcast. Refused while it is actively sending.
Find published help articles that fit a conversation, in the visitor's language and limited to ones this visitor may see. Matches the visitor's latest message, or `query` when given. Returns up to 6, best match first; weaker results can be only loosely related, so check the title and excerpt before sharing one. Read-only; uses no AI quota. Each result has `insert`, the exact markup to put in the reply. To show a help article to the visitor, write `[label](hal-article:<article id or slug>)` into the `content` of reply_to_conversation. The widget renders it as a clickable card at that spot, on its own line (it is not an inline link inside a sentence), so put it between sentences or paragraphs, e.g. "Refunds take 5 days.\n[Refund policy](hal-article:refund-policy)\nAnything else?". The label is the card title, so use the article title. Several cards in one reply are fine. Only published articles the visitor may see are accepted; each reference is checked and rewritten to the slug for the visitor's language. Find the right article with find_relevant_articles (matched to the conversation, or to your own query), or list_articles with published_only.
Argument
Type
Description
query
string
What to look for, e.g. 'refund policy'. Defaults to the visitor's latest message.
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
conversation_id*
string
The conversation to find articles for
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"conversation_id"
],
"properties": {
"query": {
"type": "string",
"description": "What to look for, e.g. 'refund policy'. Defaults to the visitor's latest message."
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"conversation_id": {
"type": "string",
"description": "The conversation to find articles for"
}
}
}
generate_ai_response_suggestion
Generate an advisory-only HAL AI reply suggestion for the latest visitor message. Call this after get_conversation, then combine HAL's draft, evidence, and confidence with the conversation messages when composing your final answer. This tool never sends a message to the visitor, even when project auto-send or AI deflection is enabled.
Get a single email broadcast, including delivery/open/click counts. With an A/B test, `ab_test` has its settings, `phase` (testing, waiting, winner_sending, done, skipped, cancelled), `ends_at` (automatic winner pick), the `winner`, and `results` (test-group sent/opens/clicks/rates per variant plus a confidence score).
Deliverability checklist for a broadcast before sending: sender authentication (custom domain, DMARC, MAIL FROM/SPF), postal address, project bounce/complaint health, warm-up capacity (how many days the send will be spread over), and content lint (size, image-heavy, subject, spam phrases, link shorteners). `error` checks block sending; share warnings with the user.
Get a conversation with its messages and attachment metadata. agents_typing lists teammates drafting a reply right now; if someone is, let them answer instead of replying over them. replied_to_email is set when the conversation started as a reply to a campaign, workflow or broadcast email. Call get_conversation_image with an image attachment ID to inspect its visual content. To incorporate HAL's own evidence-backed AI draft into your final answer, call generate_ai_response_suggestion next.
Get an image attached to a conversation message as MCP image content so the AI client can inspect it. Images over 2 MB are resized and compressed before delivery. Use an attachment ID returned by get_conversation.
Argument
Type
Description
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
attachment_id*
string
The image attachment ID returned by get_conversation
Summarize the sales pipeline: per stage the number of deals, total and probability-weighted amount, plus open/won/lost totals, win rate and open deals whose expected close date has passed. Use list_deals for the deals themselves.
Orientation for HAL email features: campaigns vs workflows vs broadcasts, templates vs project defaults vs inline design, sender domains, images, test sending, track_event, and unsubscribe/suppression. Call this before creating any campaign, workflow, broadcast, or template.
Project email reporting. Always returns: health (last 30 days across every campaign, workflow and broadcast: sent, sent_last_24h, delivered, hard bounces (bounced), soft bounces, complaints and their rates, plus the status that blocks broadcasts, and reset_at when a list-cleanup reset restarted the window), sources (the same window broken down per workflow/broadcast with delivered, hard/soft bounces, unique opens, clicks and replies), warm-up progress (only broadcasts count toward it), and the footer postal address. Pass workflow_id or broadcast_id (optionally with days; omitted = all time) to also get stats for that one campaign. Opens and clicks exclude automatic ones from security scanners and Apple Mail Privacy Protection, which are reported as automatic_opens/automatic_clicks. Replies count recipients who answered the email (auto-replies are ignored). Delivered counts only cover emails sent after delivery tracking was enabled.
Argument
Type
Description
days
integer
Trailing window for the workflow_id/broadcast_id stats; omitted = all time
Get the custom sender domain (Starter plan and above) configured for this project, including DNS records, verification status, and any Reply-To override (`sender_domain.reply_to`, alongside the top-level `reply_to` this project's emails actually use).
New to HAL email? Call get_email_capabilities_overview first. Static reference for building visitor workflows through create_workflow/update_workflow/validate_workflow: trigger shapes, node types, graph rules, condition/predicate operators, email block types, and variable syntax.
No arguments.
Input schema (JSON)
{
"type": "object",
"properties": {}
}
get_workflow_email_defaults
Get the project default email design used to seed new send_email nodes.
Import a single historical conversation silently (no webhooks, no notifications). Use for migrating data from other chat platforms.
Argument
Type
Description
visitor*
object
Visitor info — matched by email first, then user_id, then external_id, or creates new
messages*
array
Messages to import (1-1000, ordered chronologically)
project_id
string
Target project ID
conversation
object
Conversation metadata (defaults to resolved status)
project_slug
string
Target project slug (helpdesk slug)
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"visitor",
"messages"
],
"properties": {
"visitor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Visitor display name"
},
"email": {
"type": "string",
"description": "Visitor email (used for matching existing visitors)"
},
"user_id": {
"type": "string",
"description": "Authenticated user ID from source system"
},
"external_id": {
"type": "string",
"description": "External ID from source system"
}
},
"description": "Visitor info — matched by email first, then user_id, then external_id, or creates new"
},
"messages": {
"type": "array",
"items": {
"type": "object",
"required": [
"role",
"content"
],
"properties": {
"role": {
"enum": [
"visitor",
"agent",
"system"
],
"type": "string",
"description": "Who sent the message"
},
"content": {
"type": "string",
"description": "Message content"
},
"created_at": {
"type": "string",
"description": "ISO 8601 timestamp (messages auto-spaced 1s apart if omitted)"
},
"is_internal": {
"type": "boolean",
"default": false,
"description": "Whether this is an internal note (not visible to visitor)"
},
"sender_name": {
"type": "string",
"description": "Display name of the sender"
},
"sender_email": {
"type": "string",
"description": "Email of the sender"
}
}
},
"maxItems": 1000,
"minItems": 1,
"description": "Messages to import (1-1000, ordered chronologically)"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"conversation": {
"type": "object",
"properties": {
"status": {
"enum": [
"open",
"resolved"
],
"type": "string",
"default": "resolved",
"description": "Conversation status (default: resolved)"
},
"created_at": {
"type": "string",
"description": "ISO 8601 timestamp for when the conversation was created"
},
"external_id": {
"type": "string",
"description": "External ID from source system (stored for reference)"
}
},
"description": "Conversation metadata (defaults to resolved status)"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}
import_conversations
Import multiple historical conversations in batch (max 100). Each conversation is imported independently — one failure does not affect others. Silent: no webhooks, no notifications.
Argument
Type
Description
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
conversations*
array
Conversations to import (1-100)
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"conversations"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"conversations": {
"type": "array",
"items": {
"type": "object",
"required": [
"visitor",
"messages"
],
"properties": {
"visitor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Visitor display name"
},
"email": {
"type": "string",
"description": "Visitor email (used for matching existing visitors)"
},
"user_id": {
"type": "string",
"description": "Authenticated user ID from source system"
},
"external_id": {
"type": "string",
"description": "External ID from source system"
}
},
"description": "Visitor info"
},
"messages": {
"type": "array",
"items": {
"type": "object",
"required": [
"role",
"content"
],
"properties": {
"role": {
"enum": [
"visitor",
"agent",
"system"
],
"type": "string",
"description": "Who sent the message"
},
"content": {
"type": "string",
"description": "Message content"
},
"created_at": {
"type": "string",
"description": "ISO 8601 timestamp (messages auto-spaced 1s apart if omitted)"
},
"is_internal": {
"type": "boolean",
"default": false,
"description": "Whether this is an internal note (not visible to visitor)"
},
"sender_name": {
"type": "string",
"description": "Display name of the sender"
},
"sender_email": {
"type": "string",
"description": "Email of the sender"
}
}
},
"maxItems": 1000,
"minItems": 1,
"description": "Messages (1-1000)"
},
"conversation": {
"type": "object",
"properties": {
"status": {
"enum": [
"open",
"resolved"
],
"type": "string",
"default": "resolved",
"description": "Conversation status (default: resolved)"
},
"created_at": {
"type": "string",
"description": "ISO 8601 timestamp for when the conversation was created"
},
"external_id": {
"type": "string",
"description": "External ID from source system (stored for reference)"
}
},
"description": "Conversation metadata"
}
}
},
"maxItems": 100,
"minItems": 1,
"description": "Conversations to import (1-100)"
}
}
}
link_contact_to_company
Link an existing contact to an existing company. The operation is idempotent and both records must belong to the selected project.
List articles, optionally filtered by group or to published ones. To show a help article to the visitor, write `[label](hal-article:<article id or slug>)` into the `content` of reply_to_conversation. The widget renders it as a clickable card at that spot, on its own line (it is not an inline link inside a sentence), so put it between sentences or paragraphs, e.g. "Refunds take 5 days.\n[Refund policy](hal-article:refund-policy)\nAnything else?". The label is the card title, so use the article title. Several cards in one reply are fine. Only published articles the visitor may see are accepted; each reference is checked and rewritten to the slug for the visitor's language. Find the right article with find_relevant_articles (matched to the conversation, or to your own query), or list_articles with published_only.
Argument
Type
Description
group_id
string
Filter by group ID
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
published_only
boolean
Only published articles, the ones that can be shared with a visitor
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"group_id": {
"type": "string",
"description": "Filter by group ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"published_only": {
"type": "boolean",
"description": "Only published articles, the ones that can be shared with a visitor"
}
}
}
Read-only CRM board: list ALL companies grouped by pipeline stage, including companies with no linked contacts and unstaged companies. Returns per-stage deal totals so agents can reconcile Won totals with company rows. Company stage and deal value mirror the company primary deal; use list_deals to see every deal, including expansions and renewals.
Argument
Type
Description
stage_id
string
Optional: only include companies in this stage. Omits unstaged when set.
project_id
string
Target project ID
stage_name
string
Optional: filter by stage name (case-insensitive, e.g. "Won"). Omits unstaged when set. Do not combine with stage_id.
project_slug
string
Target project slug (helpdesk slug)
include_unstaged
boolean
Include companies with no stage. Default true. Ignored when stage_id or stage_name is set.
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"stage_id": {
"type": "string",
"description": "Optional: only include companies in this stage. Omits unstaged when set."
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"stage_name": {
"type": "string",
"description": "Optional: filter by stage name (case-insensitive, e.g. \"Won\"). Omits unstaged when set. Do not combine with stage_id."
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"include_unstaged": {
"type": "boolean",
"default": true,
"description": "Include companies with no stage. Default true. Ignored when stage_id or stage_name is set."
}
}
}
List deals (sales opportunities). A company can have several deals: new business, expansion, renewal. Each deal has a stage, amount, expected close date, owner, next step and contacts. Filter by company, contact, stage, owner or status.
Argument
Type
Description
limit
number
offset
number
search
string
Search deal and company names
status
string
stage_id
string | null
Pass null for deals with no stage
company_id
string
contact_id
string
Deals this contact takes part in
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
owner_user_id
string
Input schema (JSON)
list_email_campaign_runs
List email campaign runs with delivery, open, and click data.
List a project's email categories used for per-category unsubscribe/preferences (marketing, product updates, transactional, ...). A project with no customized categories returns the built-in defaults.
Merge a duplicate company into a keeper. Contacts, tracked events, and CRM timeline move to the keeper; the source company is deleted. Use when the same org has a HAL-generated row and a later source-system (e.g. Apollo) id row. Refuses to merge companies that already have different external ids.
Argument
Type
Description
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
keeper_company_id*
string
Company to keep. Prefer the older row when hydrating a source-system id.
source_company_id*
string
Duplicate company to absorb and delete
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"keeper_company_id",
"source_company_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"keeper_company_id": {
"type": "string",
"description": "Company to keep. Prefer the older row when hydrating a source-system id."
},
"source_company_id": {
"type": "string",
"description": "Duplicate company to absorb and delete"
}
}
}
preview_broadcast_audience
Preview who a broadcast (or a candidate audience) would reach: match count, suppressed count, contacts left out by list hygiene (invalid/disposable/role addresses, unengaged, recently emailed) per reason, and a sample.
Argument
Type
Description
audience
object
Override audience to preview before saving
category
string
Only used with audience (no broadcast_id); defaults to "marketing"
project_id
string
Target project ID
broadcast_id
string
Preview the audience already saved on this broadcast
project_slug
string
Target project slug (helpdesk slug)
skip_unengaged
boolean
Leave out contacts who got 5+ emails in the last 180 days without opening or clicking any (default true)
skip_role_addresses
boolean
Leave out shared role mailboxes like info@ or admin@ (default false)
skip_recently_emailed
boolean
Frequency cap: leave out contacts who got a broadcast in the last 24h (default true)
Input schema (JSON)
preview_email_template
Render an email template preview as subject, preheader, HTML, and plain text.
Argument
Type
Description
theme
object
blocks
array
Shortcut for template_document.blocks
subject
string
Email subject
preheader
string
Email preheader
project_id
string
Target project ID
template_id
string
project_slug
string
Target project slug (helpdesk slug)
workflow_name
string
sample_context
object
template_document
object
Structured email document
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"preheader": {
"type": "string",
"description": "Email preheader"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"template_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"workflow_name": {
"type": "string"
},
"sample_context": {
"type": "object",
"properties": {
"company_id": {
"type": "string"
},
"company_name": {
"type": "string"
},
"visitor_name": {
"type": "string"
},
"company_stage": {
"type": "string"
},
"visitor_email": {
"type": "string"
},
"visitor_user_id": {
"type": "string"
},
"browser_language": {
"type": "string"
},
"company_metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"contact_metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"visitor_metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"company_contact_count": {
"type": "number"
}
}
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
},
"description": "Structured email document"
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
Send an agent message to a conversation. To show a help article to the visitor, write `[label](hal-article:<article id or slug>)` into the `content` of reply_to_conversation. The widget renders it as a clickable card at that spot, on its own line (it is not an inline link inside a sentence), so put it between sentences or paragraphs, e.g. "Refunds take 5 days.\n[Refund policy](hal-article:refund-policy)\nAnything else?". The label is the card title, so use the article title. Several cards in one reply are fine. Only published articles the visitor may see are accepted; each reference is checked and rewritten to the slug for the visitor's language. Find the right article with find_relevant_articles (matched to the conversation, or to your own query), or list_articles with published_only. To walk the visitor through a flow, pass `offer_guide_id` instead of writing guide markup. To send files, pass `attachments`; they are delivered with the message in the widget and in email replies.
Argument
Type
Description
content
string
The message content. May contain article cards as `[label](hal-article:<article id or slug>)`, each on its own line where it belongs in the reply. May be empty when sending attachments.
project_id
string
Target project ID
attachments
array
Files to attach to the message (max 5)
is_internal
boolean
Whether this is an internal note (not visible to visitor)
project_slug
string
Target project slug (helpdesk slug)
offer_guide_id
reset_email_deliverability_health
Start a fresh 30-day health window for a project that is blocked from sending broadcasts by old bounces or complaints. ONLY use this after the bounced and complained addresses have been suppressed (list_email_suppressions / suppress_email_recipient) so the same list cannot bounce again. HAL enforces this: the reset is refused, and nothing changes, if any recipient that bounced or complained in the current window is not suppressed (by a project-wide or platform-wide suppression), and a project can be reset at most once per 30 days. Once it succeeds, sends before the reset stop counting toward the project's bounce and complaint rate, and any new bounces after it count normally and can block the project again. This only resets HAL's own project health window; it does not change the Amazon SES account reputation or review status. Per-broadcast auto-pause is not affected. Cannot be undone and is logged: get explicit user confirmation, then pass confirm: true and a reason describing the cleanup (3-500 characters). Returns the updated health (including reset_at).
Argument
Type
Description
reason*
string
What was cleaned up, e.g. "Suppressed all 312 hard-bounced addresses from the March 2026 import" (3-500 characters)
confirm*
boolean
Must be true: confirms the bounced/complained addresses were suppressed
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reason",
"confirm"
],
"properties": {
"reason": {
"type": "string",
"description": "What was cleaned up, e.g. \"Suppressed all 312 hard-bounced addresses from the March 2026 import\" (3-500 characters)"
},
"confirm": {
"type": "boolean",
"const": true,
"description": "Must be true: confirms the bounced/complained addresses were suppressed"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}
resume_broadcast
Resume a paused broadcast. Broadcasts auto-pause when their bounce or spam-complaint rate is too high, or when a scheduled send hits a blocking deliverability check; `pause_reason` says why. Only resume after the user understands the reason and has addressed it (e.g. removed bad addresses). The remaining recipients are sent to, and it pauses again if rates stay high.
End a broadcast's A/B test early and send the winner to the rest of the audience now, instead of waiting for the automatic pick. `ab_test.results` on get_broadcast shows each variant's open/click rates. Pass `variant` to choose it; omit it to send the current leader. This sends real email to the remaining recipients: confirm with the user first.
IMMEDIATELY sends this broadcast to its whole live audience - a real, irreversible email blast to real contacts, not a test. You MUST call preview_broadcast_audience first and pass its exact `count` as confirm_recipient_count; a mismatch is refused. Call get_broadcast_readiness first too: sends with blocking deliverability checks are refused. Only call this after the user has explicitly confirmed they want to send to that many recipients right now.
Argument
Type
Description
project_id
string
Target project ID
broadcast_id*
string
project_slug
string
Target project slug (helpdesk slug)
confirm_recipient_count*
integer
Must exactly equal the current preview_broadcast_audience count
Show the visitor and your teammates in the dashboard that a reply is being written. Call it right before you draft a reply the visitor will read, so a live agent sees the conversation is being handled. Do not call it for internal notes, for reading or summarizing, or when you are not going to reply. reply_to_conversation clears it; call again with is_typing false if you decide not to reply.
Argument
Type
Description
is_typing
boolean
true while you draft the reply, false to clear it without replying
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
conversation_id*
string
The conversation ID
duration_seconds
integer
Clear the indicator after this many seconds if no reply is sent
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"conversation_id"
],
"properties": {
"is_typing": {
"type": "boolean",
"default": true,
"description": "true while you draft the reply, false to clear it without replying"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"conversation_id": {
"type": "string",
"description": "The conversation ID"
},
"duration_seconds": {
"type": "integer",
"default": 60,
"maximum": 120,
"minimum": 5,
"description": "Clear the indicator after this many seconds if no reply is sent"
}
}
}
Suppress an email address so lifecycle email campaigns skip it. Defaults to category "all" (blocks everything); pass a specific category key (see list_email_categories) to block only that category.
Argument
Type
Description
note
string
email*
string
reason
string
category
string
EmailCategory key (see list_email_categories), or "all" for every category
Add tags to a message. Merges with existing tags (deduplicates). If Damper integration is enabled and a tag matches tags_to_sync, pushes the conversation to Damper as feedback.
Track a lifecycle event exactly like the public track-event API. THIS CAN SEND REAL EMAILS: matching enabled api_trigger workflows fire immediately for real contacts. Use dry_run to preview matches without tracking or sending anything. Workflows only fire for events that resolve to a visitor (via user_id or email); company-only events never trigger workflows.
Argument
Type
Description
name*
string
email
string
value
string | number | boolean | null
entity
string
dry_run
boolean
If true, does not track anything or send emails; only reports which enabled api_trigger workflows would match
user_id
string
metadata
object
Contact properties. Only fills properties the contact does not have yet (missing, null or empty), unless overwrite_metadata is true.
event_key
string
Idempotency key; a repeat call with the same key returns the original event
company_id
string
unsuppress_email_recipient
Remove an email address from the lifecycle email suppression list. Omit category to lift every suppression on the address (bounce/complaint rows are never removed); pass category to lift only that one.
Argument
Type
Description
email*
string
category
string
EmailCategory key (see list_email_categories), or "all" for every category
Update a draft or scheduled broadcast (name, email content, audience, schedule, list-hygiene or tracking options, A/B test).
Argument
Type
Description
name
string
theme
object
blocks
array
ab_test
object
Optional automatic A/B test: a random test group gets variant A (the main email) or B; after duration_hours the variant with the better winner_metric is sent to everyone else. Needs track_engagement on and at least 10 recipients.
subject
string
audience
object
category
string
EmailCategory key (see list_email_categories); defaults to "marketing"
preheader
string
project_id
string
Target project ID
broadcast_id*
string
update_company
Update a company
Argument
Type
Description
name
string
New name
notes
string
New notes
domain
string | null
New domain
industry
string | null
New industry
metadata
any
Flat custom metadata (max 50 keys, 10KB). Values: string, number, boolean, or null. Replaces entire object when set. Pass null or {} to clear.
Update conversation status, assignment, snooze state, or spam. is_spam true does what "Mark as spam" does in the inbox: the conversation leaves the inbox, is marked read, and the same sender's next conversations in this project go straight to spam; is_spam false undoes it and lets the sender back in. The change is recorded in the conversation's activity as done via MCP. Use list_conversations with spam "only" to review spam.
Argument
Type
Description
status
string
New status
is_spam
boolean
true to mark the conversation as spam, false to unmark it
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
snoozed_until
any
ISO 8601 time to snooze until (null to unsnooze)
conversation_id*
string
The conversation ID
assigned_user_id
string | null
User ID to assign (null to unassign)
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"conversation_id"
],
"properties": {
"status": {
"enum": [
"open",
"resolved"
],
"type": "string",
"description": "New status"
},
"is_spam": {
"type": "boolean",
"description": "true to mark the conversation as spam, false to unmark it"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"snoozed_until": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
],
"description": "ISO 8601 time to snooze until (null to unsnooze)"
},
"conversation_id": {
"type": "string",
"description": "The conversation ID"
},
"assigned_user_id": {
"type": [
"string",
"null"
],
"description": "User ID to assign (null to unassign)"
}
}
}
update_deal
Update a deal. Moving it to a 100% stage marks it won and a 0% stage marks it lost (pass lost_reason); moving it back to an open stage reopens it.
Argument
Type
Description
name
string
Deal name. Defaults to the company name.
notes
string | null
amount
any
Deal amount in the project's sales currency and value unit
source
string | null
Where the deal came from, e.g. inbound, outbound, referral
deal_id*
string
stage_id
string | null
CRM stage ID (see list_crm_stages). A 100% stage means won, 0% means lost.
deal_type
string
new_business, expansion or renewal
next_step
string | null
The next action to move the deal
project_id
string
Target project ID
lost_reason
string | null
Why the deal was lost. Kept only while the deal is in a lost stage.
update_email_campaign
Update an email campaign.
Argument
Type
Description
name
string
enabled
boolean
trigger
object
frequency
string
conditions
array
project_id
string
Target project ID
campaign_id*
string
template_id
string
email_design
object
project_slug
string
Target project slug (helpdesk slug)
delay_seconds
number
email_category
string
update_email_categories
Replace the full set of email categories for a project (upserts by key, removes any key not included). Refused with the referencing suppressions/broadcasts/workflows if a key still in use would be removed.
Set the physical mailing address shown in the footer of every marketing/lifecycle email (required by CAN-SPAM). Pass null or an empty string to remove it. Confirm the exact address with the user first.
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"template_id"
],
"properties": {
"name": {
"type": "string"
},
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"template_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
}
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
update_guide
Update a guide
Argument
Type
Description
name
string
New name. The slug does NOT change — host-page calls keep working across renames.
steps
array
New steps
title
object
Guide title by locale. Shown to visitors.
enabled
boolean
Enable/disable
guide_id*
string
The guide ID
frequency
string
New frequency
start_url
string
Where this guide runs — same-origin path template, e.g. "{{app_base_path}}/documents/add/invoice". Empty string clears it.
conditions
object
Audience conditions, evaluated server-side before the guide is sent. Pass an empty rules array to clear.
project_id
string
Target project ID
description
object
One-line description by locale.
update_sender_identity
Update the local part, display sender name, and/or Reply-To override of the configured sender domain, without changing the domain itself. By default, Reply-To stays on the HAL inbound address so inbound routing/threading keep working. Setting `reply_to` overrides that with the given address - it must already forward into the project's HAL inbound address, or replies will be lost. Pass an empty string or omit `reply_to` as `null` to clear an existing override and revert to the HAL address.
Argument
Type
Description
reply_to
string | null
Reply-To override, a single bare email address (e.g. [email protected]) that already forwards into the HAL inbound address. Pass an empty string or null to clear the override.
local_part
string
New local part of the From address
project_id
string
Target project ID
sender_name
string
New display name to use in From
project_slug
string
Target project slug (helpdesk slug)
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"reply_to": {
"type": [
"string",
"null"
],
"description": "Reply-To override, a single bare email address (e.g. [email protected]) that already forwards into the HAL inbound address. Pass an empty string or null to clear the override."
},
"local_part": {
"type": "string",
"description": "New local part of the From address"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"sender_name": {
"type": "string",
"description": "New display name to use in From"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}
Update a visitor workflow. Partial: only provided fields change. If trigger fields change without a new definition, the existing trigger node is synced in place.
Argument
Type
Description
name
string
enabled
boolean
priority
integer
frequency
string
definition
object
project_id
string
Target project ID
workflow_id*
string
project_slug
string
Target project slug (helpdesk slug)
trigger_mode
string
trigger_type
string
trigger_config
object
update_workflow_email_defaults
Update the project default email design (subject/preheader/theme/template_document) used to seed new send_email nodes. Merges into the project config without touching other settings.
Argument
Type
Description
theme
object
blocks
array
Shortcut for template_document.blocks
subject
string
preheader
string
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
template_document
object
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
}
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
upload_email_image
Upload an image to a project's email image library so it can be used in lifecycle/workflow email `image` blocks (email_block_types.image.url must be an absolute URL — external hosting is no longer required). Provide exactly one of data_base64 (with mime_type) or source_url. Use email_url in email image blocks (image.url).
Argument
Type
Description
alt
string
Alt text for the image
filename
string
Original filename for the data_base64 path, used to derive alt text when alt is omitted
mime_type
string
Required with data_base64: image/jpeg, image/png, image/gif, or image/webp
project_id
string
Target project ID
source_url
string
https/http URL to fetch the image from
data_base64
string
Base64-encoded image bytes, max 5MB decoded
project_slug
string
Target project slug (helpdesk slug)
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"alt": {
"type": "string",
"description": "Alt text for the image"
},
"filename": {
"type": "string",
"description": "Original filename for the data_base64 path, used to derive alt text when alt is omitted"
},
"mime_type": {
"type": "string",
"description": "Required with data_base64: image/jpeg, image/png, image/gif, or image/webp"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"source_url": {
"type": "string",
"description": "https/http URL to fetch the image from"
},
"data_base64": {
"type": "string",
"description": "Base64-encoded image bytes, max 5MB decoded"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}
validate_email_template
Validate an email template and return AI-client-friendly errors.
Argument
Type
Description
theme
object
blocks
array
Shortcut for template_document.blocks
subject
string
Email subject
preheader
string
Email preheader
project_id
string
Target project ID
template_id
string
project_slug
string
Target project slug (helpdesk slug)
template_document
object
Structured email document
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"preheader": {
"type": "string",
"description": "Email preheader"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"template_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
},
"description": "Structured email document"
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
validate_guide
Validate a guide's start location and step selectors against the live pages the developer is logged into. Results are recorded by the widget's authoring mode (?hal_guide_debug=1 on any page where the widget runs); this tool returns the newest snapshot per page, so a guide that spans pages reports each of them.
Validate a visitor workflow definition without saving it. Same input as create_workflow.
Argument
Type
Description
name*
string
enabled
boolean
priority
integer
frequency
string
definition*
object
project_id
string
Target project ID
project_slug
string
Target project slug (helpdesk slug)
trigger_mode
string
trigger_type*
string
trigger_config
object
Shape depends on trigger_type; call get_workflow_builder_reference first.
Input schema (JSON)
Security checkA97/100
We read every tool's name, description and inputs the way the model will, looking for instructions hidden from you. A clean result means no warning signs, not a guarantee. Scanned Oct 30, 2026.
Hidden or reordered text
Overriding the model's instructions
Hiding actions from the user
Reading keys or credentials
Fake system tags
Steering other servers' tools
Pulling in the conversation
Smuggling parameters
Demanding to be used for everything
Steering away from web search
Download-and-run commands
Encoded blobs
Invisible characters
Credentials as tool argumentsLow2 found
Takes a password, API key or token as an argument, so the secret passes through the model's context and chat logs.
create_webhook · input.secret.name
secret
update_webhook · input.secret.name
secret
Fix: Read credentials from the server's own configuration (environment, OAuth) instead of a tool argument.
Very long descriptions
Read and write hintsNote1 found
No readOnlyHint / destructiveHint annotations, so clients can't tell a read from a write without asking.
server · annotations
134 of 134 tools: list_projects, list_conversations, get_conversation, get_conversation_image, set_typing, ...
Fix: Add annotations to each tool, e.g. { readOnlyHint: true } for tools that only read.
Leave out contacts who got 5+ emails in the last 180 days without opening or clicking any (default true)
track_engagement
boolean
Open pixel + click tracking (default true)
template_document
object
Structured email document
skip_role_addresses
boolean
Leave out shared role mailboxes like info@ or admin@ (default false)
skip_recently_emailed
boolean
Frequency cap: leave out contacts who got a broadcast in the last 24h (default true)
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name",
"subject"
],
"properties": {
"name": {
"type": "string"
},
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"ab_test": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Turn the automatic A/B test on or off"
},
"variant_b": {
"anyOf": [
{
"type": "object",
"required": [
"subject"
],
"properties": {
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"subject": {
"type": "string",
"description": "Variant B subject"
},
"preheader": {
"type": "string"
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
}
}
}
},
{
"type": "null"
}
],
"description": "Variant B email, or null to remove it (the test must be disabled). Omit template_document/blocks for a subject-line test: variant A's current design is copied into B when this is saved, so after changing A's design, send variant_b again to copy the new one."
},
"test_percent": {
"type": "integer",
"maximum": 50,
"minimum": 10,
"description": "Share of the audience in the test group, split evenly between A and B (default 20)"
},
"winner_metric": {
"enum": [
"open_rate",
"click_rate"
],
"type": "string",
"description": "How the winner is picked (default open_rate)"
},
"duration_hours": {
"type": "integer",
"maximum": 72,
"minimum": 1,
"description": "Hours to wait after the test group is sent before picking the winner (default 4)"
}
},
"description": "Optional automatic A/B test: a random test group gets variant A (the main email) or B; after duration_hours the variant with the better winner_metric is sent to everyone else. Needs track_engagement on and at least 10 recipients."
},
"subject": {
"type": "string",
"description": "Email subject"
},
"audience": {
"type": "object",
"required": [
"operator",
"predicates"
],
"properties": {
"operator": {
"enum": [
"and",
"or"
],
"type": "string"
},
"predicates": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"field",
"value_type",
"operator"
],
"properties": {
"field": {
"type": "string"
},
"value": {
"type": "string"
},
"source": {
"enum": [
"contact",
"company",
"contact_builtin"
],
"type": "string"
},
"operator": {
"enum": [
"is_true",
"is_false",
"exists",
"not_exists",
"equals",
"not_equals",
"contains",
"not_contains",
"starts_with",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal"
],
"type": "string"
},
"value_type": {
"enum": [
"string",
"number",
"boolean",
"enum"
],
"type": "string"
},
"custom_property_id": {
"type": "string"
}
}
}
}
},
"description": "Defaults to all contacts with an email"
},
"category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "EmailCategory key (see list_email_categories); defaults to \"marketing\""
},
"preheader": {
"type": "string",
"description": "Email preheader"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"scheduled_at": {
"type": "string",
"description": "ISO datetime to schedule the send"
},
"skip_unengaged": {
"type": "boolean",
"description": "Leave out contacts who got 5+ emails in the last 180 days without opening or clicking any (default true)"
},
"track_engagement": {
"type": "boolean",
"description": "Open pixel + click tracking (default true)"
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
},
"description": "Structured email document"
},
"skip_role_addresses": {
"type": "boolean",
"description": "Leave out shared role mailboxes like info@ or admin@ (default false)"
},
"skip_recently_emailed": {
"type": "boolean",
"description": "Frequency cap: leave out contacts who got a broadcast in the last 24h (default true)"
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
lost_reason
string | null
Why the deal was lost. Kept only while the deal is in a lost stage.
project_slug
string
Target project slug (helpdesk slug)
owner_user_id
string | null
User who owns the deal
next_step_due_at
string | null
ISO 8601 date, e.g. 2026-12-31. Pass null to clear.
expected_close_date
string | null
ISO 8601 date, e.g. 2026-12-31. Pass null to clear.
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"company_id"
],
"properties": {
"name": {
"type": "string",
"description": "Deal name. Defaults to the company name."
},
"notes": {
"type": [
"string",
"null"
]
},
"amount": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
],
"description": "Deal amount in the project's sales currency and value unit"
},
"source": {
"type": [
"string",
"null"
],
"description": "Where the deal came from, e.g. inbound, outbound, referral"
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"contact_id"
],
"properties": {
"role": {
"anyOf": [
{
"enum": [
"decision_maker",
"champion",
"influencer",
"user",
"billing"
],
"type": "string"
},
{
"type": "null"
}
]
},
"contact_id": {
"type": "string"
}
}
},
"description": "People involved in the deal"
},
"stage_id": {
"type": [
"string",
"null"
],
"description": "CRM stage ID (see list_crm_stages). A 100% stage means won, 0% means lost."
},
"deal_type": {
"enum": [
"new_business",
"expansion",
"renewal"
],
"type": "string",
"description": "new_business, expansion or renewal"
},
"next_step": {
"type": [
"string",
"null"
],
"description": "The next action to move the deal"
},
"company_id": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"lost_reason": {
"type": [
"string",
"null"
],
"description": "Why the deal was lost. Kept only while the deal is in a lost stage."
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"owner_user_id": {
"type": [
"string",
"null"
],
"description": "User who owns the deal"
},
"next_step_due_at": {
"type": [
"string",
"null"
],
"description": "ISO 8601 date, e.g. 2026-12-31. Pass null to clear."
},
"expected_close_date": {
"type": [
"string",
"null"
],
"description": "ISO 8601 date, e.g. 2026-12-31. Pass null to clear."
}
}
}
skip_unengaged
boolean
Skip contacts who received 5+ emails in the last 180 days without opening, clicking or replying to any (the sunset rule broadcasts use). Ignored for categories people cannot unsubscribe from. Default false.
frequency_scope
string
next_campaign_id
string
Optional campaign id to trigger after this campaign email is sent
custom_frequency_key
string
reevaluate_conditions_at_send
boolean
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name",
"trigger"
],
"properties": {
"name": {
"type": "string"
},
"enabled": {
"type": "boolean",
"default": false
},
"trigger": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"enum": [
"first_seen",
"event",
"property_match",
"page_visit",
"no_event_after"
],
"type": "string"
},
"scope": {
"enum": [
"visitor",
"contact",
"company",
"custom_key"
],
"type": "string"
},
"pattern": {
"type": "string",
"description": "URL pattern for page_visit campaigns"
},
"operator": {
"enum": [
"and",
"or"
],
"type": "string",
"description": "Predicate join for property_match"
},
"custom_key": {
"type": "string"
},
"event_name": {
"type": "string",
"description": "Lifecycle event name for event campaigns"
},
"match_type": {
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"predicates": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"value_type",
"operator"
],
"properties": {
"field": {
"type": "string"
},
"value": {
"type": "string"
},
"source": {
"enum": [
"builtin",
"custom",
"visitor",
"contact",
"company",
"event"
],
"type": "string",
"default": "custom"
},
"operator": {
"enum": [
"is_true",
"is_false",
"exists",
"not_exists",
"equals",
"not_equals",
"contains",
"not_contains",
"starts_with",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal"
],
"type": "string",
"description": "Condition operator"
},
"value_type": {
"enum": [
"string",
"number",
"boolean",
"enum"
],
"type": "string"
},
"custom_property_id": {
"type": "string"
}
}
}
},
"anchor_event": {
"type": "string",
"description": "Anchor lifecycle event for no_event_after campaigns"
},
"missing_event": {
"type": "string",
"description": "Missing lifecycle event for no_event_after campaigns"
},
"within_seconds": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
}
}
},
"frequency": {
"enum": [
"once_ever",
"once_per_session",
"every_time",
"every_30_days",
"every_60_days",
"every_90_days"
],
"type": "string",
"default": "once_ever"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"operator"
],
"properties": {
"field": {
"type": "string",
"description": "Built-in campaign condition field or metadata field prefix"
},
"value": {
"type": "string",
"description": "Condition value for operators that need one"
},
"operator": {
"enum": [
"is_true",
"is_false",
"exists",
"not_exists",
"equals",
"not_equals",
"contains",
"not_contains",
"starts_with",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal"
],
"type": "string",
"description": "Condition operator"
}
}
}
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"template_id": {
"type": "string"
},
"email_design": {
"type": "object",
"required": [
"subject"
],
"properties": {
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"preheader": {
"type": "string",
"description": "Email preheader"
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
},
"description": "Structured email document"
}
}
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"delay_seconds": {
"type": "number",
"default": 0,
"minimum": 0
},
"email_category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "Defaults to \"marketing\" if omitted"
},
"skip_unengaged": {
"type": "boolean",
"description": "Skip contacts who received 5+ emails in the last 180 days without opening, clicking or replying to any (the sunset rule broadcasts use). Ignored for categories people cannot unsubscribe from. Default false."
},
"frequency_scope": {
"enum": [
"visitor",
"contact",
"company",
"custom_key"
],
"type": "string",
"default": "visitor"
},
"next_campaign_id": {
"type": "string",
"description": "Optional campaign id to trigger after this campaign email is sent"
},
"custom_frequency_key": {
"type": "string"
},
"reevaluate_conditions_at_send": {
"type": "boolean",
"default": false
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
description
object
One-line description by locale. Shown under the title.
project_slug
string
Target project slug (helpdesk slug)
trigger_type*
string
Trigger type
delay_seconds
number
Delay before showing
trigger_config
object
Trigger configuration
show_in_suggestions
boolean
Offer this guide to a visitor typing a matching question. Requires `title`. Independent of trigger_type: a route guide may fire on arrival and still be offered in chat.
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name",
"trigger_type",
"steps"
],
"properties": {
"name": {
"type": "string",
"description": "Guide name (internal label, not shown to visitors). A slug for host-page calls is generated from it and returned."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"title",
"content"
],
"properties": {
"type": {
"enum": [
"popup",
"tooltip"
],
"type": "string",
"description": "Step type"
},
"title": {
"type": "object",
"description": "Title by locale",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"advance": {
"type": "object",
"required": [
"on"
],
"properties": {
"on": {
"enum": [
"next",
"click",
"navigate",
"element"
],
"type": "string",
"description": "What advances past this step. Default: next (the visitor presses the button)."
},
"pattern": {
"type": "string",
"description": "URL pattern to wait for. Required for on=\"navigate\". Matched like a route trigger (see match_type)."
},
"selector": {
"type": "string",
"description": "CSS selector to wait for. Required for on=\"click\" and on=\"element\"."
},
"match_type": {
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string",
"description": "How `pattern` is matched. Default: contains."
},
"timeout_ms": {
"type": "number",
"description": "Give up waiting after this long and let the Next button take over. The Next button stays available the whole time — a waiting step never traps the visitor."
}
},
"description": "What advances past this step. Omit for Next-button only."
},
"content": {
"type": "object",
"description": "Content by locale. Supports a safe inline subset: **bold**, `code`, [text](url), and \\n line breaks.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"position": {
"enum": [
"top",
"bottom",
"left",
"right"
],
"type": "string",
"description": "Tooltip position — a preference; the widget flips and clamps to stay on screen."
},
"selector": {
"type": "string",
"description": "CSS selector for tooltip target"
},
"article_id": {
"type": "string",
"description": "Help-centre article this step links to, so a guide can hand off to the docs natively."
}
}
},
"description": "Guide steps"
},
"title": {
"type": "object",
"description": "Guide title by locale, e.g. {\"en\":\"Change your plan\"}. Shown to visitors.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"enabled": {
"type": "boolean",
"default": true,
"description": "Whether enabled"
},
"frequency": {
"enum": [
"once_ever",
"once_per_session",
"every_time"
],
"type": "string",
"default": "once_ever",
"description": "How often to show"
},
"start_url": {
"type": "string",
"description": "Where this guide runs, as a same-origin path template against the visitor's stored properties, e.g. \"{{app_base_path}}/documents/add/invoice\". When a visitor starts the guide from elsewhere, the widget navigates there first (via the host router when available). Same-origin paths only; missing properties fail closed to popup mode."
},
"conditions": {
"type": "object",
"required": [
"rules"
],
"properties": {
"match": {
"enum": [
"all",
"any"
],
"type": "string",
"description": "How rules combine. Default: all."
},
"rules": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"operator"
],
"properties": {
"field": {
"type": "string",
"description": "One of: properties.<key> (host-supplied via set/identify), visitor.first_seen_at, contact.created_at, guide.completed:<guide_id>, event.count:<event_name>"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
],
"description": "Comparison value. Required for equals/not_equals/gt/lt/in/not_in; omitted for exists/not_exists. Dates compare as dates (ISO strings)."
},
"operator": {
"enum": [
"equals",
"not_equals",
"exists",
"not_exists",
"gt",
"lt",
"in",
"not_in"
],
"type": "string",
"description": "Comparison. `not_exists` is the only operator that passes on an absent field."
}
}
},
"description": "Audience rules. Fail-closed: a rule referencing something absent excludes the visitor."
}
},
"description": "Audience conditions, evaluated server-side: an ineligible visitor receives nothing at all. guide.completed:<id> and event.count:<name> enable completion-style targeting (e.g. not_exists on guide.completed:<onboarding-id>)."
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"description": {
"type": "object",
"description": "One-line description by locale. Shown under the title.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"trigger_type": {
"enum": [
"manual",
"route",
"event"
],
"type": "string",
"description": "Trigger type"
},
"delay_seconds": {
"type": "number",
"default": 0,
"description": "Delay before showing"
},
"trigger_config": {
"type": "object",
"description": "Trigger configuration",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"show_in_suggestions": {
"type": "boolean",
"description": "Offer this guide to a visitor typing a matching question. Requires `title`. Independent of trigger_type: a route guide may fire on arrival and still be offered in chat."
}
}
}
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name",
"trigger_type",
"definition"
],
"properties": {
"name": {
"type": "string"
},
"enabled": {
"type": "boolean",
"default": false
},
"priority": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"frequency": {
"enum": [
"once_ever",
"once_per_session",
"every_time",
"every_30_days",
"every_60_days",
"every_90_days"
],
"type": "string"
},
"definition": {
"type": "object",
"required": [
"nodes"
],
"properties": {
"edges": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"target"
],
"properties": {
"id": {
"type": "string"
},
"source": {
"type": "string"
},
"target": {
"type": "string"
},
"sourceHandle": {
"enum": [
"yes",
"no"
],
"type": "string"
}
}
},
"default": []
},
"nodes": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"default": {},
"properties": {
"trigger_mode": {
"enum": [
"event",
"property"
],
"type": "string"
},
"trigger_type": {
"enum": [
"first_seen",
"first_message",
"page_visit",
"api_trigger",
"email_capture",
"nps_response",
"csat_response"
],
"type": "string"
},
"trigger_config": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"description": "Ignored on write: the trigger node data is always overwritten with the top-level trigger_mode/trigger_type/trigger_config so they stay in sync.",
"additionalProperties": {}
},
"type": {
"type": "string",
"const": "trigger"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"field",
"operator"
],
"properties": {
"field": {
"type": "string",
"description": "Condition field. Call get_workflow_builder_reference for the full list and operator rules."
},
"value": {
"type": "string",
"description": "Required unless operator is exists/not_exists/is_true/is_false"
},
"operator": {
"enum": [
"is_true",
"is_false",
"exists",
"not_exists",
"equals",
"not_equals",
"contains",
"not_contains",
"starts_with",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal"
],
"type": "string"
}
}
},
"type": {
"type": "string",
"const": "condition"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"messages",
"display_mode"
],
"properties": {
"messages": {
"type": "object",
"description": "Locale code -> message text, e.g. {\"en\": \"Hi there!\"}. At least one non-empty message is required.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"display_mode": {
"enum": [
"bubble",
"open_widget"
],
"type": "string"
},
"delay_seconds": {
"type": "number",
"default": 0,
"minimum": 0
}
}
},
"type": {
"type": "string",
"const": "send_widget_message"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"body": {
"type": "string",
"description": "Legacy plain-text email body. Only relevant for round-tripping a \"default\" template_variant node from get_workflow; new emails should use blocks instead."
},
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"template_id": {
"type": "string",
"description": "Copy a reusable email template (see list_email_templates). subject/preheader/theme override the copied values. If template_document/blocks are also given, the template is not read and template_id is kept only as provenance."
},
"delay_seconds": {
"type": "number",
"default": 0,
"minimum": 0
},
"template_name": {
"type": "string"
},
"email_category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "EmailCategory key (see list_email_categories) this email sends under, e.g. \"marketing\" or \"transactional\". Invalid/omitted is treated as \"marketing\" at send time."
},
"skip_unengaged": {
"type": "boolean",
"description": "Skip contacts who received 5+ emails in the last 180 days without opening, clicking or replying to any (the sunset rule broadcasts use). Ignored for categories people cannot unsubscribe from. Default false."
},
"next_campaign_id": {
"type": [
"string",
"null"
],
"description": "Workflow id (containing a send_email node) to trigger after this email sends"
},
"template_variant": {
"enum": [
"default",
"custom_v1"
],
"type": "string",
"description": "Usually omit this. \"default\" round-trips a legacy plain-text email node (body, no blocks) unchanged; new emails should use blocks/template_document instead."
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
},
"description": "Structured email document"
},
"reevaluate_conditions_at_send": {
"type": "boolean",
"default": false
}
}
},
"type": {
"type": "string",
"const": "send_email"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"target_workflow_id"
],
"properties": {
"target_workflow_id": {
"type": "string"
}
}
},
"type": {
"type": "string",
"const": "trigger_campaign"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"default": {},
"properties": {
"label": {
"type": "string"
}
}
},
"type": {
"type": "string",
"const": "end"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
}
]
},
"minItems": 1,
"description": "Node ids are required; choose short readable ids like \"trigger\" or \"check-plan\"."
}
}
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"trigger_mode": {
"enum": [
"event",
"property"
],
"type": "string",
"default": "event"
},
"trigger_type": {
"enum": [
"first_seen",
"first_message",
"page_visit",
"api_trigger",
"email_capture",
"nps_response",
"csat_response"
],
"type": "string"
},
"trigger_config": {
"type": "object",
"description": "Shape depends on trigger_type; call get_workflow_builder_reference first.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"audience": {
"type": "object",
"required": [
"operator",
"predicates"
],
"properties": {
"operator": {
"enum": [
"and",
"or"
],
"type": "string"
},
"predicates": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"field",
"value_type",
"operator"
],
"properties": {
"field": {
"type": "string"
},
"value": {
"type": "string"
},
"source": {
"enum": [
"contact",
"company",
"contact_builtin"
],
"type": "string"
},
"operator": {
"enum": [
"is_true",
"is_false",
"exists",
"not_exists",
"equals",
"not_equals",
"contains",
"not_contains",
"starts_with",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal"
],
"type": "string"
},
"value_type": {
"enum": [
"string",
"number",
"boolean",
"enum"
],
"type": "string"
},
"custom_property_id": {
"type": "string"
}
}
}
}
},
"description": "Override audience to preview before saving"
},
"category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "Only used with audience (no broadcast_id); defaults to \"marketing\""
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string",
"description": "Preview the audience already saved on this broadcast"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"skip_unengaged": {
"type": "boolean",
"description": "Leave out contacts who got 5+ emails in the last 180 days without opening or clicking any (default true)"
},
"skip_role_addresses": {
"type": "boolean",
"description": "Leave out shared role mailboxes like info@ or admin@ (default false)"
},
"skip_recently_emailed": {
"type": "boolean",
"description": "Frequency cap: leave out contacts who got a broadcast in the last 24h (default true)"
}
}
}
string
Offer a guide below the message. The visitor gets a button that walks them through it on the page. Use a manual, enabled guide with a title (see list_guides). Do not write the guide markup into `content` by hand.
conversation_id*
string
The conversation ID
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"conversation_id"
],
"properties": {
"content": {
"type": "string",
"default": "",
"description": "The message content. May contain article cards as `[label](hal-article:<article id or slug>)`, each on its own line where it belongs in the reply. May be empty when sending attachments."
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"required": [
"filename",
"mime_type",
"data_base64"
],
"properties": {
"filename": {
"type": "string",
"pattern": "^[^\\x00-\\x1f\\x7f]+$",
"maxLength": 255,
"minLength": 1,
"description": "File name shown to the visitor, e.g. \"invoice.pdf\""
},
"mime_type": {
"type": "string",
"description": "image/jpeg, image/png, image/gif, image/webp, application/pdf, Word (.doc/.docx), Excel (.xls/.xlsx), application/xml, text/plain, text/csv, or application/zip"
},
"data_base64": {
"type": "string",
"maxLength": 14349194,
"description": "Base64-encoded file bytes, max 10MB decoded"
}
}
},
"maxItems": 5,
"description": "Files to attach to the message (max 5)"
},
"is_internal": {
"type": "boolean",
"default": false,
"description": "Whether this is an internal note (not visible to visitor)"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"offer_guide_id": {
"type": "string",
"description": "Offer a guide below the message. The visitor gets a button that walks them through it on the page. Use a manual, enabled guide with a title (see list_guides). Do not write the guide markup into `content` by hand."
},
"conversation_id": {
"type": "string",
"description": "The conversation ID"
}
}
}
Structured email document
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"to_email"
],
"properties": {
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"to_email": {
"type": "string",
"description": "Recipient email. Must belong to a user on this account."
},
"preheader": {
"type": "string",
"description": "Email preheader"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"template_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"workflow_name": {
"type": "string"
},
"sample_context": {
"type": "object",
"properties": {
"company_id": {
"type": "string"
},
"company_name": {
"type": "string"
},
"visitor_name": {
"type": "string"
},
"company_stage": {
"type": "string"
},
"visitor_email": {
"type": "string"
},
"visitor_user_id": {
"type": "string"
},
"browser_language": {
"type": "string"
},
"company_metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"contact_metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"visitor_metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"company_contact_count": {
"type": "number"
}
}
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
},
"description": "Structured email document"
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
project_id
string
Target project ID
occurred_at
string
ISO timestamp; defaults to now
contact_name
string
project_slug
string
Target project slug (helpdesk slug)
overwrite_metadata
boolean
Replace existing contact properties with the metadata values
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"email": {
"type": "string"
},
"value": {
"type": [
"string",
"number",
"boolean",
"null"
]
},
"entity": {
"enum": [
"visitor",
"company"
],
"type": "string"
},
"dry_run": {
"type": "boolean",
"default": false,
"description": "If true, does not track anything or send emails; only reports which enabled api_trigger workflows would match"
},
"user_id": {
"type": "string"
},
"metadata": {
"type": "object",
"description": "Contact properties. Only fills properties the contact does not have yet (missing, null or empty), unless overwrite_metadata is true.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"event_key": {
"type": "string",
"maxLength": 255,
"description": "Idempotency key; a repeat call with the same key returns the original event"
},
"company_id": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"occurred_at": {
"type": "string",
"description": "ISO timestamp; defaults to now"
},
"contact_name": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"overwrite_metadata": {
"type": "boolean",
"description": "Replace existing contact properties with the metadata values"
}
}
}
Whether to show in the helpdesk
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"article_id"
],
"properties": {
"slug": {
"type": "string",
"description": "New slug"
},
"title": {
"type": "string",
"description": "Translation title (requires locale)"
},
"locale": {
"type": "string",
"description": "Locale to upsert translation for"
},
"content": {
"type": "string",
"description": "Translation content in Markdown (requires locale)"
},
"group_id": {
"type": [
"string",
"null"
],
"description": "New group ID (null for ungrouped)"
},
"article_id": {
"type": "string",
"description": "The article ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"sort_order": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "New display order"
},
"is_published": {
"type": "boolean",
"description": "Publish/unpublish"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"show_in_helpdesk": {
"type": "boolean",
"description": "Whether to show in the helpdesk"
}
}
}
project_slug
string
Target project slug (helpdesk slug)
scheduled_at
string | null
ISO datetime, or null to unschedule
skip_unengaged
boolean
Leave out contacts who got 5+ emails in the last 180 days without opening or clicking any (default true)
track_engagement
boolean
Open pixel + click tracking (default true)
template_document
object
skip_role_addresses
boolean
Leave out shared role mailboxes like info@ or admin@ (default false)
skip_recently_emailed
boolean
Frequency cap: leave out contacts who got a broadcast in the last 24h (default true)
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id"
],
"properties": {
"name": {
"type": "string"
},
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"ab_test": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Turn the automatic A/B test on or off"
},
"variant_b": {
"anyOf": [
{
"type": "object",
"required": [
"subject"
],
"properties": {
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"subject": {
"type": "string",
"description": "Variant B subject"
},
"preheader": {
"type": "string"
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
}
}
}
},
{
"type": "null"
}
],
"description": "Variant B email, or null to remove it (the test must be disabled). Omit template_document/blocks for a subject-line test: variant A's current design is copied into B when this is saved, so after changing A's design, send variant_b again to copy the new one."
},
"test_percent": {
"type": "integer",
"maximum": 50,
"minimum": 10,
"description": "Share of the audience in the test group, split evenly between A and B (default 20)"
},
"winner_metric": {
"enum": [
"open_rate",
"click_rate"
],
"type": "string",
"description": "How the winner is picked (default open_rate)"
},
"duration_hours": {
"type": "integer",
"maximum": 72,
"minimum": 1,
"description": "Hours to wait after the test group is sent before picking the winner (default 4)"
}
},
"description": "Optional automatic A/B test: a random test group gets variant A (the main email) or B; after duration_hours the variant with the better winner_metric is sent to everyone else. Needs track_engagement on and at least 10 recipients."
},
"subject": {
"type": "string"
},
"audience": {
"type": "object",
"required": [
"operator",
"predicates"
],
"properties": {
"operator": {
"enum": [
"and",
"or"
],
"type": "string"
},
"predicates": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"field",
"value_type",
"operator"
],
"properties": {
"field": {
"type": "string"
},
"value": {
"type": "string"
},
"source": {
"enum": [
"contact",
"company",
"contact_builtin"
],
"type": "string"
},
"operator": {
"enum": [
"is_true",
"is_false",
"exists",
"not_exists",
"equals",
"not_equals",
"contains",
"not_contains",
"starts_with",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal"
],
"type": "string"
},
"value_type": {
"enum": [
"string",
"number",
"boolean",
"enum"
],
"type": "string"
},
"custom_property_id": {
"type": "string"
}
}
}
}
}
},
"category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "EmailCategory key (see list_email_categories); defaults to \"marketing\""
},
"preheader": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"scheduled_at": {
"type": [
"string",
"null"
],
"description": "ISO datetime, or null to unschedule"
},
"skip_unengaged": {
"type": "boolean",
"description": "Leave out contacts who got 5+ emails in the last 180 days without opening or clicking any (default true)"
},
"track_engagement": {
"type": "boolean",
"description": "Open pixel + click tracking (default true)"
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
}
},
"skip_role_addresses": {
"type": "boolean",
"description": "Leave out shared role mailboxes like info@ or admin@ (default false)"
},
"skip_recently_emailed": {
"type": "boolean",
"description": "Frequency cap: leave out contacts who got a broadcast in the last 24h (default true)"
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
project_slug
string
Target project slug (helpdesk slug)
owner_user_id
string | null
User who owns the deal
next_step_due_at
string | null
ISO 8601 date, e.g. 2026-12-31. Pass null to clear.
expected_close_date
string | null
ISO 8601 date, e.g. 2026-12-31. Pass null to clear.
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"deal_id"
],
"properties": {
"name": {
"type": "string",
"description": "Deal name. Defaults to the company name."
},
"notes": {
"type": [
"string",
"null"
]
},
"amount": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
],
"description": "Deal amount in the project's sales currency and value unit"
},
"source": {
"type": [
"string",
"null"
],
"description": "Where the deal came from, e.g. inbound, outbound, referral"
},
"deal_id": {
"type": "string"
},
"stage_id": {
"type": [
"string",
"null"
],
"description": "CRM stage ID (see list_crm_stages). A 100% stage means won, 0% means lost."
},
"deal_type": {
"enum": [
"new_business",
"expansion",
"renewal"
],
"type": "string",
"description": "new_business, expansion or renewal"
},
"next_step": {
"type": [
"string",
"null"
],
"description": "The next action to move the deal"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"lost_reason": {
"type": [
"string",
"null"
],
"description": "Why the deal was lost. Kept only while the deal is in a lost stage."
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"owner_user_id": {
"type": [
"string",
"null"
],
"description": "User who owns the deal"
},
"next_step_due_at": {
"type": [
"string",
"null"
],
"description": "ISO 8601 date, e.g. 2026-12-31. Pass null to clear."
},
"expected_close_date": {
"type": [
"string",
"null"
],
"description": "ISO 8601 date, e.g. 2026-12-31. Pass null to clear."
}
}
}
EmailCategory key (see list_email_categories), or "all" for every category
skip_unengaged
boolean
Skip contacts who received 5+ emails in the last 180 days without opening, clicking or replying to any (the sunset rule broadcasts use). Ignored for categories people cannot unsubscribe from. Default false.
frequency_scope
string
next_campaign_id
string | null
Campaign id to trigger after this campaign email is sent, or null to clear
custom_frequency_key
string
reevaluate_conditions_at_send
boolean
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"campaign_id"
],
"properties": {
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"trigger": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"enum": [
"first_seen",
"event",
"property_match",
"page_visit",
"no_event_after"
],
"type": "string"
},
"scope": {
"enum": [
"visitor",
"contact",
"company",
"custom_key"
],
"type": "string"
},
"pattern": {
"type": "string",
"description": "URL pattern for page_visit campaigns"
},
"operator": {
"enum": [
"and",
"or"
],
"type": "string",
"description": "Predicate join for property_match"
},
"custom_key": {
"type": "string"
},
"event_name": {
"type": "string",
"description": "Lifecycle event name for event campaigns"
},
"match_type": {
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"predicates": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"value_type",
"operator"
],
"properties": {
"field": {
"type": "string"
},
"value": {
"type": "string"
},
"source": {
"enum": [
"builtin",
"custom",
"visitor",
"contact",
"company",
"event"
],
"type": "string",
"default": "custom"
},
"operator": {
"enum": [
"is_true",
"is_false",
"exists",
"not_exists",
"equals",
"not_equals",
"contains",
"not_contains",
"starts_with",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal"
],
"type": "string",
"description": "Condition operator"
},
"value_type": {
"enum": [
"string",
"number",
"boolean",
"enum"
],
"type": "string"
},
"custom_property_id": {
"type": "string"
}
}
}
},
"anchor_event": {
"type": "string",
"description": "Anchor lifecycle event for no_event_after campaigns"
},
"missing_event": {
"type": "string",
"description": "Missing lifecycle event for no_event_after campaigns"
},
"within_seconds": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
}
}
},
"frequency": {
"enum": [
"once_ever",
"once_per_session",
"every_time",
"every_30_days",
"every_60_days",
"every_90_days"
],
"type": "string",
"default": "once_ever"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"operator"
],
"properties": {
"field": {
"type": "string",
"description": "Built-in campaign condition field or metadata field prefix"
},
"value": {
"type": "string",
"description": "Condition value for operators that need one"
},
"operator": {
"enum": [
"is_true",
"is_false",
"exists",
"not_exists",
"equals",
"not_equals",
"contains",
"not_contains",
"starts_with",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal"
],
"type": "string",
"description": "Condition operator"
}
}
}
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"campaign_id": {
"type": "string"
},
"template_id": {
"type": "string"
},
"email_design": {
"type": "object",
"required": [
"subject"
],
"properties": {
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"preheader": {
"type": "string",
"description": "Email preheader"
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
},
"description": "Structured email document"
}
}
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"delay_seconds": {
"type": "number",
"minimum": 0
},
"email_category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "EmailCategory key (see list_email_categories), or \"all\" for every category"
},
"skip_unengaged": {
"type": "boolean",
"description": "Skip contacts who received 5+ emails in the last 180 days without opening, clicking or replying to any (the sunset rule broadcasts use). Ignored for categories people cannot unsubscribe from. Default false."
},
"frequency_scope": {
"enum": [
"visitor",
"contact",
"company",
"custom_key"
],
"type": "string"
},
"next_campaign_id": {
"type": [
"string",
"null"
],
"description": "Campaign id to trigger after this campaign email is sent, or null to clear"
},
"custom_frequency_key": {
"type": "string"
},
"reevaluate_conditions_at_send": {
"type": "boolean"
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
project_slug
string
Target project slug (helpdesk slug)
trigger_type
string
New trigger type
delay_seconds
number
New delay
trigger_config
object
New trigger config
show_in_suggestions
boolean
Offer this guide to a visitor typing a matching question. Independent of trigger_type.
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"guide_id"
],
"properties": {
"name": {
"type": "string",
"description": "New name. The slug does NOT change — host-page calls keep working across renames."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"title",
"content"
],
"properties": {
"type": {
"enum": [
"popup",
"tooltip"
],
"type": "string",
"description": "Step type"
},
"title": {
"type": "object",
"description": "Title by locale",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"advance": {
"type": "object",
"required": [
"on"
],
"properties": {
"on": {
"enum": [
"next",
"click",
"navigate",
"element"
],
"type": "string",
"description": "What advances past this step. Default: next (the visitor presses the button)."
},
"pattern": {
"type": "string",
"description": "URL pattern to wait for. Required for on=\"navigate\". Matched like a route trigger (see match_type)."
},
"selector": {
"type": "string",
"description": "CSS selector to wait for. Required for on=\"click\" and on=\"element\"."
},
"match_type": {
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string",
"description": "How `pattern` is matched. Default: contains."
},
"timeout_ms": {
"type": "number",
"description": "Give up waiting after this long and let the Next button take over. The Next button stays available the whole time — a waiting step never traps the visitor."
}
},
"description": "What advances past this step. Omit for Next-button only."
},
"content": {
"type": "object",
"description": "Content by locale. Supports a safe inline subset: **bold**, `code`, [text](url), and \\n line breaks.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"position": {
"enum": [
"top",
"bottom",
"left",
"right"
],
"type": "string",
"description": "Tooltip position — a preference; the widget flips and clamps to stay on screen."
},
"selector": {
"type": "string",
"description": "CSS selector for tooltip target"
},
"article_id": {
"type": "string",
"description": "Help-centre article this step links to, so a guide can hand off to the docs natively."
}
}
},
"description": "New steps"
},
"title": {
"type": "object",
"description": "Guide title by locale. Shown to visitors.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"enabled": {
"type": "boolean",
"description": "Enable/disable"
},
"guide_id": {
"type": "string",
"description": "The guide ID"
},
"frequency": {
"enum": [
"once_ever",
"once_per_session",
"every_time"
],
"type": "string",
"description": "New frequency"
},
"start_url": {
"type": "string",
"description": "Where this guide runs — same-origin path template, e.g. \"{{app_base_path}}/documents/add/invoice\". Empty string clears it."
},
"conditions": {
"type": "object",
"required": [
"rules"
],
"properties": {
"match": {
"enum": [
"all",
"any"
],
"type": "string",
"description": "How rules combine. Default: all."
},
"rules": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"operator"
],
"properties": {
"field": {
"type": "string",
"description": "One of: properties.<key> (host-supplied via set/identify), visitor.first_seen_at, contact.created_at, guide.completed:<guide_id>, event.count:<event_name>"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
],
"description": "Comparison value. Required for equals/not_equals/gt/lt/in/not_in; omitted for exists/not_exists. Dates compare as dates (ISO strings)."
},
"operator": {
"enum": [
"equals",
"not_equals",
"exists",
"not_exists",
"gt",
"lt",
"in",
"not_in"
],
"type": "string",
"description": "Comparison. `not_exists` is the only operator that passes on an absent field."
}
}
},
"description": "Audience rules. Fail-closed: a rule referencing something absent excludes the visitor."
}
},
"description": "Audience conditions, evaluated server-side before the guide is sent. Pass an empty rules array to clear."
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"description": {
"type": "object",
"description": "One-line description by locale.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"trigger_type": {
"enum": [
"manual",
"route",
"event"
],
"type": "string",
"description": "New trigger type"
},
"delay_seconds": {
"type": "number",
"description": "New delay"
},
"trigger_config": {
"type": "object",
"description": "New trigger config",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"show_in_suggestions": {
"type": "boolean",
"description": "Offer this guide to a visitor typing a matching question. Independent of trigger_type."
}
}
}
Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workflow_id"
],
"properties": {
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"priority": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"frequency": {
"enum": [
"once_ever",
"once_per_session",
"every_time",
"every_30_days",
"every_60_days",
"every_90_days"
],
"type": "string"
},
"definition": {
"type": "object",
"required": [
"nodes"
],
"properties": {
"edges": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"target"
],
"properties": {
"id": {
"type": "string"
},
"source": {
"type": "string"
},
"target": {
"type": "string"
},
"sourceHandle": {
"enum": [
"yes",
"no"
],
"type": "string"
}
}
},
"default": []
},
"nodes": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"default": {},
"properties": {
"trigger_mode": {
"enum": [
"event",
"property"
],
"type": "string"
},
"trigger_type": {
"enum": [
"first_seen",
"first_message",
"page_visit",
"api_trigger",
"email_capture",
"nps_response",
"csat_response"
],
"type": "string"
},
"trigger_config": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"description": "Ignored on write: the trigger node data is always overwritten with the top-level trigger_mode/trigger_type/trigger_config so they stay in sync.",
"additionalProperties": {}
},
"type": {
"type": "string",
"const": "trigger"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"field",
"operator"
],
"properties": {
"field": {
"type": "string",
"description": "Condition field. Call get_workflow_builder_reference for the full list and operator rules."
},
"value": {
"type": "string",
"description": "Required unless operator is exists/not_exists/is_true/is_false"
},
"operator": {
"enum": [
"is_true",
"is_false",
"exists",
"not_exists",
"equals",
"not_equals",
"contains",
"not_contains",
"starts_with",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal"
],
"type": "string"
}
}
},
"type": {
"type": "string",
"const": "condition"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"messages",
"display_mode"
],
"properties": {
"messages": {
"type": "object",
"description": "Locale code -> message text, e.g. {\"en\": \"Hi there!\"}. At least one non-empty message is required.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"display_mode": {
"enum": [
"bubble",
"open_widget"
],
"type": "string"
},
"delay_seconds": {
"type": "number",
"default": 0,
"minimum": 0
}
}
},
"type": {
"type": "string",
"const": "send_widget_message"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"body": {
"type": "string",
"description": "Legacy plain-text email body. Only relevant for round-tripping a \"default\" template_variant node from get_workflow; new emails should use blocks instead."
},
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"template_id": {
"type": "string",
"description": "Copy a reusable email template (see list_email_templates). subject/preheader/theme override the copied values. If template_document/blocks are also given, the template is not read and template_id is kept only as provenance."
},
"delay_seconds": {
"type": "number",
"default": 0,
"minimum": 0
},
"template_name": {
"type": "string"
},
"email_category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "EmailCategory key (see list_email_categories) this email sends under, e.g. \"marketing\" or \"transactional\". Invalid/omitted is treated as \"marketing\" at send time."
},
"skip_unengaged": {
"type": "boolean",
"description": "Skip contacts who received 5+ emails in the last 180 days without opening, clicking or replying to any (the sunset rule broadcasts use). Ignored for categories people cannot unsubscribe from. Default false."
},
"next_campaign_id": {
"type": [
"string",
"null"
],
"description": "Workflow id (containing a send_email node) to trigger after this email sends"
},
"template_variant": {
"enum": [
"default",
"custom_v1"
],
"type": "string",
"description": "Usually omit this. \"default\" round-trips a legacy plain-text email node (body, no blocks) unchanged; new emails should use blocks/template_document instead."
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
},
"description": "Structured email document"
},
"reevaluate_conditions_at_send": {
"type": "boolean",
"default": false
}
}
},
"type": {
"type": "string",
"const": "send_email"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"target_workflow_id"
],
"properties": {
"target_workflow_id": {
"type": "string"
}
}
},
"type": {
"type": "string",
"const": "trigger_campaign"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"default": {},
"properties": {
"label": {
"type": "string"
}
}
},
"type": {
"type": "string",
"const": "end"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
}
]
},
"minItems": 1,
"description": "Node ids are required; choose short readable ids like \"trigger\" or \"check-plan\"."
}
}
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"workflow_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"trigger_mode": {
"enum": [
"event",
"property"
],
"type": "string"
},
"trigger_type": {
"enum": [
"first_seen",
"first_message",
"page_visit",
"api_trigger",
"email_capture",
"nps_response",
"csat_response"
],
"type": "string"
},
"trigger_config": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name",
"trigger_type",
"definition"
],
"properties": {
"name": {
"type": "string"
},
"enabled": {
"type": "boolean",
"default": false
},
"priority": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"frequency": {
"enum": [
"once_ever",
"once_per_session",
"every_time",
"every_30_days",
"every_60_days",
"every_90_days"
],
"type": "string"
},
"definition": {
"type": "object",
"required": [
"nodes"
],
"properties": {
"edges": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"target"
],
"properties": {
"id": {
"type": "string"
},
"source": {
"type": "string"
},
"target": {
"type": "string"
},
"sourceHandle": {
"enum": [
"yes",
"no"
],
"type": "string"
}
}
},
"default": []
},
"nodes": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"default": {},
"properties": {
"trigger_mode": {
"enum": [
"event",
"property"
],
"type": "string"
},
"trigger_type": {
"enum": [
"first_seen",
"first_message",
"page_visit",
"api_trigger",
"email_capture",
"nps_response",
"csat_response"
],
"type": "string"
},
"trigger_config": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"description": "Ignored on write: the trigger node data is always overwritten with the top-level trigger_mode/trigger_type/trigger_config so they stay in sync.",
"additionalProperties": {}
},
"type": {
"type": "string",
"const": "trigger"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"field",
"operator"
],
"properties": {
"field": {
"type": "string",
"description": "Condition field. Call get_workflow_builder_reference for the full list and operator rules."
},
"value": {
"type": "string",
"description": "Required unless operator is exists/not_exists/is_true/is_false"
},
"operator": {
"enum": [
"is_true",
"is_false",
"exists",
"not_exists",
"equals",
"not_equals",
"contains",
"not_contains",
"starts_with",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal"
],
"type": "string"
}
}
},
"type": {
"type": "string",
"const": "condition"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"messages",
"display_mode"
],
"properties": {
"messages": {
"type": "object",
"description": "Locale code -> message text, e.g. {\"en\": \"Hi there!\"}. At least one non-empty message is required.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"display_mode": {
"enum": [
"bubble",
"open_widget"
],
"type": "string"
},
"delay_seconds": {
"type": "number",
"default": 0,
"minimum": 0
}
}
},
"type": {
"type": "string",
"const": "send_widget_message"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"body": {
"type": "string",
"description": "Legacy plain-text email body. Only relevant for round-tripping a \"default\" template_variant node from get_workflow; new emails should use blocks instead."
},
"theme": {
"type": "object",
"properties": {
"dark": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Defaults to false (light only, no dark overrides emitted)"
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
}
},
"description": "Dark-mode color overrides, applied via @media (prefers-color-scheme: dark) and Outlook.com [data-ogsc]/[data-ogsb] selectors."
},
"shadow": {
"enum": [
"none",
"sm",
"md"
],
"type": "string"
},
"spacing": {
"enum": [
"compact",
"regular",
"spacious"
],
"type": "string",
"description": "Scales block margins and card padding. Defaults to \"regular\"."
},
"link_color": {
"type": "string",
"description": "Hex color"
},
"text_color": {
"type": "string",
"description": "Hex color"
},
"font_family": {
"enum": [
"system",
"serif",
"mono",
"georgia",
"helvetica"
],
"type": "string"
},
"border_color": {
"type": "string",
"description": "Hex color"
},
"border_style": {
"enum": [
"none",
"subtle",
"strong"
],
"type": "string"
},
"button_style": {
"enum": [
"filled",
"outline"
],
"type": "string",
"description": "Defaults to \"filled\"."
},
"button_radius": {
"enum": [
"square",
"rounded",
"pill"
],
"type": "string",
"description": "Defaults to \"rounded\", which tracks corner_radius. \"square\" is 0px, \"pill\" is 999px."
},
"content_width": {
"enum": [
"narrow",
"regular",
"wide"
],
"type": "string"
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string"
},
"heading_color": {
"type": "string",
"description": "Hex color"
},
"heading_scale": {
"enum": [
"regular",
"large"
],
"type": "string",
"description": "\"large\" renders h1/h2 at 34/26px instead of 28/22px."
},
"primary_color": {
"type": "string",
"description": "Hex color"
},
"canvas_background": {
"type": "string",
"description": "Hex color"
},
"content_background": {
"type": "string",
"description": "Hex color"
},
"button_border_width": {
"enum": [
"regular",
"thin"
],
"type": "string",
"description": "Outline button border thickness. Defaults to \"regular\" (2px); \"thin\" is 1px."
}
}
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"description": "Shortcut for template_document.blocks"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"template_id": {
"type": "string",
"description": "Copy a reusable email template (see list_email_templates). subject/preheader/theme override the copied values. If template_document/blocks are also given, the template is not read and template_id is kept only as provenance."
},
"delay_seconds": {
"type": "number",
"default": 0,
"minimum": 0
},
"template_name": {
"type": "string"
},
"email_category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "EmailCategory key (see list_email_categories) this email sends under, e.g. \"marketing\" or \"transactional\". Invalid/omitted is treated as \"marketing\" at send time."
},
"skip_unengaged": {
"type": "boolean",
"description": "Skip contacts who received 5+ emails in the last 180 days without opening, clicking or replying to any (the sunset rule broadcasts use). Ignored for categories people cannot unsubscribe from. Default false."
},
"next_campaign_id": {
"type": [
"string",
"null"
],
"description": "Workflow id (containing a send_email node) to trigger after this email sends"
},
"template_variant": {
"enum": [
"default",
"custom_v1"
],
"type": "string",
"description": "Usually omit this. \"default\" round-trips a legacy plain-text email node (body, no blocks) unchanged; new emails should use blocks/template_document instead."
},
"template_document": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
}
},
"version": {
"type": "number",
"const": 1,
"default": 1
}
},
"description": "Structured email document"
},
"reevaluate_conditions_at_send": {
"type": "boolean",
"default": false
}
}
},
"type": {
"type": "string",
"const": "send_email"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"target_workflow_id"
],
"properties": {
"target_workflow_id": {
"type": "string"
}
}
},
"type": {
"type": "string",
"const": "trigger_campaign"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"default": {},
"properties": {
"label": {
"type": "string"
}
}
},
"type": {
"type": "string",
"const": "end"
},
"position": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
}
}
]
},
"minItems": 1,
"description": "Node ids are required; choose short readable ids like \"trigger\" or \"check-plan\"."
}
}
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"trigger_mode": {
"enum": [
"event",
"property"
],
"type": "string",
"default": "event"
},
"trigger_type": {
"enum": [
"first_seen",
"first_message",
"page_visit",
"api_trigger",
"email_capture",
"nps_response",
"csat_response"
],
"type": "string"
},
"trigger_config": {
"type": "object",
"description": "Shape depends on trigger_type; call get_workflow_builder_reference first.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"definitions": {
"__schema0": {
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"text",
"level"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "heading"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"level": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Heading level"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "paragraph"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"color": {
"type": "string",
"description": "Hex color override for this block only"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text",
"url"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"url": {
"type": "string",
"description": "https, http, or mailto URL"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"text": {
"type": "string",
"description": "Button label"
},
"type": {
"type": "string",
"const": "button"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"full_width": {
"type": "boolean",
"description": "Stretch the button to the full column width"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "divider"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"size": {
"enum": [
"sm",
"md",
"lg"
],
"type": "string",
"description": "Vertical spacer size"
},
"type": {
"type": "string",
"const": "spacer"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"url",
"alt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"alt": {
"type": "string",
"description": "Alt text; required"
},
"url": {
"type": "string",
"description": "https or http image URL. Call upload_email_image first to host an image and get an absolute URL."
},
"href": {
"type": "string",
"description": "Optional https, http, or mailto URL the image links to when clicked"
},
"type": {
"type": "string",
"const": "image"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "footer_note"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"style",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "list"
},
"align": {
"enum": [
"left",
"center"
],
"type": "string",
"description": "Defaults to \"left\"."
},
"items": {
"type": "array",
"items": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"maxItems": 50,
"minItems": 1
},
"style": {
"enum": [
"bullet",
"number"
],
"type": "string"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"text": {
"type": "string",
"description": "Supports **bold**, *italic*, [label](url) inline formatting"
},
"type": {
"type": "string",
"const": "quote"
},
"attribution": {
"type": "string",
"description": "Optional \"— attribution\" line under the quote"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". Consecutive blocks are grouped into a row when their widths sum to a full row: half+half, third+third+third, third+two-thirds, or two-thirds+third. Any other combination (e.g. two unpaired two-thirds blocks) falls back to full width."
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
},
{
"type": "object",
"required": [
"id",
"type",
"blocks"
],
"properties": {
"id": {
"type": "string",
"description": "Unique within the document"
},
"type": {
"type": "string",
"const": "section"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/definitions/__schema0"
},
"minItems": 1,
"description": "Child blocks. Sections cannot contain another section."
},
"padding": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"md\""
},
"background": {
"type": "string",
"description": "Hex color; defaults to transparent"
},
"full_bleed": {
"type": "boolean",
"description": "Break out of the card's horizontal padding so the background spans edge to edge"
},
"text_color": {
"type": "string",
"description": "Hex color; overrides paragraph/list/quote text color for children"
},
"layout_width": {
"enum": [
"full",
"half",
"third",
"two-thirds"
],
"type": "string",
"description": "Defaults to \"full\". A fractional width lets sibling sections group into a column row - e.g. three sections each with layout_width \"third\" render as a three-column row of intact cards (icon+heading+text stays together per card) instead of stacking icons, then headings, then text on mobile. full_bleed is ignored on a fractional-width section since escaping the card padding makes no sense for a block sitting inside a column cell."
},
"corner_radius": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Defaults to \"none\""
},
"heading_color": {
"type": "string",
"description": "Hex color; overrides heading color for children"
},
"spacing_after": {
"enum": [
"none",
"sm",
"md",
"lg"
],
"type": "string",
"description": "Overrides this block's bottom margin (0/8/18/32px, scaled by theme.spacing). Defaults to the block type's own margin."
}
}
}
]
}
}
}