HAL MCP
An official MCP server provided by HAL that allows AI agents to interact with customer support, CRM, and help center data. It enables reading conversations, managing contacts and deals, accessing knowledge base articles, and replying to messages, all enforced by HAL's server-side permissions.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
Only account owners and admins can generate itAccount owners and admins create project keys under Settings → API → Project MCP keysEvery tools/call needs a keyAuthorization: Bearer <MCP key> (or X-API-Key: <MCP key>)
MCP endpoint (Streamable HTTP)
https://api.chatwithhal.com/mcpWhat you can do with it
- Read and reply to customer conversations
- Manage CRM contacts, companies, and deals
- Search and retrieve help center articles
- List and manage conversation tags and macros
Source and maintenance
Vendor evidenceRegistry 1.0.0
Protocol and capabilities
- Server
- @chatwithhal/mcp 1.0.0
- MCP protocol
- 2025-06-18
- Tools
- 134 advertised
- Resources
- Not advertised
- Resource templates
- Not advertised
- Prompts
- Not advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
134 advertised
list_projects
List projects available to this MCP key. Call this first, then get_email_capabilities_overview for email features.
list_projects input schema
{
"type": "object",
"properties": {}
}list_conversations
List conversations with filters (status, spam, limit, offset). Each result says whether it is marked as spam.
list_conversations input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"spam": {
"enum": [
"all",
"exclude",
"only"
],
"type": "string",
"default": "all",
"description": "Spam filter: \"exclude\" hides spam like the inbox, \"only\" lists spam to review"
},
"limit": {
"type": "number",
"default": 50,
"maximum": 100,
"minimum": 1,
"description": "Max results to return"
},
"offset": {
"type": "number",
"default": 0,
"minimum": 0,
"description": "Offset for pagination"
},
"status": {
"enum": [
"open",
"resolved",
"all"
],
"type": "string",
"default": "open",
"description": "Filter by status"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_conversation
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_conversation input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"conversation_id"
],
"properties": {
"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"
}
}
}get_conversation_image
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.
get_conversation_image input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"attachment_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"attachment_id": {
"type": "string",
"description": "The image attachment ID returned by get_conversation"
}
}
}set_typing
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.
set_typing input schema
{
"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"
}
}
}reply_to_conversation
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.
reply_to_conversation input schema
{
"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"
}
}
}update_conversation
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.
update_conversation input schema
{
"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)"
}
}
}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.
generate_ai_response_suggestion input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"conversation_id"
],
"properties": {
"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"
}
}
}list_article_groups
List all article groups
list_article_groups input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}create_article_group
Create a new article group
create_article_group input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name",
"slug"
],
"properties": {
"name": {
"type": "string",
"description": "Group name"
},
"slug": {
"type": "string",
"description": "URL-friendly slug"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"description": {
"type": "string",
"description": "Group description"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"show_in_helpdesk": {
"type": "boolean",
"description": "Whether to show this group in the helpdesk (defaults to true)"
}
}
}update_article_group
Update an article group
update_article_group input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"group_id"
],
"properties": {
"name": {
"type": "string",
"description": "New name"
},
"slug": {
"type": "string",
"description": "New slug"
},
"group_id": {
"type": "string",
"description": "The group ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"sort_order": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "New display order"
},
"description": {
"type": [
"string",
"null"
],
"description": "New description"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"show_in_helpdesk": {
"type": "boolean",
"description": "Whether to show this group in the helpdesk"
}
}
}list_articles
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.
list_articles input schema
{
"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"
}
}
}find_relevant_articles
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.
find_relevant_articles input schema
{
"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"
}
}
}get_article
Get an article with translations
get_article input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"article_id"
],
"properties": {
"article_id": {
"type": "string",
"description": "The article ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}create_article
Create an article with an initial translation
create_article input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"slug",
"title",
"content"
],
"properties": {
"slug": {
"type": "string",
"description": "URL-friendly slug"
},
"title": {
"type": "string",
"description": "Article title"
},
"locale": {
"type": "string",
"default": "en",
"description": "Locale for the initial translation"
},
"content": {
"type": "string",
"description": "Article content (Markdown)"
},
"group_id": {
"type": [
"string",
"null"
],
"description": "Group ID (null for ungrouped)"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"show_in_helpdesk": {
"type": "boolean",
"description": "Whether to show this article in the helpdesk (defaults to true)"
}
}
}update_article
Update article properties or upsert a translation
update_article input schema
{
"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"
}
}
}list_contacts
List contacts with optional search
list_contacts input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "number",
"default": 50,
"maximum": 100,
"minimum": 1,
"description": "Max results"
},
"offset": {
"type": "number",
"default": 0,
"minimum": 0,
"description": "Offset for pagination"
},
"search": {
"type": "string",
"description": "Search by name or email"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_contact
Get a contact with full details, recent activity and the deals they are on
get_contact input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contact_id"
],
"properties": {
"contact_id": {
"type": "string",
"description": "The contact ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}create_contact
Create a new contact
create_contact input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"name": {
"type": "string",
"description": "Contact name"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags"
},
"email": {
"type": "string",
"description": "Contact email"
},
"notes": {
"type": "string",
"description": "Notes"
},
"phone": {
"type": "string",
"description": "Contact phone"
},
"metadata": {
"type": "object",
"description": "Flat custom metadata (max 50 keys, 10KB). Values: string, number, boolean, or null. Replaces entire object on write.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}update_contact
Update a contact
update_contact input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contact_id"
],
"properties": {
"name": {
"type": "string",
"description": "New name"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "New tags"
},
"email": {
"type": "string",
"description": "New email"
},
"notes": {
"type": "string",
"description": "New notes"
},
"phone": {
"type": "string",
"description": "New phone"
},
"metadata": {
"anyOf": [
{
"type": "object",
"description": "Flat custom metadata (max 50 keys, 10KB). Values: string, number, boolean, or null. Replaces entire object on write.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
{
"type": "null"
}
],
"description": "Flat custom metadata (max 50 keys, 10KB). Values: string, number, boolean, or null. Replaces entire object when set. Pass null or {} to clear."
},
"contact_id": {
"type": "string",
"description": "The contact ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_crm_stages
List CRM pipeline stages
list_crm_stages input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_companies
List companies with optional search and stage filter. Includes companies with no linked contacts. Paginated.
list_companies input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "number",
"default": 50,
"maximum": 100,
"minimum": 1,
"description": "Max results"
},
"offset": {
"type": "number",
"default": 0,
"minimum": 0,
"description": "Offset for pagination"
},
"search": {
"type": "string",
"description": "Search by name or notes"
},
"stage_id": {
"type": [
"string",
"null"
],
"description": "Filter by CRM stage ID. Pass null for unstaged companies only."
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_companies_by_stage
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.
list_companies_by_stage input schema
{
"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."
}
}
}get_company
Get a company with contacts, details and its deals. The company stage and deal_value mirror its primary deal.
get_company input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"company_id"
],
"properties": {
"company_id": {
"type": "string",
"description": "The company ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}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.
link_contact_to_company input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contact_id",
"company_id"
],
"properties": {
"company_id": {
"type": "string",
"description": "The company ID"
},
"contact_id": {
"type": "string",
"description": "The contact ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}create_company
Create a new company
create_company input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Company name"
},
"notes": {
"type": "string",
"description": "Notes"
},
"domain": {
"type": "string",
"description": "Company domain"
},
"industry": {
"type": "string",
"description": "Industry"
},
"metadata": {
"type": "object",
"description": "Flat custom metadata (max 50 keys, 10KB). Values: string, number, boolean, or null. Replaces entire object on write.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"stage_id": {
"type": "string",
"description": "CRM stage ID"
},
"deal_value": {
"type": "number",
"description": "Deal value"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}update_company
Update a company
update_company input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"company_id"
],
"properties": {
"name": {
"type": "string",
"description": "New name"
},
"notes": {
"type": "string",
"description": "New notes"
},
"domain": {
"type": [
"string",
"null"
],
"description": "New domain"
},
"industry": {
"type": [
"string",
"null"
],
"description": "New industry"
},
"metadata": {
"anyOf": [
{
"type": "object",
"description": "Flat custom metadata (max 50 keys, 10KB). Values: string, number, boolean, or null. Replaces entire object on write.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
{
"type": "null"
}
],
"description": "Flat custom metadata (max 50 keys, 10KB). Values: string, number, boolean, or null. Replaces entire object when set. Pass null or {} to clear."
},
"stage_id": {
"type": [
"string",
"null"
],
"description": "New stage ID"
},
"company_id": {
"type": "string",
"description": "The company ID"
},
"deal_value": {
"type": [
"number",
"null"
],
"description": "New deal value"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}merge_companies
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.
merge_companies input schema
{
"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"
}
}
}list_deals
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.
list_deals input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "number",
"default": 50,
"maximum": 200,
"minimum": 1
},
"offset": {
"type": "number",
"default": 0,
"minimum": 0
},
"search": {
"type": "string",
"description": "Search deal and company names"
},
"status": {
"enum": [
"open",
"won",
"lost"
],
"type": "string"
},
"stage_id": {
"type": [
"string",
"null"
],
"description": "Pass null for deals with no stage"
},
"company_id": {
"type": "string"
},
"contact_id": {
"type": "string",
"description": "Deals this contact takes part in"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"owner_user_id": {
"type": "string"
}
}
}get_deal_pipeline
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.
get_deal_pipeline input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_deal
Get a deal with its company, stage, contacts and stage/amount history
get_deal input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"deal_id"
],
"properties": {
"deal_id": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}create_deal
Create a deal for a company. The company's own stage and value follow its primary deal (its newest open new-business deal).
create_deal input schema
{
"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."
}
}
}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.
update_deal input schema
{
"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."
}
}
}set_deal_contact
Add a contact to a deal, or change their role on it
set_deal_contact input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"deal_id",
"contact_id"
],
"properties": {
"role": {
"anyOf": [
{
"enum": [
"decision_maker",
"champion",
"influencer",
"user",
"billing"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"deal_id": {
"type": "string"
},
"contact_id": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}remove_deal_contact
Remove a contact from a deal
remove_deal_contact input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"deal_id",
"contact_id"
],
"properties": {
"deal_id": {
"type": "string"
},
"contact_id": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}delete_deal
Delete a deal. A company with no deals left drops out of the pipeline.
delete_deal input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"deal_id"
],
"properties": {
"deal_id": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_email_capabilities_overview
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.
get_email_capabilities_overview input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
}list_email_templates
List reusable workflow email templates for a project.
list_email_templates input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_email_template
Get a reusable workflow email template.
get_email_template input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"template_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"template_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}create_email_template
New to HAL email? Call get_email_capabilities_overview first. Create a reusable workflow email template.
create_email_template input schema
{
"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."
}
}
}
]
}
}
}update_email_template
Update a reusable workflow email template.
update_email_template input schema
{
"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."
}
}
}
]
}
}
}delete_email_template
Delete a reusable workflow email template. Existing campaigns keep their embedded copy.
delete_email_template input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"template_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"template_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}preview_email_template
Render an email template preview as subject, preheader, HTML, and plain text.
preview_email_template input schema
{
"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."
}
}
}
]
}
}
}validate_email_template
Validate an email template and return AI-client-friendly errors.
validate_email_template input schema
{
"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."
}
}
}
]
}
}
}send_test_email_template
Send a workflow email template test to an account user email address only.
send_test_email_template input schema
{
"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."
}
}
}
]
}
}
}send_test_email_campaign
Send a test email for an existing email campaign to an account user email address only.
send_test_email_campaign input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"campaign_id",
"to_email"
],
"properties": {
"to_email": {
"type": "string",
"description": "Recipient email. Must belong to a user on this account."
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"campaign_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"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"
}
}
}
}
}list_email_suppressions
List email addresses suppressed for lifecycle email campaigns in a project.
list_email_suppressions input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "number",
"default": 25,
"maximum": 100,
"minimum": 1
},
"cursor": {
"type": "string"
},
"reason": {
"enum": [
"manual",
"unsubscribe",
"bounce",
"complaint"
],
"type": "string",
"default": "manual"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}suppress_email_recipient
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.
suppress_email_recipient input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email"
],
"properties": {
"note": {
"type": "string"
},
"email": {
"type": "string"
},
"reason": {
"enum": [
"manual",
"unsubscribe",
"bounce",
"complaint"
],
"type": "string",
"default": "manual"
},
"category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "EmailCategory key (see list_email_categories), or \"all\" for every category"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}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.
unsuppress_email_recipient input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email"
],
"properties": {
"email": {
"type": "string"
},
"category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "EmailCategory key (see list_email_categories), or \"all\" for every category"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_email_unsubscribe_status
Check whether an email address is currently suppressed for lifecycle email campaigns, for a given category (default "all").
get_email_unsubscribe_status input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email"
],
"properties": {
"email": {
"type": "string"
},
"category": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "EmailCategory key (see list_email_categories), or \"all\" for every category"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_email_campaigns
List email campaigns backed by visitor workflows.
list_email_campaigns input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_email_campaign
Get email campaign details.
get_email_campaign input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"campaign_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"campaign_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_event_names
List tracked lifecycle event names seen in a project.
list_event_names input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_custom_properties
List visitor custom properties and sampled metadata keys available for campaign predicates and conditions.
list_custom_properties input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"company_sample_limit": {
"type": "integer",
"default": 100,
"maximum": 250,
"minimum": 1
}
}
}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.
create_email_campaign input schema
{
"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."
}
}
}
]
}
}
}update_email_campaign
Update an email campaign.
update_email_campaign input schema
{
"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."
}
}
}
]
}
}
}enable_email_campaign
Enable an email campaign.
enable_email_campaign input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"campaign_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"campaign_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}disable_email_campaign
Disable an email campaign.
disable_email_campaign input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"campaign_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"campaign_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}delete_email_campaign
Delete an email campaign. Refuses if another workflow in the project still chains into it via trigger_campaign or next_campaign_id.
delete_email_campaign input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"campaign_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"campaign_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_email_campaign_runs
List email campaign runs with delivery, open, and click data.
list_email_campaign_runs input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"campaign_id"
],
"properties": {
"limit": {
"type": "number",
"default": 25,
"maximum": 100,
"minimum": 1
},
"cursor": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"campaign_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_email_campaign_run
Get one email campaign run with clicked URLs.
get_email_campaign_run input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"campaign_id",
"run_id"
],
"properties": {
"run_id": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"campaign_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_email_categories
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.
list_email_categories input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}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.
update_email_categories input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"categories"
],
"properties": {
"categories": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"label",
"unsubscribable"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,30}$",
"description": "Stable slug; used on suppressions, broadcasts, and send_email nodes"
},
"label": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"description": {
"type": "string",
"maxLength": 200
},
"unsubscribable": {
"type": "boolean",
"description": "false for transactional-style categories that always send"
}
}
},
"maxItems": 20,
"minItems": 1
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_email_images
List images in a project’s email image library, newest first. Use these for lifecycle/workflow email `image` blocks.
list_email_images input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1
},
"cursor": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}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).
upload_email_image input schema
{
"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)"
}
}
}delete_email_image
Delete an image from a project’s email image library. Remove it from any email templates first, or the image block will break.
delete_email_image input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"image_id"
],
"properties": {
"image_id": {
"type": "string",
"description": "The email image ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_broadcasts
List one-off email broadcasts for a project.
list_broadcasts input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1
},
"cursor": {
"type": "string"
},
"status": {
"enum": [
"draft",
"scheduled",
"sending",
"paused",
"sent",
"cancelled",
"failed"
],
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_broadcast
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).
get_broadcast input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}create_broadcast
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.
create_broadcast input schema
{
"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."
}
}
}
]
}
}
}update_broadcast
Update a draft or scheduled broadcast (name, email content, audience, schedule, list-hygiene or tracking options, A/B test).
update_broadcast input schema
{
"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."
}
}
}
]
}
}
}delete_broadcast
Delete a broadcast. Refused while it is actively sending.
delete_broadcast input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}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.
preview_broadcast_audience input schema
{
"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)"
}
}
}get_broadcast_audience_fields
List the fields available for building a broadcast audience (contact/company builtins, sampled metadata keys, valid operators per type).
get_broadcast_audience_fields input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}send_test_broadcast_email
Send a test of a broadcast email to an account user email address only (never to real contacts).
send_test_broadcast_email input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id",
"to_email"
],
"properties": {
"variant": {
"enum": [
"a",
"b"
],
"type": "string",
"description": "A/B test variant to send (default a, the main email)"
},
"to_email": {
"type": "string",
"description": "Recipient email. Must belong to a user on this account."
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"sample_contact_id": {
"type": "string",
"description": "Contact to source sample merge fields from"
}
}
}schedule_broadcast
Schedule a draft (or reschedule a scheduled) broadcast to send at a future time.
schedule_broadcast input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id",
"scheduled_at"
],
"properties": {
"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"
}
}
}send_broadcast_now
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.
send_broadcast_now input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id",
"confirm_recipient_count"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"confirm_recipient_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Must exactly equal the current preview_broadcast_audience count"
}
}
}cancel_broadcast
Cancel a scheduled, in-progress, or paused broadcast. Recipients not yet sent to are marked cancelled.
cancel_broadcast input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_broadcast_recipients
List the per-recipient delivery status for a broadcast.
list_broadcast_recipients input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1
},
"cursor": {
"type": "string"
},
"status": {
"enum": [
"pending",
"held",
"sending",
"sent",
"failed",
"skipped",
"cancelled"
],
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_broadcast_readiness
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_broadcast_readiness input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string"
},
"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.
resume_broadcast input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}select_broadcast_ab_winner
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.
select_broadcast_ab_winner input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"broadcast_id"
],
"properties": {
"variant": {
"enum": [
"a",
"b"
],
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"broadcast_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_email_deliverability
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.
get_email_deliverability input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"days": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Trailing window for the workflow_id/broadcast_id stats; omitted = all time"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"workflow_id": {
"type": "string",
"description": "Campaign/workflow to report on"
},
"broadcast_id": {
"type": "string",
"description": "Broadcast to report on"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}update_email_postal_address
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.
update_email_postal_address input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"postal_address"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"postal_address": {
"anyOf": [
{
"type": "string",
"maxLength": 300
},
{
"type": "null"
}
]
}
}
}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).
reset_email_deliverability_health input schema
{
"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)"
}
}
}get_workflow_builder_reference
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.
get_workflow_builder_reference input schema
{
"type": "object",
"properties": {}
}list_workflows
List visitor workflows for a project (trigger + branching graph automations), ordered by priority.
list_workflows input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"enabled": {
"type": "boolean"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"trigger_type": {
"enum": [
"first_seen",
"first_message",
"page_visit",
"api_trigger",
"email_capture",
"nps_response",
"csat_response"
],
"type": "string"
}
}
}get_workflow
Get a visitor workflow including its full node/edge graph definition.
get_workflow input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workflow_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"workflow_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}validate_workflow
Validate a visitor workflow definition without saving it. Same input as create_workflow.
validate_workflow input schema
{
"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."
}
}
}
]
}
}
}create_workflow
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.
create_workflow input schema
{
"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."
}
}
}
]
}
}
}update_workflow
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.
update_workflow input schema
{
"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."
}
}
}
]
}
}
}delete_workflow
Delete a visitor workflow. Refuses if another workflow in the project still chains into it via trigger_campaign or next_campaign_id.
delete_workflow input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workflow_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"workflow_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}set_workflow_enabled
Enable or disable a visitor workflow.
set_workflow_enabled input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workflow_id",
"enabled"
],
"properties": {
"enabled": {
"type": "boolean"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"workflow_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}reorder_workflows
Reorder visitor workflows by priority; the first id in the list gets the highest priority.
reorder_workflows input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workflow_ids"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"workflow_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
}
}
}list_workflow_executions
List execution history for a visitor workflow.
list_workflow_executions input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workflow_id"
],
"properties": {
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1
},
"cursor": {
"type": "string"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"workflow_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_workflow_execution
Get one visitor workflow execution.
get_workflow_execution input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workflow_id",
"execution_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"workflow_id": {
"type": "string"
},
"execution_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_workflow_email_defaults
Get the project default email design used to seed new send_email nodes.
get_workflow_email_defaults input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}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.
update_workflow_email_defaults input schema
{
"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."
}
}
}
]
}
}
}send_test_workflow_email
Send a real test email for one send_email node in a workflow to an account user email address only.
send_test_workflow_email input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workflow_id",
"to_email"
],
"properties": {
"node_id": {
"type": "string",
"description": "Required if the workflow has more than one send_email node"
},
"to_email": {
"type": "string",
"description": "Recipient email. Must belong to a user on this account."
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"workflow_id": {
"type": "string"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"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"
}
}
}
}
}list_test_email_recipients
List account user emails allowed as workflow/email test recipients.
list_test_email_recipients input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
}track_event
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.
track_event input schema
{
"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"
}
}
}list_automations
List all automations for this project
list_automations input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_automation
Get automation details
get_automation input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"automation_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"automation_id": {
"type": "string",
"description": "The automation ID"
}
}
}create_automation
Create a new automation
create_automation input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name",
"trigger_type",
"messages"
],
"properties": {
"name": {
"type": "string",
"description": "Automation name"
},
"enabled": {
"type": "boolean",
"default": true,
"description": "Whether enabled"
},
"messages": {
"type": "object",
"description": "Messages by locale (e.g. {\"en\": \"Hello!\"})",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"frequency": {
"enum": [
"once_ever",
"once_per_session",
"every_time"
],
"type": "string",
"default": "once_ever",
"description": "How often to fire"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"trigger_type": {
"enum": [
"page_visit",
"first_message",
"api_trigger",
"email_capture"
],
"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": {}
}
}
}update_automation
Update an automation
update_automation input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"automation_id"
],
"properties": {
"name": {
"type": "string",
"description": "New name"
},
"enabled": {
"type": "boolean",
"description": "Enable/disable"
},
"messages": {
"type": "object",
"description": "New messages by locale",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"frequency": {
"enum": [
"once_ever",
"once_per_session",
"every_time"
],
"type": "string",
"description": "New frequency"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"trigger_type": {
"enum": [
"page_visit",
"first_message",
"api_trigger",
"email_capture"
],
"type": "string",
"description": "New trigger type"
},
"automation_id": {
"type": "string",
"description": "The automation ID"
},
"delay_seconds": {
"type": "number",
"description": "New delay"
},
"trigger_config": {
"type": "object",
"description": "New trigger configuration",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
}toggle_automation
Enable or disable an automation
toggle_automation input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"automation_id",
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether to enable or disable"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
},
"automation_id": {
"type": "string",
"description": "The automation ID"
}
}
}list_guides
List all guides for this project
list_guides input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_guide
Get guide details
get_guide input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"guide_id"
],
"properties": {
"guide_id": {
"type": "string",
"description": "The guide ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}create_guide
Create a new guide
create_guide input schema
{
"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."
}
}
}update_guide
Update a guide
update_guide input schema
{
"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."
}
}
}toggle_guide
Enable or disable a guide
toggle_guide input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"guide_id",
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether to enable or disable"
},
"guide_id": {
"type": "string",
"description": "The guide ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}delete_guide
Permanently delete a guide and its execution history
delete_guide input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"guide_id"
],
"properties": {
"guide_id": {
"type": "string",
"description": "The guide ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_guide_stats
Per-guide analytics: triggers, completions, completion rate, per-step drop-off, selector misses
get_guide_stats input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"guide_id"
],
"properties": {
"guide_id": {
"type": "string",
"description": "The guide ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"since_days": {
"type": "number",
"description": "Count only executions from the last N days. Omit for all time."
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_guide_health
Which guides had steps fail to anchor recently — the signal that a selector rotted in the target app
get_guide_health input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"since_days": {
"type": "number",
"default": 7,
"description": "Look at misses from the last N days. Default: 7."
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}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_guide input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"guide_id"
],
"properties": {
"guide_id": {
"type": "string",
"description": "The guide ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}tag_message
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.
tag_message input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"message_id",
"tags"
],
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags to add to the message"
},
"message_id": {
"type": "string",
"description": "The message ID to tag"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}untag_message
Remove specific tags from a message
untag_message input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"message_id",
"tags"
],
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags to remove"
},
"message_id": {
"type": "string",
"description": "The message ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_message_tags
List all tags defined for this project
list_message_tags input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_message_tags_stats
Get all project tags with their usage counts
get_message_tags_stats input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_teams
List all teams for this project with member and conversation counts
list_teams input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_team
Get a team with its members
get_team input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"team_id"
],
"properties": {
"team_id": {
"type": "string",
"description": "The team ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_macros
List shared macros (available to all team members)
list_macros input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_macro
Get a single shared macro by ID
get_macro input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"macro_id"
],
"properties": {
"macro_id": {
"type": "string",
"description": "The macro ID"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}list_webhooks
List all webhooks for this project
list_webhooks input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}create_webhook
Create a new webhook
create_webhook input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"url",
"events"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "The webhook URL to receive events"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event types to subscribe to (e.g. conversation.created, message.created)"
},
"secret": {
"type": "string",
"description": "Optional HMAC secret for signature verification"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}update_webhook
Update an existing webhook
update_webhook input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"webhook_id"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "New webhook URL"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "New event types"
},
"secret": {
"type": [
"string",
"null"
],
"description": "New secret (null to remove)"
},
"enabled": {
"type": "boolean",
"description": "Enable or disable the webhook"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"webhook_id": {
"type": "string",
"description": "The webhook ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}delete_webhook
Delete a webhook
delete_webhook input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"webhook_id"
],
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"webhook_id": {
"type": "string",
"description": "The webhook ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_statistics
Get project statistics including responsiveness, conversation volume, and per-agent metrics. Defaults to last 30 days.
get_statistics input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"end_date": {
"type": "string",
"description": "End date (ISO 8601, e.g. 2025-01-31)"
},
"project_id": {
"type": "string",
"description": "Target project ID"
},
"start_date": {
"type": "string",
"description": "Start date (ISO 8601, e.g. 2025-01-01)"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}get_sender_domain
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).
get_sender_domain input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}configure_sender_domain
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.
configure_sender_domain input schema
{
"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\""
}
}
}check_sender_domain
Re-check the project's custom sender domain verification status against Amazon SES.
check_sender_domain input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}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.
update_sender_identity input schema
{
"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. support@yourcompany.com) 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)"
}
}
}remove_sender_domain
Remove the project's custom sender domain. Visitor-facing email reverts to the default Hal address.
remove_sender_domain input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project_id": {
"type": "string",
"description": "Target project ID"
},
"project_slug": {
"type": "string",
"description": "Target project slug (helpdesk slug)"
}
}
}import_conversation
Import a single historical conversation silently (no webhooks, no notifications). Use for migrating data from other chat platforms.
import_conversation input schema
{
"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.
import_conversations input schema
{
"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)"
}
}
}Prompts
Not advertised
Resources
Not advertised
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 929 ms
- 95th percentile latency
- 929 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 929 ms · metadata changed · 134 tool(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http hal-mcp-chatwithhal https://api.chatwithhal.com/mcpCodex
Codex configuration
codex mcp add hal-mcp-chatwithhal --url https://api.chatwithhal.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"hal-mcp-chatwithhal": {
"url": "https://api.chatwithhal.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"hal-mcp-chatwithhal": {
"type": "streamableHttp",
"url": "https://api.chatwithhal.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"hal-mcp-chatwithhal": {
"type": "http",
"url": "https://api.chatwithhal.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http hal-mcp-chatwithhal https://api.chatwithhal.com/mcpClaude Desktop
Claude Desktop configuration
{
"mcpServers": {
"hal-mcp-chatwithhal": {
"url": "https://api.chatwithhal.com/mcp"
}
}
}Windsurf
Windsurf configuration
{
"mcpServers": {
"hal-mcp-chatwithhal": {
"serverUrl": "https://api.chatwithhal.com/mcp"
}
}
}Let your agent find its tools
Find servers like HAL MCP from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.
Other crm, sales, and marketing servers
Do you run HAL MCP?
Prove ownership with a DNS record, a well-known file, or your Official MCP Registry entry, and your edits publish immediately. Proofs are re-checked weekly; admins can still hide or remove a listing.