HAL MCP Server

New to HAL email? Call get_email_capabilities_overview first. Create an email campaign using campaign language instead of workflow graph internals.

New to HAL email? Call get_email_capabilities_overview first. Create a reusable workflow email template.

Delete an email campaign. Refuses if another workflow in the project still chains into it via trigger_campaign or next_campaign_id.

Delete an image from a project’s email image library. Remove it from any email templates first, or the image block will break.

Delete a reusable workflow email template. Existing campaigns keep their embedded copy.

Get email campaign details.

Get one email campaign run with clicked URLs.

Orientation for HAL email features: campaigns vs workflows vs broadcasts, templates vs project defaults vs inline design, sender domains, images, test sending, track_event, and unsubscribe/suppression. Call this before creating any campaign, workflow, broadcast, or template.

Project email reporting. Always returns: health (last 30 days across every campaign, workflow and broadcast: sent, sent_last_24h, delivered, hard bounces (bounced), soft bounces, complaints and their rates, plus the status that blocks broadcasts, and reset_at when a list-cleanup reset restarted the window), sources (the same window broken down per workflow/broadcast with delivered, hard/soft bounces, unique opens, clicks and replies), warm-up progress (only broadcasts count toward it), and the footer postal address. Pass workflow_id or broadcast_id (optionally with days; omitted = all time) to also get stats for that one campaign. Opens and clicks exclude automatic ones from security scanners and Apple Mail Privacy Protection, which are reported as automatic_opens/automatic_clicks. Replies count recipients who answered the email (auto-replies are ignored). Delivered counts only cover emails sent after delivery tracking was enabled.

Get a reusable workflow email template.

Check whether an email address is currently suppressed for lifecycle email campaigns, for a given category (default "all").

List email campaign runs with delivery, open, and click data.

List email campaigns backed by visitor workflows.

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 images in a project’s email image library, newest first. Use these for lifecycle/workflow email `image` blocks.

List email addresses suppressed for lifecycle email campaigns in a project.

List reusable workflow email templates for a project.

Update an email campaign.

Replace the full set of email categories for a project (upserts by key, removes any key not included). Refused with the referencing suppressions/broadcasts/workflows if a key still in use would be removed.

Set the physical mailing address shown in the footer of every marketing/lifecycle email (required by CAN-SPAM). Pass null or an empty string to remove it. Confirm the exact address with the user first.

Update a reusable workflow email template.

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.

Delete a visitor workflow. Refuses if another workflow in the project still chains into it via trigger_campaign or next_campaign_id.

Get a visitor workflow including its full node/edge graph definition.

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 the project default email design used to seed new send_email nodes.

Get one visitor workflow execution.

List execution history for a visitor workflow.

Enable or disable a visitor 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 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.

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.

Delete a broadcast. Refused while it is actively sending.

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).

List the fields available for building a broadcast audience (contact/company builtins, sampled metadata keys, valid operators per type).

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.

List the per-recipient delivery status for a broadcast.

Update a draft or scheduled broadcast (name, email content, audience, schedule, list-hygiene or tracking options, A/B test).

Create a deal for a company. The company's own stage and value follow its primary deal (its newest open new-business deal).

Delete a deal. A company with no deals left drops out of the pipeline.

Get a deal with its company, stage, contacts and stage/amount history

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.

Remove a contact from a deal

Add a contact to a deal, or change their role on it

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.

Create an article with an initial translation

Create a new article group

Get an article with translations

List all article groups

Update article properties or upsert a translation

Update an article group

Create a new guide

Permanently delete a guide and its execution history

Get guide details

Which guides had steps fail to anchor recently — the signal that a selector rotted in the target app

Per-guide analytics: triggers, completions, completion rate, per-step drop-off, selector misses

Update a guide

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 a test of a broadcast email to an account user email address only (never to real contacts).

Send a test email for an existing email campaign to an account user email address only.

Send a workflow email template test to an account user email address only.

Send a real test email for one send_email node in a workflow to an account user email address only.

Re-check the project's custom sender domain verification status against Amazon SES.

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).

Remove the project's custom sender domain. Visitor-facing email reverts to the default Hal address.

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.

Create a new automation

Get automation details

Update an automation

Create a new company

Get a company with contacts, details and its deals. The company stage and deal_value mirror its primary deal.

Update a company

Create a new contact

Get a contact with full details, recent activity and the deals they are on

Update a contact

Get a conversation with its messages and attachment metadata. agents_typing lists teammates drafting a reply right now; if someone is, let them answer instead of replying over them. replied_to_email is set when the conversation started as a reply to a campaign, workflow or broadcast email. Call get_conversation_image with an image attachment ID to inspect its visual content. To incorporate HAL's own evidence-backed AI draft into your final answer, call generate_ai_response_suggestion next.

Get an image attached to a conversation message as MCP image content so the AI client can inspect it. Images over 2 MB are resized and compressed before delivery. Use an attachment ID returned by get_conversation.

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.

Validate an email template and return AI-client-friendly errors.

Validate a guide's start location and step selectors against the live pages the developer is logged into. Results are recorded by the widget's authoring mode (?hal_guide_debug=1 on any page where the widget runs); this tool returns the newest snapshot per page, so a guide that spans pages reports each of them.

Validate a visitor workflow definition without saving it. Same input as create_workflow.

Create a new webhook

Delete a webhook

Update an existing webhook

List companies with optional search and stage filter. Includes companies with no linked contacts. Paginated.

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.

Import a single historical conversation silently (no webhooks, no notifications). Use for migrating data from other chat platforms.

Import multiple historical conversations in batch (max 100). Each conversation is imported independently — one failure does not affect others. Silent: no webhooks, no notifications.

Get all project tags with their usage counts

List all tags defined for this project

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.

Render an email template preview as subject, preheader, HTML, and plain text.

Enable or disable an automation

Enable or disable a guide

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 all automations for this project

List one-off email broadcasts for a project.

Cancel a scheduled, in-progress, or paused broadcast. Recipients not yet sent to are marked cancelled.

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.

List contacts with optional search

List conversations with filters (status, spam, limit, offset). Each result says whether it is marked as spam.

List CRM pipeline stages

List visitor custom properties and sampled metadata keys available for campaign predicates and conditions.

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.

Disable an email campaign.

Enable an email campaign.

List tracked lifecycle event names seen in a project.

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.

List all guides for this project

Link an existing contact to an existing company. The operation is idempotent and both records must belong to the selected project.

Get a single shared macro by ID

List shared macros (available to all team members)

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.

List projects available to this MCP key. Call this first, then get_email_capabilities_overview for email features.

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.

Reorder visitor workflows by priority; the first id in the list gets the highest priority.

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.

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).

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.

Schedule a draft (or reschedule a scheduled) broadcast to send at a future time.

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.

Get project statistics including responsiveness, conversation volume, and per-agent metrics. Defaults to last 30 days.

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.

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.

Get a team with its members

List all teams for this project with member and conversation counts

List account user emails allowed as workflow/email test recipients.

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.

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.

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.

Remove specific tags from a message

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).

List all webhooks for this project

List visitor workflows for a project (trigger + branching graph automations), ordered by priority.