AIエージェント向け

SendHQ MCPサーバー

Give an AI agent full, safe control of one SendHQ workspace: send and receive email, verify domains, publish templates, and investigate deliverability through 142 strictly typed tools. Written for agents first; humans welcome.

142 toolsstdio transport, one command0 key-management tools
インストールと接続(Claude Code)
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

このサーバーについて

The SendHQ MCP server lets an AI agent operate one SendHQ workspace through the Model Context Protocol: send email (single, batch, templated, replies, attachments, idempotent retries), read and search sent and received mail (subjects, bodies, and attachment names) and its delivery events, organize mail into labels with auto-filing rules, manage drafts and private attachments, author and publish hosted templates, add and verify domains and their DNS, set up inbound receiving and inbound addresses, inspect deliverability, bounces, complaints, and suppressions, run newsletters (consented contacts with tags and custom fields, segments, lists with signup forms, welcome emails, and newsletter sites, and broadcasts with pre-send checks, test sends, scheduling, and bot-filtered open and click reports), and read account usage, billing state, analytics, and API-key metadata.

これはsendhq CLIバイナリに組み込まれたローカルのstdioサーバーです。MCPクライアントがsendhq mcpを子プロセスとして起動し、stdin/stdout上でJSON-RPCを使って通信します。各ツール呼び出しは、ワークスペースのAPIキーで認証されたhttps://sendhq.cc/api/v1のSendHQ REST APIへのドキュメント化されたリクエスト1件になります。そのため、MCPサーバーの権限はそのキーの権限とまったく同じで、それを超えることはありません。

  • 142 tools in 10 groups, generated from one catalog that is also published as tools.json.
  • 厳密なJSONスキーマ:不明な引数、誤った型、必須フィールドの欠落は、SendHQに届く前にローカルで拒否されます。
  • 構造化されたエラー:安定したcode、HTTPのstatus、explanation(説明)、具体的なremedy(対処法)、再試行が有効かどうかを含みます。
  • 実際にメールを送信するツールやデータを破棄するツールは、説明文の冒頭でその旨を示し、MCPの安全性アノテーションを持っています。
  • --read-onlyモードでは、送信や変更を行うツールがすべて非表示になります。
  • 何もログに記録されません。stdoutにはプロトコルメッセージのみが流れ、APIキーやメッセージの内容がログに残ることはありません。
ドキュメント用MCPエンドポイントとは別物です。SendHQは、https://sendhq.cc/api/mcpで読み取り専用の小さなドキュメント用MCPエンドポイントもホストしています(料金とドキュメントの参照のみで、アカウントへのアクセスはありません)。このページで説明するサーバーは、アカウント単位の完全なサーバーで、ローカルまたは以下のホスト型コネクタとして動作します。

Use SendHQ in Claude, ChatGPT and Grok

インストールは不要です。SendHQはこのサーバーを、同じツールを備えたホスト型コネクタとしてhttps://mcp.sendhq.cc/mcpでも提供しています。キーを貼り付ける代わりに、SendHQアカウントでログインします。

Claude

  1. Settings → Connectorsを開いてディレクトリからSendHQを探すか、Add custom connectorを選んでhttps://mcp.sendhq.cc/mcpを貼り付けます。
  2. ConnectをクリックしてSendHQにログインし、アクセス内容を確認してAllowをクリックします。
  3. 受信トレイの確認、検証済みドメインからのメール送信、バウンスの説明などをClaudeに依頼できます。

ChatGPT

  1. Open Settings → Security and login and turn on Developer mode.
  2. Go to chatgpt.com/plugins, click Create MCP app, name it SendHQ and enter https://mcp.sendhq.cc/mcp.
  3. Sign in to SendHQ and click Allow, then pick SendHQ from the tools menu in a new chat.

Grok

  1. Go to grok.com/connectors, click New Connector, then Custom.
  2. Enter https://mcp.sendhq.cc/mcp, sign in to SendHQ and click Allow.

Muse by Meta

In Muse, open Connectors and search for SendHQ. Click Connect, sign in to SendHQ and click Allow.

承認と接続解除

  • The request_feature tool sends a feature request to the SendHQ team with your account details, so we can follow up by email.
  • 実際にメールを送信するツールやデータを削除するツールには、その旨のラベルが付いています。アシスタントが事前に確認を求めるかどうかは、アシスタント側でツールごとに設定します。Claudeでは、Settings → Connectors → SendHQでそれらのツールにNeeds approvalを選択してください。
  • コネクタには、アシスタントの名前が付いた専用のAPIキー(例:「Claude (AI connector)」)が発行されます。APIキーでこれを削除すると、即座に接続が解除されます。
  • APIキーの作成や失効、請求の変更はできません。添付ファイルはbase64で送受信され、ローカルファイルへのアクセスはありません。
  • Sending requires an active subscription. There is no free allowance, including mail to the account owner.

お問い合わせ:postmaster@sendhq.cc。プライバシー:sendhq.cc/privacy。

インストール

sendhqバイナリをインストールします(Linux、macOS、Windows、x86-64およびarm64に対応)。インストーラーはリリースのチェックサムを検証し、デフォルトではバイナリを~/.local/binに配置します。

macOSとLinux
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
Windows PowerShell
irm https://downloads.sendhq.cc/install.ps1 | iex
インストールを確認する
sendhq version
SENDHQ_API_KEY=re_your_key sendhq doctor

ダッシュボードのhttps://sendhq.cc/app#/keysでAPIキーを作成します。MCPサーバーはキーを作成できません。サーバーを起動するコマンドは次の1つだけです。

stdioサーバーを起動する
SENDHQ_API_KEY=re_your_key sendhq mcp

通常、これを手動で実行することはありません。MCPクライアントが起動します。ターミナルで実行すると、stdinでJSON-RPCを待ち受けます。

クライアントを設定する

Claude Code

claude mcp add
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

# read-only variant
claude mcp add sendhq-readonly --env SENDHQ_API_KEY=re_your_key -- sendhq mcp --read-only

--scope userを追加するとすべてのプロジェクトで使えるようになり、--scope projectを追加するとプロジェクトの.mcp.jsonに書き込まれます。共有する.mcp.jsonでは、キーをコミットせずに環境変数から参照してください。Claude Codeは.mcp.json内の${VAR}を展開します。

.mcp.json
{
  "mcpServers": {
    "sendhq": {
      "command": "sendhq",
      "args": [
        "mcp"
      ],
      "env": {
        "SENDHQ_API_KEY": "${SENDHQ_API_KEY}"
      }
    }
  }
}

OpenAI Codex

~/.codex/config.toml
[mcp_servers.sendhq]
command = "sendhq"
args = ["mcp"]
env = { SENDHQ_API_KEY = "re_your_key" }

コマンドラインからも設定できます:codex mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp。

Claude Desktop

claude_desktop_config.json(macOS:~/Library/Application Support/Claude/、Windows:%APPDATA%\Claude\)を編集し、アプリを再起動します。デスクトップアプリはシェルのPATHを引き継がないため、バイナリの絶対パス(which sendhq)を使ってください。

claude_desktop_config.json
{
  "mcpServers": {
    "sendhq": {
      "command": "/Users/you/.local/bin/sendhq",
      "args": [
        "mcp"
      ],
      "env": {
        "SENDHQ_API_KEY": "re_your_key"
      }
    }
  }
}

その他のMCPクライアント

コマンドsendhq、引数["mcp"](必要に応じて"--read-only")、および以下の環境変数を指定してstdioサーバーを設定します。サーバーはMCPプロトコルバージョン2024-11-05、2025-03-26、2025-06-18、2025-11-25に対応し、initialize、ping、tools/list、tools/callを実装しています。ツールの結果には、JSONテキストブロックとstructuredContentの両方が含まれます。

stdioの簡易動作確認(sendhq mcpにパイプする)
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_service_health","arguments":{}}}

アカウント単位のサーバーには、ホスト型のHTTPトランスポートはありません。書き込み可能なリモートMCPエンドポイントにはユーザーごとのOAuthが必要ですが、SendHQはこれを提供していません。ローカルのバイナリなら、キーをすでに保持しているマシン上に留めておけます。

環境変数とフラグ

変数またはフラグ必須意味
SENDHQ_API_KEYはいワークスペースのAPIキー(re_…)。get_service_health以外のすべてのツールで必要です。キーがなくてもサーバーは起動しますが、すべての呼び出しで修正方法を説明する構造化されたauth_errorが返されます。
SENDHQ_API_BASE_URLいいえAPIのベースURL。デフォルトはhttps://sendhq.cc/api/v1です。ローカル環境やステージング環境でのみ使用してください。旧エイリアスとしてSENDHQ_BASE_URLも使用できます。
SENDHQ_MCP_READ_ONLYいいえ1、true、yesを指定すると--read-onlyと同じ動作になります。
--read-onlyいいえメールの送信も状態の変更も行わないツールのみを公開します。非表示のツールは、名前を指定して呼び出されても拒否されます。
SENDHQ_PROFILE / --profileいいえSENDHQ_API_KEYの代わりに、sendhq auth loginでOSのキーリングに保存したキーを使います。両方が存在する場合は環境変数が優先されます。

キーは、設定されたベースURLにAuthorization: Bearerヘッダーとしてのみ送信されます。出力、ログへの記録、エラーでの表示、ツールの結果への含有は一切ありません。

エージェント向けの安全モデル

  • Sends real email. send_email, send_batch, send_template_test, send_broadcast, send_broadcast_test, schedule_broadcast (at the scheduled time), and send_broadcast_to_more deliver mail to real people and consume delivery credits. Their descriptions start with SENDS REAL EMAIL. Call them only when the user explicitly asked for that specific message to be sent, with the recipients, sender, and content confirmed.
  • Destructive. delete_email, delete_draft, delete_attachment, delete_domain, delete_inbox, remove_suppression, the campaign deletes (delete_contact, delete_list, remove_list_contact, delete_broadcast, cancel_broadcast, delete_segment, delete_contact_field), and bulk_update_contacts are marked destructiveHint: true and their descriptions start with DESTRUCTIVE. Confirm with the user first. remove_suppression weakens a safety block and is appropriate only when a human confirms the address works again.
  • 状態を変更します。下書き、テンプレート、ドメイン、インボックスの作成や更新、テンプレートの公開、検証の開始はワークスペースを変更しますが、メールは送信しません。
  • 読み取り専用。それ以外はすべてreadOnlyHint: trueで、自由に呼び出しても安全です。
  • このサーバーがDNSを変更することはありません。add_domainは人間が公開するためのレコードを返します。get_domain_connect_linkは、ユーザー本人が開いてDNSプロバイダー上で承認する必要がある同意URLを返します。
  • このサーバーが請求を変更することはありません。get_accountはプラン、使用量、サブスクリプションの状態を読み取るだけです。
  • Sending requires an active subscription. There is no free allowance. Every send, including a test and a send to the account owner's own address, returns subscription_required (402) until a plan is active. Lapsed, cancelled, and past-due subscriptions are refused the same way. The owner chooses a plan in the dashboard (Profile & Billing) or at https://sendhq.cc/pricing. Unpaid workspaces can still verify domains, create keys, and read the workspace.
  • Accepted is not delivered. A successful send returns an ID; delivery, bounce, and complaint evidence arrives later in list_email_events. Never claim inbox placement or that a person read a message. Broadcast opens are estimates: privacy proxies and security scanners load images on their own, and requests that look automated are counted apart (machine in get_broadcast_report).
  • 423の一時停止を回避するために別のFromアドレスに切り替えないでください。また、配信停止した受信者や苦情を報告した受信者を再び追加してはいけません。

APIキーは対象外

設計上、APIキーを作成、変更、ローテーション、失効、削除するツールはありません。エージェントが認証情報を発行したり破棄したりしてはいけません。list_api_keysが返すのは、名前、秘密でないプレフィックス、最終使用日時のみです。キーの管理は、ログインした人間がダッシュボードで行います。

ワークフロー

1. 最初の送信

  1. get_service_healthでAPIに到達できることを確認します(キーなしで動作します)。
  2. get_account shows the plan (access.tier) and remaining quota. If there is no active plan, do not send: the call returns subscription_required.
  3. list_sending_identitiesで使用できるFromアドレスを一覧表示します。空の場合は、先にドメインのワークフローを実行してください。
  4. 送信者、受信者、件名、本文をユーザーに確認してから、idempotency_keyを付けてsend_emailを呼び出します。
  5. 返されたidを指定してlist_email_eventsを呼び出すと、プロバイダーが報告した時点で(通常は数秒から数分)delivery、bounce、complaint、rejectが表示されます。
最初の送信
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "SendHQ is connected",
    "text": "It works.",
    "idempotency_key": "first-send-2026-09-26"
  }
}

2. ドメイン検証の一連の流れ

  1. add_domain with name: "example.com". The result includes the DNS records (DKIM CNAMEs, domain verification, SPF, recommended DMARC).
  2. domain_idを指定してget_dns_providerを呼び出すと、権威DNSプロバイダーが検出され、そのプロバイダーで各レコードに入力すべき正確な相対ホストが返されます。
  3. If providers.domainConnect.available is true, get_domain_connect_link returns a consent URL. Give it to the human; nothing changes until they approve at the provider. Otherwise, give the human the records to publish. Never publish a second SPF record: merge SendHQ's SPF include (include:amazonses.com) into the existing v=spf1 value.
  4. verify_domain rechecks DNS and DKIM verification. Status moves through pending, checking, and propagating to verified. Poll verify_domain or get_domain every 30–60 seconds; DNS can take minutes to hours.
  5. statusがverifiedになると、そのドメインのアドレスがlist_sending_identitiesに表示されます。

3. バウンス、苦情、サプレッション

  1. list_blocked_recipientsは、ブロックされたすべてのアドレスをその理由(bounce、complaint、unsubscribe)と件数のサマリーとともに返します。
  2. list_suppressionsはハードバウンスと苦情によるサプレッションを返します。deliverability_statsは過去30日間の配信率、バウンス率、苦情率を返します。list_sender_reputationは、どのFromアドレスがスロットリングまたは一時停止されているかを示します。
  3. サプレッション対象の受信者を含む送信は422 recipient_suppressedで失敗します。その受信者を除外して再送してください。
  4. バウンスしたメールボックスが現在は使えることを人間が確認した場合にのみ、remove_suppressionを呼び出してください。苦情によるサプレッションは恒久的です(409 complaint_suppression_locked)。

4. メールを受信する

  1. ドメイン(多くの場合inbound.example.comのようなサブドメイン)が検証済みである必要があります。
  2. setup_inboundは受信を準備し、MXレコードを1つ返します。これを人間が公開します。
  3. statusがreadyになるまでverify_inboundを呼び出します。
  4. domain_idとlocal_part(例:support)を指定してcreate_inboxを呼び出すと、support@inbound.example.comが作成されます。
  5. direction: "in"とunread: true(必要に応じてinbox_idも)を指定してlist_emailsをポーリングします。メッセージはget_emailで、その会話はget_threadで、添付ファイルはdownload_attachmentで読み取り、mark_email(read: true)で処理済みにします。
  6. send_emailとreply_to_email_idでスレッド内に返信します。SendHQがIn-Reply-To、References、スレッドを設定します。

5. Webhookとイベント通知

Webhooks push signed events to an endpoint a human configures in the dashboard or with the REST API (see /docs/webhooks): email events (email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.failed, email.received), contact.unsubscribed when a recipient unsubscribes from a marketing or automation email, and, for automations, automation.entered, automation.converted, and automation.exited. There is no webhook tool, because endpoint responses carry signing secrets. An agent without a webhook polls instead: list_email_events for one message's outcome, list_emails with status (for example bounced) or after for recent changes, list_emails with direction: "in" and unread: true for new inbound mail, and list_blocked_recipients for new suppressions. Poll no more than about once a minute per question.

6. 配信失敗を診断する

  1. メッセージを探します。direction: "out"とtoまたはqueryを指定してlist_emailsを呼び出すか、IDがわかっている場合はget_emailを使います。status: failedは、SendHQまたはプロバイダーが送信時に拒否したことを意味します。メールのエラーにその理由が記載されています。
  2. list_email_events:bounce(恒久的または一時的、プロバイダーの診断情報付き)、complaint、reject、delivery。イベントがまだない場合は、プロバイダーがまだ報告していないということです。しばらく待ってから再確認してください。
  3. If the send call itself failed, read the error code: subscription_required → the owner activates a plan; sender_domain_unverified → finish domain verification; recipient_suppressed → the address hard-bounced or complained before; sender_paused → inspect list_sender_reputation; account_paused → the workspace is paused for review, read the rates; daily_limit_reached → wait until midnight UTC; quota_exhausted → get_account usage.
  4. get_domainでDKIM、SPF、DMARCが引き続き公開されていることを確認します。deliverability_statsで、問題が1通のメッセージだけか、傾向なのかがわかります。
  5. 証拠が示す内容を報告してください。deliveryイベントは受信者側のサーバーがメッセージを受け付けたことを意味し、受信トレイに届いたことや読まれたことを意味するわけではありません。

7. タスク用バケットを管理する(ラベル)

  1. name(例:Agent/Orders)とskip_inbox: trueを指定してcreate_labelを呼び出します。これでラベルがバケットになります。このラベルが付いた受信メールはアーカイブされ、人間の受信トレイには表示されずラベル内にのみ表示されます。
  2. send_email(またはsend_batch)とlabels: ["Agent/Orders"]でタスク用のメールを送信します。その会話への返信は自動的にラベルを引き継ぎ、受信トレイをスキップします。
  3. 自分の会話以外から始まるメールには、振り分けルールを追加します。inbox_id(orders@…のような専用アドレス)、from、to、subjectのいずれかを指定してcreate_label_ruleを呼び出します。受信済みのメールも振り分けるにはapply_to_existing: trueを渡します。
  4. バケットを処理します。label: "Agent/Orders"、direction: "in"、unread: trueを指定してlist_emailsを呼び出し、get_emailまたはget_threadで読み、send_emailとreply_to_email_idで返信し、処理したらmark_emailでread: trueにします。
  5. 紛れ込んだメッセージの出し入れにはlabel_email(add / remove)を使います。受信メッセージにバケットのラベルを追加すると、そのメッセージはアーカイブもされます。
  6. 必要に応じてset_inbox_forwardingを使うと、受信アドレスに届いたすべてのメールのコピーを別のメールボックスに送信できます(転送先は先にメールで確認を行います)。
バケットに送信する
{
  "name": "send_email",
  "arguments": {
    "from": "Orders <orders@example.com>",
    "to": [
      "customer@example.net"
    ],
    "subject": "Order 1042: confirm delivery window",
    "text": "Reply with a time that works.",
    "labels": [
      "Agent/Orders"
    ],
    "idempotency_key": "order-1042-window"
  }
}

8. 添付ファイルとテンプレート

有料プランでは、send_emailのattachmentsで最大10個のファイルを添付できます(それぞれcontent_base64またはローカルのfile_pathが必要です。filenameのデフォルトはファイルのベース名です)。ホスト型テンプレートの場合:create_template → update_template_draft → render_templateでサンプルデータを使ってプレビュー → send_template_test(実際のテストを1通送信) → publish_templateの順に進め、その後template: {key, data}とちょうど1人のto受信者を指定してsend_emailまたはsend_batchで送信します。

9. Send a newsletter

  1. Audience: list_lists (or create_list with a signup form), and optionally preview_segment then create_segment to narrow it, for example to contacts tagged VIP who opened in the last 90 days. Add only people who asked for your email: every subscribed contact needs a consent_basis.
  2. get_newsletter_settings: if postalAddress is empty, ask the user for one and set it with update_newsletter_settings (marketing email needs it).
  3. create_broadcast with list_id, a verified from, subject, preview_text, content (markdown is simplest), and optionally audience (segment_id, limit, order: engaged).
  4. check_broadcast: fix every block item and tell the user about warn items. Then send_broadcast_test to the user's own address so they can look at it.
  5. Only when the user says to send: send_broadcast now (with an idempotency_key), or schedule_broadcast with scheduled_at (unschedule_broadcast to change it).
  6. Follow up with get_broadcast (delivery totals), get_broadcast_report (opens, clicks, links, inbox providers, against your average), and list_broadcast_recipients with activity. Report opens as estimates. With a limited audience, send_broadcast_to_more sends to the next people.
Draft a broadcast
{
  "name": "create_broadcast",
  "arguments": {
    "list_id": "lst_…",
    "from": "Acme <news@example.com>",
    "subject": "What shipped in October",
    "preview_text": "Three new features",
    "markdown": "Hi {{first_name | there}},\n\nHere is what shipped this month.",
    "audience": {
      "segment_id": "seg_…"
    }
  }
}

10. Run an automation

An automation is a timed sequence of emails that starts when a contact does something and stops when they convert. Automations are being enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled from every tool below.

  1. create_automation with a key, the entry event, exit_rules (the goal_event that counts as converting, or no_goal: true), a verified from_address, and steps, each due offset_seconds after the person entered. It starts as a draft and sends nothing. Every automation carries domain, the domain of its from_address; in a workspace that sends from several domains, list_automations and get_automations_overview take domain to show the automations of one of them.
  2. To let the user read it first: send_automation_test_email sends one email, and send_automation_test every email in order, to the account's own address only (never to a contact), with stand-in values for the merge tags. A test enrols nobody, is in no report, and works while the automation is still a draft. Both send real email, so only when the user asks. send_automation_test_email with dry_run: true returns the rendered email without sending anything.
  3. get_sending_limits shows how much automation email one person may get across every automation, and during which hours. Change them with update_sending_limits only when the user asks.
  4. To start from a ready-made email instead of writing one: list_automation_templates is the template library (welcome, onboarding tips, a nudge to finish setup, trial ending and trial ended, abandoned checkout, failed payment or dunning, receipt, upgrade at a usage limit, feature announcement, review request, feedback score, cancellation survey, and winback for retention), get_automation_template shows one with the email as this workspace would send it, and use_automation_template makes the draft automation with the emails, the suggested entry event and the suggested goal. Some templates come as a set that makes one automation: three onboarding tips, trial ending then trial ended, payment failed then a last notice. set_automation_step with template loads one template into an email of an automation that already exists.
  5. An email can also be built in the dashboard's drag-and-drop builder. get_automation shows such an email with editor design: its content is the builder's project, which only the builder writes, and its html is what is sent. Leave the project alone. To change the wording of a designed email, ask the user to open it in the dashboard; to replace it, send your own html with editor html.
  6. A template is finished except for what only the user knows, written as placeholders in square brackets: [First step], or [Link to plans] as a link's address. to_fill on the automation lists each one by email, and each workspace name the emails print that is blank. Ask the user for the real words and links, write them in with set_automation_step, and set product_name and sender_name with update_sending_limits. Never invent them. set_automation_status refuses to turn the automation on while anything is left (422 automation_not_ready, with a problems list that names each email and detail); test emails are allowed, so the user can read it first.
  7. Only when the user says to start: set_automation_status with status: "on".
  8. Record what people do with track_event (a new contact needs contact.consent_basis). The entry event starts the sequence, the goal event ends it as converted, and a dedupe_key makes a retry harmless. enroll_contact and exit_contact add or remove one person by hand.
  9. preview_automation shows, for everyone in the automation now, which email would go out if they were evaluated at this moment, or why not: nothing due until a time, held by a limit or the sending hours until a time, waiting behind a higher-priority automation, or skipped. It sends nothing and changes nothing.
  10. list_automations gives each automation's 30-day totals. An email that a limit holds back is not dropped: it goes out when the limit allows. When several emails of one automation are due at once, only the latest is sent.
  11. Results: get_automations_overview (every automation) and get_automation_report (one automation, with a row per email) give totals and a number for each day of a date range: people who entered, emails sent, delivered, opened, clicked, and converted. list_automation_people lists who did what (did: entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, or waiting), and get_automation_person gives one contact's history with every open and click. Automation emails are tracked like broadcasts: report opens and clicks as estimates, and note that automated requests are labelled machine and never counted.
Start from a template
{
  "name": "use_automation_template",
  "arguments": {
    "template_id": "payment-failed-notices",
    "from_name": "Dana from Acme",
    "from_address": "dana@example.com"
  }
}
Dry run
{
  "name": "preview_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Who clicked the first email
{
  "name": "list_automation_people",
  "arguments": {
    "automation_key": "checkout-recovery",
    "did": "clicked",
    "step": 1
  }
}

11. See what came in, and connect another system

Events reach SendHQ three ways: track_event from the workspace's own code, a connection (a secret address a payment provider or another system posts its webhooks to), and a spreadsheet uploaded in the dashboard. See /docs/events.

  1. list_events is the feed of everything recorded, newest first: who, what they did (also as plain words), when, where it came from, and which automations it started, ended, or converted. Filter by contact, by name, or by date. list_event_names lists the kinds of event seen in the last 30 days.
  2. list_connections shows each connection with its last delivery in plain words, and get_connection its last 50 deliveries: "Recorded 2 events", "Skipped: no email address", "Refused: bad signature". Start there when something a provider sent did not show up.
  3. Only when the user asks to connect a system: create_connection with kind stripe or dodo (mapped for you) or generic with a mapping. It returns the secret address once; give it to the user to paste into that system. From then on what arrives is recorded without anyone looking, and can start automations that send email.
  4. update_connection with enabled: false pauses a connection (its address answers 404); delete_connection removes it. The provider's signing secret and a replacement address are set by a person in the dashboard.
What one person did
{
  "name": "list_events",
  "arguments": {
    "contact": "ada@example.net"
  }
}

12. Check an email's content before it is sent

score_email reads a subject, the HTML and the plain text as they were written and returns a score from 0 to 100 with what to change, most points first. A plain email with no links and no images scores 100; a designed layout, links to another site than the sender's, link shorteners, images with few words, hidden text, capitals and very long HTML each take points off. Pass from so links can be compared with the sender's own domain. Nothing is stored or sent, and the footer and tracking SendHQ adds are not scored. The dashboard's email editor shows the same number for the same content. It looks at content only, so use it as a checklist: sender reputation, authentication and how recipients react decide more of where mail lands.

Score a draft
{
  "name": "score_email",
  "arguments": {
    "from": "hello@example.com",
    "subject": "Your cart is still here",
    "html": "<p>Pick up where you left off.</p><p><a href=\"https://bit.ly/3xyz\">Finish checkout</a></p>"
  }
}

結果、ページネーション、エラー

呼び出しが成功すると、APIのJSONオブジェクトがstructuredContentとJSONテキストブロックとして返されます。すべてのlist_*ツールはlimit(1〜200、デフォルト50)とoffsetを受け付け、paginationオブジェクトを付加します。has_moreがtrueの間は、offset: pagination.next_offsetを指定して呼び出しを続けてください。

ページネーションされた結果
{
  "data": [
    "…"
  ],
  "count": 50,
  "pagination": {
    "offset": 0,
    "limit": 50,
    "returned": 50,
    "total": 180,
    "has_more": true,
    "next_offset": 50
  }
}

呼び出しが失敗すると、構造化されたエラーとともにisError: trueが返されます。むやみに再試行せず、remedyに従ってください。再試行するのはretryableがtrueの場合だけにしてください。

構造化されたツールエラー
{
  "error": {
    "code": "subscription_required",
    "status": 402,
    "message": "Sending requires an active SendHQ subscription. Choose a plan to start sending.",
    "retryable": false,
    "explanation": "This workspace has no active paid subscription. SendHQ does not send any email, including to the account owner, until a plan is active.",
    "remedy": "Ask the account owner to choose a plan at https://sendhq.cc/pricing or in the dashboard (Profile & Billing). Do not retry until the subscription is active."
  }
}

任意のエラーフィールド:request_id(サポートへの問い合わせ時に伝えてください)、retry_after_seconds、problems(invalid_argumentsの場合のスキーマ違反のリスト)、idempotent_replayed(「冪等性」を参照)。

冪等性

send_emailとsend_batchはidempotency_key(最大200文字)を受け付け、Idempotency-Keyヘッダーとして送信します。論理的なメッセージごとに一定のキーを1つ生成してください(例:invoice-4812-receipt)。

  • 再試行では、同じキーと同一のリクエストボディの両方を再利用する必要があります。同じキーで何かを変更すると(受信者、件名、本文、ヘッダー、テンプレートデータ、さらには引数の値でも)、409 idempotency_conflictが返されます。
  • 同じキー、同じボディで、元のリクエストが完了している場合:SendHQは再送せずに保存済みの結果を返します。これが、タイムアウトやnetwork_errorの後に安全に再試行する方法です。
  • 元のリクエストがまだ実行中に同じキーを使った場合:409 idempotency_in_progressが返されます。少し待ってから再試行できます。
  • 新しい論理的なメッセージには新しいキーが必要です。
  • 保存された失敗も再生されます。最初の試行が失敗した場合、同じキーで再試行すると、同じ失敗がidempotent_replayed: trueとretryable: false付きで返されます。list_emails(direction: out)で何も送信されていないことを確認し、原因を修正してから、新しいキーで送信してください。
  • サーバーがPOSTを自動で再試行することはありません。自動的に再試行されるのは読み取り専用のGET呼び出しだけです(ネットワークエラー、429、5xxの場合に最大3回)。
  • インラインのattachmentsを指定したsend_emailは複数のリクエストを実行するため、idempotency_keyを受け付けません。再試行しても安全な添付ファイル付きの送信には、create_draft → upload_attachment → draft_idとidempotency_keyを指定したsend_emailの順に使ってください。
再試行しても安全な送信(タイムアウト時はまったく同じ内容で繰り返す)
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <billing@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "Receipt #4812",
    "text": "Thanks for your payment.",
    "idempotency_key": "receipt-4812"
  }
}

レート制限とクォータ

SendHQは、APIについて1秒あたりのリクエスト数の固定上限を公表していません。エージェントが実際に直面する制限は使用量の上限で、429として返されます。

  • プランごとの月間受信者配信数。To、Cc、Bccの各アドレスがそれぞれ1配信としてカウントされます。get_account → usage.recipientDeliveriesとusage.emailQuotaMonthを比較してください。
  • Fromアドレスごとの1日あたりの受信者数。その送信者のレピュテーションの状態によって決まります(list_sender_reputation → dailyLimit、有料プランのデフォルトは2,000)。
  • Subscription: sending is refused with subscription_required until a paid plan is active. There is no free or trial allowance.
  • Workspace daily ladder on paid plans: 1,000 recipients on day one, then 2,000, 3,000, 5,000, 8,000, 12,000, 18,000, 25,000, 35,000, 45,000, and 50,000. A step is gained after a UTC day that used at least half the cap with healthy 7-day feedback. A high rate demotes once per incident, not every day the rate stays high. See get_account → sendingLimit. Over the cap: daily_limit_reached, not queued, retry after resets_at (midnight UTC), not on a short backoff.
  • Hourly pace: about one tenth of the day's cap each UTC hour (100 on day one). hourly_limit_reached waits until the next UTC hour.
  • New domains: a sending domain less than 30 days old may send at most 500 Gmail recipients a day (gmail_recipient_limit), on any ladder rung. gmail_rate_limited means Gmail returned 4.7.28; wait until resets_at and keep sending to other providers.
  • 添付ファイル:1メッセージあたり最大10ファイル、10 MBまで。有料プランでは、受信者数で重み付けした添付ファイルの転送量が月10 GBまで。
  • リクエストごと:To + Cc + Bccで最大100アドレス。send_batchは最大100メッセージ。
  • レピュテーションのサーキットブレーカー:直近7日間のローリングウィンドウで、バウンスや苦情がしきい値を超えると、該当するFromアドレスがスロットリングまたは一時停止されます(423 sender_paused)。率が下がれば自動的に回復します。

quota_exhaustedは、期間がリセットされるかプランが変更されるまで再試行できません。rate_limitedはretry_after_secondsの経過後に再試行できます。送信の場合は、同じidempotency_keyと同一のボディで再試行してください。

エラー一覧

codeは安定しています。messageではなく、こちらで分岐してください。

codeHTTP再試行意味と対処法
invalid_arguments—いいえ引数がツールのJSONスキーマのローカル検証に失敗しました。SendHQには何も届いていません。problemsに記載されたフィールドを修正してください。
auth_error401いいえAPIキーがない、失効している、または誤っています。サーバープロセスにSENDHQ_API_KEYを設定してください。キーは人間がダッシュボードで作成します。
subscription_required402いいえNo active subscription. Nothing is sent, including to the account owner. The owner chooses a plan. Do not retry until then.
payment_required402いいえこの機能(添付ファイルなど)には有料プランが必要です。その機能を使わずに送信するか、アップグレードしてください。
sender_domain_not_owned403いいえFromのドメインがこのワークスペースにありません。list_sending_identitiesまたはadd_domainを使ってください。
sender_domain_unverified403いいえFromのドメインがまだ検証されていません。get_domainで確認し、不足しているレコードを公開して、verify_domainを実行してください。
domain_limit_reached403いいえプランのドメイン数の上限に達しました。使っていないドメインを(承認を得て)削除するか、アップグレードしてください。
marketing_not_enabled403いいえこのドメインまたはプランではマーケティングクラスが有効になっていません。メッセージが本当にトランザクションメールである場合にのみtransactionalを使ってください。
forbidden403いいえポリシーによりこの操作は許可されていません。リクエストを調整してください。
not_found404いいえIDがこのワークスペースにありません。リソースを一覧表示して正しいIDを確認してください。アーカイブ済みのテンプレートは先に復元してください。
idempotency_conflict409いいえキーが異なるボディで再利用されました。元のリクエストをまったく同じ内容で再送するか、新しいメッセージには新しいキーを使ってください。
idempotency_in_progress409はい元のリクエストがまだ実行中です。待ってから、同じキーとボディで再試行してください。
revision_conflict409いいえ読み取った後にテンプレートの下書きが変更されました。get_templateで取得し、変更をマージして、再度保存してください。
complaint_suppression_locked409いいえ受信者が苦情を報告しています。今後そのアドレスには絶対にメールを送らないでください。
inbound_not_ready409いいえメール受信の準備ができていません。setup_inboundを実行し、MXを公開して、verify_inboundを実行してください。
conflict409いいえリソースがすでに存在するか、状態が正しくありません。リソースを読み取って調整してください。
attachments_too_large413いいえ10ファイルまたは10 MBを超えています。添付ファイルを削除するか小さくしてください。
recipient_suppressed422いいえ受信者が以前にハードバウンスしたか苦情を報告しています。その受信者を除外してください。list_blocked_recipientsを参照してください。
recipient_unsubscribed422いいえ受信者がマーケティングメールの配信を停止しています。その受信者を恒久的に除外してください。
validation_failed422いいえ内容が拒否されました(変数の仕様に違反するテンプレートデータなど)。入力を修正してください。
sender_paused423いいえこのFromアドレスは、7日間のバウンス・苦情のサーキットブレーカーによって一時停止されています。送信を停止し、リストを修正して、自動回復を待ってください。
account_paused423いいえWorkspace paused for a deliverability review. The body has the measured rate and the limit when the pause was for bounces or complaints. Do not send until it is restored.
quota_exhausted429いいえMonthly allowance, per-sender daily limit, or attachment transfer. Not the workspace daily ladder. Check get_account; wait for that limit to reset or upgrade.
daily_limit_reached429after resetWorkspace daily ladder. Not a short backoff. Wait until resets_at (midnight UTC). The message was not queued.
hourly_limit_reached429after resetHourly pace (about a tenth of the day's cap). Wait until the next UTC hour. Not a short backoff.
gmail_recipient_limit429after reset500 Gmail recipients a day for a sending domain under 30 days old, on any ladder rung. Wait until midnight UTC. Not queued.
gmail_rate_limited429after resetGmail returned 4.7.28 for this domain. Wait until resets_at. Other providers keep sending.
rate_limited429はいSlow down; wait retry_after_seconds. This is not a daily, hourly, or Gmail cap.
server_error5xxはいSendHQまたはプロバイダーの一時的な障害です。間隔を空けて再試行してください。送信の場合は同じキーとボディを使います。idempotent_replayedがtrueの場合は、何も送信されていないことを確認してから新しいキーを使ってください。
network_error—はいリクエストまたはレスポンスが失われました。再試行してください。送信の場合は、同じidempotency_keyを使えば安全に再試行できます。
invalid_request400いいえリクエストの形式が不正です。messageを読んで修正してください。
tool_error—いいえMCPサーバー内部でのローカルな失敗です(読み取れないfile_pathなど)。messageを確認してください。

ツールリファレンス

すべてのツールについて、安全性の分類、呼び出すRESTエンドポイント、パラメータ、戻り値の形式、tools/callのparamsオブジェクトの例を記載しています。パラメータは厳密で、記載されていないものはすべてサーバーに拒否されます。

Emails and threads: send_email, send_batch, list_emails, get_email, mark_email, delete_email, list_email_events, get_thread, email_delivery, thread_delivery
Labels and auto-filing rules: list_labels, get_label, create_label, update_label, delete_label, create_label_rule, delete_label_rule, label_email
Drafts, attachments, and sender identities: list_sending_identities, create_draft, list_drafts, get_draft, update_draft, delete_draft, upload_attachment, download_attachment, delete_attachment
Hosted templates: list_templates, create_template, get_template, update_template_draft, create_template_draft, render_template, send_template_test, publish_template, archive_template, restore_template
Domains and DNS: list_domains, get_domain, add_domain, verify_domain, delete_domain, get_dns_provider, get_domain_connect_link
Inbound email: setup_inbound, verify_inbound, list_inboxes, get_inbox, create_inbox, update_inbox, set_inbox_forwarding, delete_inbox
Deliverability, bounces, and suppressions: deliverability_stats, deliverability_account, deliverability_domains, deliverability_senders, score_email, list_sender_reputation, list_suppressions, remove_suppression, list_blocked_recipients
Campaigns: list_contacts, create_contact, upsert_contact, get_contact, update_contact, delete_contact, import_contacts, list_contact_imports, bulk_update_contacts, list_tags, list_contact_fields, set_contact_field, delete_contact_field, list_segments, get_segment, preview_segment, create_segment, update_segment, delete_segment, list_lists, create_list, get_list, update_list, delete_list, add_list_contacts, remove_list_contact, list_broadcasts, create_broadcast, get_broadcast, update_broadcast, delete_broadcast, send_broadcast, cancel_broadcast, list_broadcast_recipients, check_broadcast, send_broadcast_test, schedule_broadcast, unschedule_broadcast, duplicate_broadcast, send_broadcast_to_more, get_broadcast_report, get_newsletter_settings, update_newsletter_settings, get_campaign_overview, list_uploaded_images
Automations, events, and sending limits: track_event, list_automations, get_automation, create_automation, update_automation, delete_automation, set_automation_step, delete_automation_step, set_automation_step_variant, set_automation_status, send_automation_test_email, send_automation_test, enroll_contact, exit_contact, preview_automation, get_automations_overview, get_automation_report, list_automation_people, get_automation_person, get_sending_limits, update_sending_limits, list_automation_templates, get_automation_template, use_automation_template, list_events, list_event_names, list_connections, get_connection, create_connection, update_connection, delete_connection
Account, usage, analytics, and keys: get_account, get_account_diagnostics, get_analytics, list_api_keys, get_service_health

メールとスレッド

実際にメールを送信send_email
POST /emails

メールを1通送信する

SENDS REAL EMAIL. Send one message from a verified domain: raw html/text, a published hosted template, a reply in an existing thread, or a message with attachments. Pass idempotency_key so a retry cannot send twice; a retry must reuse the same key AND an identical request, otherwise SendHQ returns 409. attachments is a convenience that creates a draft, uploads each file, and sends with that draft; it cannot be combined with idempotency_key or draft_id (use create_draft + upload_attachment + send_email with draft_id for retry-safe attachment sends). Unpaid workspaces (integration trial) can deliver only to the account email or a mailbox-simulator test address, and cannot send attachments.

html、text、templateのうち少なくとも1つを指定してください。

パラメータ型必須説明
fromstringはい送信者。例:Acme <hello@example.com>。ドメインがこのワークスペースで検証済みである必要があります(list_sending_identitiesを参照)。(最大998文字)
tostring[]はい受信者。各エントリーはアドレスで、表示名を付けることもできます。to+cc+bccの合計は最大100件で、宛先ごとに配信クレジットを1つ消費します。(1〜100件)
ccstring[]いいえCcの受信者。(0〜100件)
bccstring[]いいえBccの受信者。(0〜100件)
subjectstringいいえ件名。テンプレートを送信する場合は省略します。(最大998文字)
textstringいいえプレーンテキストの本文。text、html、templateのいずれかを指定してください。
htmlstringいいえHTMLの本文。SendHQがサニタイズし、textが省略された場合はテキスト版を生成します。
reply_tostringいいえReply-Toアドレス。
headersobjectいいえ追加の安全なカスタムヘッダー(値は文字列)。例:{"X-Entity-Ref-ID": "123"}。From/To/Message-IDなどのルーティングヘッダーはSendHQが制御します。
message_classstringいいえtransactional(デフォルト)またはmarketing。マーケティングには、マーケティングが有効なプランまたはドメインが必要で、配信停止の処理が追加されます。(transactional、marketingのいずれか)
reply_to_email_idstringいいえ既存の会話の中で返信します。返信先のメッセージのem_… IDを指定します。SendHQがIn-Reply-To/Referencesとスレッドを設定します。
thread_idstringいいえメッセージを振り分ける明示的なスレッドID。
draft_idstringいいえ保存済みの下書き(dr_…)の添付ファイルをこのメッセージで送信します。送信が成功すると下書きは削除されます。
templateobjectいいえ直接指定したhtml/textの代わりに、公開済みのホスト型テンプレートを送信します。to受信者がちょうど1人で、cc/bccがないことが必要です。件名はテンプレートが提供します。id、keyのうち少なくとも1つを指定してください。
template.idstringいいえテンプレートID(tmpl_…)。idまたはkeyを指定してください。
template.keystringいいえaccount-welcomeなどのテンプレートキー。idまたはkeyを指定してください。
template.version_idstringいいえ任意の公開済みリリースID(tmplv_…)。デフォルトは現在の公開済みリリースです。
template.dataobjectいいえテンプレートの型付き変数に渡す値。
labelsstring[]いいえこのメッセージを振り分けるラベル名またはlbl_… ID。存在しない名前は作成されます。会話内の返信はラベルを引き継ぎ、バケットのラベル(skip_inbox)はそれらの返信を受信トレイに入れません。最大10個。(0〜10件)
idempotency_keystringいいえIdempotency-Keyヘッダー(最大200文字)。このリクエストをまったく同じ内容で再試行する場合にのみ再利用してください。(最大200文字)
attachmentsobject[]いいえ添付するファイル(最大10ファイル、合計10 MB)。それぞれcontent_base64(とfilename)またはローカルのfile_pathが必要です。(0〜10件)content_base64、file_pathのうち少なくとも1つを指定してください。
attachments[].filenamestringいいえ受信者に表示されるファイル名。content_base64を使う場合は必須です。デフォルトはfile_pathのベース名です。(最大255文字)
attachments[].content_typestringいいえMIMEタイプ。例:application/pdf。デフォルトはapplication/octet-streamです。
attachments[].content_base64stringいいえ標準のbase64でエンコードしたファイルの内容。
attachments[].file_pathstringいいえMCPサーバーのプロセスが読み取れるローカルファイルの絶対パス。
戻り値{id: em_…, providerMessageId, threadId, templateId, templateVersionId, isTest}。受け付けは配信ではありません。list_email_eventsで追跡してください。
tools/callのparamsの例
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "Your export is ready",
    "text": "Download it from your dashboard.",
    "idempotency_key": "export-ready-42"
  }
}
実際にメールを送信send_batch
POST /emails/batch

個別化したメールを一括送信する

SENDS REAL EMAIL。1回のリクエストで1〜100通の独立したメッセージを送信します(受信者ごとにテンプレートを個別化する場合はこれを使います)。各項目はsend_emailと同じ形式です(attachments/idempotency_keyを除く)。項目ごとに個別に成功または失敗します。HTTP 207は一部成功を意味するため、各data[i].okとdata[i].errorを確認してください。1つのidempotency_keyがバッチのボディ全体に適用されます。

パラメータ型必須説明
emailsobject[]はい送信するメッセージ。(1〜100件)html、text、templateのうち少なくとも1つを指定してください。
idempotency_keystringいいえバッチ全体に対するIdempotency-Key(最大200文字)。(最大200文字)
戻り値{data: [{index, ok, id?, error?: {message, status}}], count, successful, failed}。
tools/callのparamsの例
{
  "name": "send_batch",
  "arguments": {
    "emails": [
      {
        "from": "Acme <hello@example.com>",
        "to": [
          "owner@example.com"
        ],
        "template": {
          "key": "account-welcome",
          "data": {
            "first_name": "Asha"
          }
        }
      }
    ],
    "idempotency_key": "welcome-batch-2026-09-26"
  }
}
読み取り専用list_emails
GET /emails

メールを一覧表示・検索する

送信済みメール(direction: out)と受信メール(direction: in)を、フィルター付きで新しい順に一覧表示します。受信メールは分類されています。人間の受信トレイを読むにはdirection: in、archived: false、category: primaryを指定し、優先度の判断にはimportant: trueを使います。迷惑メールは、category: spamまたはinclude_spam: trueを指定しない限り非表示です。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
directionstringいいえ受信メールはin、送信済みメールはout。(in、outのいずれか)
statusstringいいえステータスによるフィルター。例:queued、sent、delivered、bounced、complained、failed。
domainstringいいえこのドメイン、またはカンマ区切りのドメインのリスト(いずれかに一致)のメッセージのみ。
inbox_idstringいいえこのインボックス(inb_…)が受信したメッセージのみ。
labelstringいいえこのラベルが付いたメッセージのみ。ラベルID lbl_…または正確な名前、あるいはカンマ区切りのリスト(いずれかに一致)を指定します。フォルダを確認するにはlist_labelsを使ってください。
archivedbooleanいいえfalse = 受信トレイビュー(アーカイブされていない受信メール)、true = アーカイブ済みのみ。すべてのメールを対象にする場合は省略します。
categorystringいいえprimary(人からのメール)、updates(ニュースレター、一斉送信メール、自動送信メール)、spam、またはカンマ区切りのリスト。迷惑メールは指定しない限り非表示です。
importantbooleanいいえtrue = 重要フラグが付いたメッセージのみ(自分が開始した会話への返信と、重要とマークされた送信者からのメール)。
include_spambooleanいいえ結果に迷惑メールを含めます(すべてのフォルダを横断して検索する場合)。
fromstringいいえ送信者アドレスにこの値を含むもの。
tostringいいえ受信者アドレスにこの値を含むもの。
unreadbooleanいいえtrue = 未読のみ、false = 既読のみ。
afterstringいいえISO-8601形式のタイムスタンプ。この日時より後に作成されたメッセージのみ。(date-time)
beforestringいいえISO-8601形式のタイムスタンプ。この日時より前に作成されたメッセージのみ。(date-time)
querystringいいえ件名、本文、送信者/受信者のアドレス、添付ファイル名を対象としたフリーテキスト検索。(最大200文字)
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [メールの概要], count, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_emails",
  "arguments": {
    "direction": "in",
    "unread": true,
    "limit": 25
  }
}
読み取り専用get_email
GET /emails/:email_id

メールを1通取得する

ヘッダー、html/textの本文、ステータス、スレッドのメタデータ、添付ファイルのメタデータを含むメッセージを1通取得します(バイトデータはdownload_attachmentでダウンロードします)。

パラメータ型必須説明
email_idstringはいメールID(em_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値メールオブジェクト:{id, direction, status, from, to, cc, bcc, subject, html, text, threadId, messageId, providerMessageId, readAt, createdAt, attachments: [{id, filename, contentType, sizeBytes, available}]}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_email",
  "arguments": {
    "email_id": "em_123"
  }
}
状態を変更mark_email
PATCH /emails/:email_id

既読、アーカイブ、迷惑メール、重要としてマークする

1通のメッセージを更新します:read、archived、category(primary、updates、spam。受信メールのみ)、important。迷惑メールとして報告したり重要とマークしたりすると、SendHQはその送信者について学習し、今後のメールに反映します。このメッセージだけを変更するにはlearn: falseを渡します。少なくとも1つのフィールドを渡してください。

パラメータ型必須説明
email_idstringはいメールID(em_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
readbooleanいいえtrue = 既読、false = 未読。
archivedbooleanいいえtrue = アーカイブ(受信トレイをスキップ)、false = 受信トレイに戻す。
categorystringいいえ受信メッセージをprimary、updates、spamのいずれかに移動します。(primary、updates、spamのいずれか)
importantbooleanいいえメッセージに重要フラグを付ける、または外します。
learnbooleanいいえfalse = この判定を送信者に対して記憶しない(デフォルトはtrue)。
戻り値更新されたメールオブジェクト。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "mark_email",
  "arguments": {
    "email_id": "em_123",
    "read": true
  }
}
破壊的操作delete_email
DELETE /emails/:email_id

メールを削除する

DESTRUCTIVE:保持されているメッセージとその保存済み添付ファイルをSendHQから完全に削除します。すでに配信されたメッセージを取り消すものではありません。

パラメータ型必須説明
email_idstringはいメールID(em_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_email",
  "arguments": {
    "email_id": "em_123"
  }
}
読み取り専用list_email_events
GET /emails/:email_id/events

メールの配信イベントを一覧表示する

送信済みメッセージ1通に対するプロバイダーのイベント:delivery、bounce、complaint、reject、open、click。これが、メッセージが配信されたかどうか、または失敗した理由を示す証拠です。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
email_idstringはいメールID(em_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [{event_type, recipient, reason, created_at, …}], count, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_email_events",
  "arguments": {
    "email_id": "em_123"
  }
}
読み取り専用get_thread
GET /threads/:thread_id

会話を取得する

会話内のすべてのメッセージ(送信・受信とも)を、それぞれの添付ファイルのメタデータとともに時系列順に取得します。

パラメータ型必須説明
thread_idstringはいスレッドID(通常は最初のメッセージのem_… ID。任意のメールのthreadIdを参照)。(最大128文字)
戻り値{id, subject, data: [メール]}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_thread",
  "arguments": {
    "thread_id": "em_123"
  }
}
Read-onlyemail_delivery
GET /emails/:email_id/delivery

Get an email delivery timeline

Queued, sent, delivered, delayed, bounced, complained, and failed events for one email, with bounce type and the SMTP diagnostic. Reasons are plain text.

パラメータ型必須説明
email_idstringはい
limitintegerいいえ
offsetintegerいいえ
Returns{emailId, status, timeline, count, limit, offset}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "email_delivery",
  "arguments": {
    "email_id": "em_123"
  }
}
Read-onlythread_delivery
GET /threads/:thread_id/delivery

Get a thread delivery summary

Counts of delivered, bounced, complained, and failed outbound messages in one conversation, plus each message's failure reason.

パラメータ型必須説明
thread_idstringはい
Returns{threadId, delivered, bounced, complained, failed, messages}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "thread_delivery",
  "arguments": {
    "thread_id": "thr_123"
  }
}

ラベルと自動振り分けルール

読み取り専用list_labels
GET /labels

ラベルを一覧表示する

ワークスペースのラベル(フォルダ)を、合計数、未読数、自動振り分けルールとともに一覧表示します。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [{id, name, color, totalCount, unreadCount, rules: [...]}], count, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_labels",
  "arguments": {}
}
読み取り専用get_label
GET /labels/:label_id

ラベルを取得する

件数と自動振り分けルールを含むラベルを1つ取得します。

パラメータ型必須説明
label_idstringはいラベルID(lbl_で始まる)または正確なラベル名。(最大128文字)
戻り値ラベルオブジェクト。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_label",
  "arguments": {
    "label_id": "Billing"
  }
}
状態を変更create_label
POST /labels

ラベルを作成する

フォルダ型のラベルを作成します。skip_inbox: trueを設定すると、エージェントが管理するバケットになります。labels: [name]を指定して送信すると、返信はそのラベルに振り分けられ、受信トレイには入りません。任意の自動振り分けルールで、新しい送信メールや受信メールを振り分けられます(ルールのすべての条件に一致する必要があります)。保持済みのメールも振り分けるにはapply_to_existingを設定します。

パラメータ型必須説明
namestringはいラベル名。例:Billing、Clients/Acme。ワークスペース内で一意(大文字と小文字を区別しない)。(最大64文字)
colorstringいいえ#1a73e8のような16進数のカラーコード。任意。
skip_inboxbooleanいいえバケットモード:このラベルが付いた受信メール(ルールによるもの、このラベル付きで送信した会話への返信、手動で付けたもの)はアーカイブされ、受信トレイではなくラベル内にのみ表示されます。
rulesobject[]いいえ任意の自動振り分けルール(最大20個)。それぞれinbox_id、from、to、subjectのうち少なくとも1つが必要です。(0〜20件)
rules[].directionstringいいえin(受信)またはout(送信)のメールのみ。両方を対象にする場合は省略します。(in、outのいずれか)
rules[].inbox_idstringいいえこのインボックス(inb_…)が受信したメールのみ。受信アドレスごとに専用のフォルダへ振り分けられます。
rules[].fromstringいいえ送信者にこのテキストを含むもの(大文字と小文字を区別しない)。例:@stripe.com。(最大200文字)
rules[].tostringいいえTo/Ccにこのテキストを含むもの(大文字と小文字を区別しない)。(最大200文字)
rules[].subjectstringいいえ件名にこのテキストを含むもの(大文字と小文字を区別しない)。(最大200文字)
rules[].skip_inboxbooleanいいえ一致した受信メールをアーカイブし、受信トレイではなくラベルのフォルダにのみ表示します。
apply_to_existingbooleanいいえルールに一致する保持済みのメールも振り分けます。
戻り値作成されたラベル(ルールを含む)。
tools/callのparamsの例
{
  "name": "create_label",
  "arguments": {
    "name": "Agent/Orders",
    "skip_inbox": true,
    "rules": [
      {
        "from": "@stripe.com"
      }
    ]
  }
}
状態を変更update_label
PATCH /labels/:label_id

ラベルの名前や色を変更する、またはバケットにする

ラベルの名前や色を変更したり、バケットモード(skip_inbox)を切り替えたりします。バケットモードを有効にすると、すでにそのラベルが付いている受信メールがアーカイブされます。

パラメータ型必須説明
label_idstringはいラベルID(lbl_で始まる)または正確なラベル名。(最大128文字)
namestringいいえ新しい名前。(最大64文字)
colorstringいいえ新しい16進数のカラーコード。
skip_inboxbooleanいいえバケットモード:このラベルが付いた受信メール(ルールによるもの、このラベル付きで送信した会話への返信、手動で付けたもの)はアーカイブされ、受信トレイではなくラベル内にのみ表示されます。
戻り値更新されたラベル。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_label",
  "arguments": {
    "label_id": "lbl_123",
    "name": "Finance/Billing"
  }
}
破壊的操作delete_label
DELETE /labels/:label_id

ラベルを削除する

DESTRUCTIVE:ラベルとそのルールを削除します。メール自体は保持され、このラベルが外れるだけです。

パラメータ型必須説明
label_idstringはいラベルID(lbl_で始まる)または正確なラベル名。(最大128文字)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_label",
  "arguments": {
    "label_id": "lbl_123"
  }
}
状態を変更create_label_rule
POST /labels/:label_id/rules

自動振り分けルールを追加する

ラベルにルールを追加し、一致する新着メールを自動的に振り分けます。設定したすべての条件に一致する必要があります。受信アドレスごとに専用のフォルダを持たせるにはinbox_idを使い、受信トレイに入れないようにするにはskip_inboxを追加します。

パラメータ型必須説明
label_idstringはいラベルID(lbl_で始まる)または正確なラベル名。(最大128文字)
directionstringいいえin(受信)またはout(送信)のメールのみ。両方を対象にする場合は省略します。(in、outのいずれか)
inbox_idstringいいえこのインボックス(inb_…)が受信したメールのみ。受信アドレスごとに専用のフォルダへ振り分けられます。
fromstringいいえ送信者にこのテキストを含むもの(大文字と小文字を区別しない)。例:@stripe.com。(最大200文字)
tostringいいえTo/Ccにこのテキストを含むもの(大文字と小文字を区別しない)。(最大200文字)
subjectstringいいえ件名にこのテキストを含むもの(大文字と小文字を区別しない)。(最大200文字)
skip_inboxbooleanいいえ一致した受信メールをアーカイブし、受信トレイではなくラベルのフォルダにのみ表示します。
apply_to_existingbooleanいいえ一致する保持済みのメールも振り分けます。
戻り値{id: lrule_…, labelId, direction, inboxId, from, to, subject, skipInbox}。
tools/callのparamsの例
{
  "name": "create_label_rule",
  "arguments": {
    "label_id": "Billing",
    "inbox_id": "inb_123",
    "skip_inbox": true
  }
}
破壊的操作delete_label_rule
DELETE /labels/:label_id/rules/:rule_id

自動振り分けルールを削除する

DESTRUCTIVE:自動振り分けルールを1つ削除します。すでに振り分けられたメールのラベルはそのまま残ります。

パラメータ型必須説明
label_idstringはいラベルID(lbl_で始まる)または正確なラベル名。(最大128文字)
rule_idstringはいルールID(lrule_で始まる)。get_labelで取得します。(最大128文字)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_label_rule",
  "arguments": {
    "label_id": "lbl_123",
    "rule_id": "lrule_123"
  }
}
状態を変更label_email
POST /emails/:email_id/labels

メールのラベルを追加・削除する

メッセージをフォルダ間で移動します。名前またはlbl_… IDでラベルを追加・削除します。addに存在しない名前を指定すると、createがfalseでない限りラベルが作成されます。

パラメータ型必須説明
email_idstringはいメールID(em_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
addstring[]いいえ追加するラベル。(0〜10件)
removestring[]いいえ削除するラベル。(0〜10件)
createbooleanいいえaddに存在しないラベルを作成します(デフォルトはtrue)。
戻り値labelsを含む更新されたメール。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "label_email",
  "arguments": {
    "email_id": "em_123",
    "add": [
      "Billing"
    ],
    "remove": [
      "Support"
    ]
  }
}

下書き、添付ファイル、送信者ID

読み取り専用list_sending_identities
GET /sending-identities

検証済みの送信者IDを一覧表示する

このワークスペースが現在送信に使えるアドレスとドメイン(検証済みドメイン、そのデフォルトのFrom、有効なインボックスのアドレス)。有効なfromを選ぶため、send_emailの前に呼び出してください。

パラメータはありません。

戻り値{domains: [検証済みドメイン名], addresses: [送信元アドレス], localParts: [...]}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_sending_identities",
  "arguments": {}
}
状態を変更create_draft
POST /drafts

下書きを作成する

作成画面用の下書きを作成します。下書きには添付ファイルを保持できます。下書きを作成し、upload_attachmentを実行してから、draft_idを指定してsend_emailを呼び出します。これ自体は何も送信しません。

パラメータ型必須説明
fromstringいいえ検証済みドメイン上の送信元アドレス(下書き中は空でもかまいません)。
tostring[]いいえ受信者。(0〜100件)
ccstring[]いいえCcの受信者。(0〜100件)
bccstring[]いいえBccの受信者。(0〜100件)
subjectstringいいえ件名。(最大998文字)
htmlstringいいえHTMLの本文。
textstringいいえプレーンテキストの本文。
reply_to_email_idstringいいえこの下書きが返信する対象のメールID。
thread_idstringいいえこの下書きが属するスレッドID。
戻り値下書きオブジェクト {id: dr_…, from, to, cc, bcc, subject, html, text, attachments: []}。
tools/callのparamsの例
{
  "name": "create_draft",
  "arguments": {
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice"
  }
}
読み取り専用list_drafts
GET /drafts

下書きを一覧表示する

作成画面用の下書きを、更新日時の新しい順に一覧表示します。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [下書き], count, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_drafts",
  "arguments": {}
}
読み取り専用get_draft
GET /drafts/:draft_id

下書きを取得する

添付ファイルのメタデータを含む下書きを1つ取得します。

パラメータ型必須説明
draft_idstringはい下書きID(dr_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値attachmentsを含む下書きオブジェクト。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
状態を変更update_draft
PUT /drafts/:draft_id

下書きの内容を置き換える

下書きの内容と受信者を置き換えます。これは完全な置き換えで、省略したフィールドはクリアされます。そのため、先にget_draftで読み取り、残したいフィールドをすべて送信してください。添付ファイルには影響しません。

パラメータ型必須説明
draft_idstringはい下書きID(dr_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
fromstringいいえ検証済みドメイン上の送信元アドレス(下書き中は空でもかまいません)。
tostring[]いいえ受信者。(0〜100件)
ccstring[]いいえCcの受信者。(0〜100件)
bccstring[]いいえBccの受信者。(0〜100件)
subjectstringいいえ件名。(最大998文字)
htmlstringいいえHTMLの本文。
textstringいいえプレーンテキストの本文。
reply_to_email_idstringいいえこの下書きが返信する対象のメールID。
thread_idstringいいえこの下書きが属するスレッドID。
戻り値更新された下書きオブジェクト。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_draft",
  "arguments": {
    "draft_id": "dr_123",
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice (updated)",
    "text": "Attached."
  }
}
破壊的操作delete_draft
DELETE /drafts/:draft_id

下書きを破棄する

DESTRUCTIVE:下書きを破棄し、その保存済み添付ファイルを完全に削除します。

パラメータ型必須説明
draft_idstringはい下書きID(dr_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
状態を変更upload_attachment
POST /drafts/:draft_id/attachments

下書きに添付ファイルをアップロードする

下書きにファイルを1つアップロードします(1メッセージあたり最大10ファイル、合計10 MB)。content_base64またはローカルのfile_pathを指定してください。送信時に添付ファイルを使うには有料プランが必要です。

content_base64、file_pathのうち少なくとも1つを指定してください。

パラメータ型必須説明
draft_idstringはい下書きID(dr_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
filenamestringいいえ受信者に表示されるファイル名。デフォルトはfile_pathのベース名です。(最大255文字)
content_typestringいいえMIMEタイプ。例:application/pdf。デフォルトはapplication/octet-streamです。
content_base64stringいいえ標準のbase64でエンコードしたファイルの内容。
file_pathstringいいえMCPサーバーのプロセスが読み取れるローカルファイルの絶対パス。
戻り値{id: att_…, filename, contentType, sizeBytes, available}。
tools/callのparamsの例
{
  "name": "upload_attachment",
  "arguments": {
    "draft_id": "dr_123",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_path": "/tmp/invoice.pdf"
  }
}
読み取り専用download_attachment
GET /attachments/:attachment_id

添付ファイルをダウンロードする

非公開の添付ファイル(送信、受信、下書き)をダウンロードします。base64の内容を返すか、save_to_pathが設定されている場合はファイルを書き込みます(overwriteがtrueでない限り上書きは拒否されます)。

パラメータ型必須説明
attachment_idstringはい添付ファイルID(att_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
save_to_pathstringいいえbase64を返す代わりにファイルを書き込む、任意のローカルの絶対パス。
overwritebooleanいいえsave_to_pathにある既存ファイルの置き換えを許可します。デフォルトはfalseです。
戻り値{attachment_id, filename, content_type, size_bytes, content_base64}または{attachment_id, filename, content_type, size_bytes, saved_to}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "download_attachment",
  "arguments": {
    "attachment_id": "att_123",
    "save_to_path": "/tmp/invoice.pdf"
  }
}
破壊的操作delete_attachment
DELETE /attachments/:attachment_id

添付ファイルを削除する

DESTRUCTIVE:保存済みの添付ファイルを完全に削除します(例:送信前に下書きからファイルを取り除く)。

パラメータ型必須説明
attachment_idstringはい添付ファイルID(att_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_attachment",
  "arguments": {
    "attachment_id": "att_123"
  }
}

ホスト型テンプレート

読み取り専用list_templates
GET /templates

ホスト型テンプレートを一覧表示する

ホスト型メールテンプレートを、公開状態と使用状況とともに一覧表示します。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
lifecyclestringいいえactive(デフォルト)、archived、all。(active、archived、allのいずれか)
querystringいいえ名前またはキーで検索します。(最大120文字)
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [テンプレート], count, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_templates",
  "arguments": {
    "lifecycle": "active"
  }
}
状態を変更create_template
POST /templates

ホスト型テンプレートを作成する

編集可能な下書き付きのテンプレートを作成します。スターター(welcome、reset、receipt、blank)から作成することもできます。キーで送信する前に公開してください。

パラメータ型必須説明
namestringはい人が読める名前。(最大120文字)
keystringいいえ送信用の固定キー:小文字、数字、ハイフンで構成され、英字で始まる(2〜64文字)。省略した場合は名前から生成されます。
starterstringいいえスターターの内容。(blank、welcome、reset、receiptのいずれか)
戻り値{template, draft, activeVersion, versions, usage}。
tools/callのparamsの例
{
  "name": "create_template",
  "arguments": {
    "name": "Account welcome",
    "key": "account-welcome",
    "starter": "welcome"
  }
}
読み取り専用get_template
GET /templates/:template_id

テンプレートを取得する

テンプレートの現在の下書き(revision付き)、有効な公開済みリリース、リリース履歴、使用状況を取得します。IDまたはキーを指定できます。

パラメータ型必須説明
template_idstringはいテンプレートID(tmpl_…)またはキー。(最大128文字)
戻り値{template, draft: {id, revision, subjectTemplate, htmlTemplate, textTemplate, variables, sampleData, …} | null, activeVersion, versions, usage}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
状態を変更update_template_draft
PUT /templates/:template_id/draft

テンプレートの下書きを保存する

楽観的同時実行制御を使って、テンプレートの編集可能な下書きを保存します。get_templateで取得した現在のrevisionを渡してください(409は他の誰かが先に保存したことを意味します。再度読み取ってから再試行してください)。これは下書きの内容の完全な置き換えで、省略したフィールドはクリアされるため、残したいフィールドをすべて送信してください。プレースホルダーには{{variable}}を使います。

パラメータ型必須説明
template_idstringはいテンプレートIDまたはキー。(最大128文字)
revisionintegerはいget_templateで取得した現在の下書きのリビジョン。(1〜…)
namestringいいえテンプレート名。(最大120文字)
subject_templatestringいいえプレースホルダーを含む件名。(最大998文字)
preheader_templatestringいいえプレビューテキスト。(最大240文字)
html_templatestringいいえプレースホルダーを含むHTMLの本文。
text_templatestringいいえプレースホルダーを含むプレーンテキストの本文。
fromstringいいえこのテンプレートで送信する際のデフォルトの送信者。
reply_tostringいいえデフォルトのReply-To。
variablesobject[]いいえ型付き変数の仕様。各項目:{key(小文字/アンダースコア), label, type: text|number|url|boolean, required(デフォルトはtrue), fallback, description}。
variables[].keystringはい
variables[].labelstringいいえ
variables[].typestringいいえ(text、number、url、booleanのいずれか)
variables[].requiredbooleanいいえ
variables[].fallbackanyいいえ
variables[].descriptionstringいいえ
sample_dataobjectいいえプレビューとテストに使うサンプル値。
戻り値{template, draft: {revision: next}, validation: {valid, findings}}。
tools/callのparamsの例
{
  "name": "update_template_draft",
  "arguments": {
    "template_id": "account-welcome",
    "revision": 3,
    "name": "Account welcome",
    "subject_template": "Welcome, {{first_name}}",
    "text_template": "Hi {{first_name}}",
    "variables": [
      {
        "key": "first_name",
        "type": "text",
        "required": true
      }
    ],
    "sample_data": {
      "first_name": "Asha"
    }
  }
}
状態を変更create_template_draft
POST /templates/:template_id/draft

公開済みリリースから新しい下書きを開始する

現在の公開済みリリースをコピーして、編集可能な新しい下書きを作成します(下書きがすでに存在する場合や、何も公開されていない場合は409)。

パラメータ型必須説明
template_idstringはいテンプレートIDまたはキー。(最大128文字)
戻り値{draft}。
tools/callのparamsの例
{
  "name": "create_template_draft",
  "arguments": {
    "template_id": "account-welcome"
  }
}
読み取り専用render_template
POST /templates/:template_id/render

テンプレートのプレビューをレンダリングする

下書き、公開済みリリース、または特定のバージョンについて、指定したデータでサーバーの実際の出力(subject、html、text)をレンダリングします。送信は行いません。データが変数の仕様に違反している場合は、findingsとともに422を返します。

パラメータ型必須説明
template_idstringはいテンプレートIDまたはキー。(最大128文字)
version_idstringいいえ任意のバージョンID。デフォルトは下書き、次に公開済みリリースです。
dataobjectいいえ変数の値。デフォルトはそのバージョンのサンプルデータです。
戻り値{subject, html, text, preheader, versionId, versionNumber, isDraft, findings}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "render_template",
  "arguments": {
    "template_id": "account-welcome",
    "data": {
      "first_name": "Asha"
    }
  }
}
実際にメールを送信send_template_test
POST /templates/:template_id/test

テンプレートのテストメールを送信する

SENDS REAL EMAIL. Send a [Test]-prefixed snapshot of the draft (or a given version) to the given recipients. Counts against usage; trial workspaces can only send to the account email or a mailbox-simulator test address.

パラメータ型必須説明
template_idstringはいテンプレートIDまたはキー。(最大128文字)
tostring[]はいテストの受信者。(1〜100件)
fromstringいいえ検証済みドメイン上の送信者。デフォルトはテンプレートのFromです。
version_idstringいいえ任意のバージョンID。
dataobjectいいえ変数の値。デフォルトはサンプルデータです。
戻り値{id: em_…, providerMessageId, threadId, isTest: true}。
tools/callのparamsの例
{
  "name": "send_template_test",
  "arguments": {
    "template_id": "account-welcome",
    "to": [
      "owner@example.com"
    ]
  }
}
状態を変更publish_template
POST /templates/:template_id/publish

テンプレートのリリースを公開する

現在の下書きを、template.keyを指定したsend_emailが使用する変更不可のリリースとして公開します。バリデーションエラーがある場合は422とfindingsで失敗し、本番環境ですでに使われているテンプレートの現行の変数仕様を壊す場合は409で失敗します。

パラメータ型必須説明
template_idstringはいテンプレートIDまたはキー。(最大128文字)
戻り値{template, published}。
tools/callのparamsの例
{
  "name": "publish_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
状態を変更archive_template
POST /templates/:template_id/archive

テンプレートをアーカイブする

このテンプレートを使った新規送信を停止します(履歴は保持され、restore_templateで元に戻せます)。このキーで送信している連携はすべて404で失敗するようになります。

パラメータ型必須説明
template_idstringはいテンプレートIDまたはキー。(最大128文字)
戻り値{template}。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "archive_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
状態を変更restore_template
POST /templates/:template_id/restore

アーカイブしたテンプレートを復元する

アーカイブしたテンプレートを再び有効にします。

パラメータ型必須説明
template_idstringはいテンプレートIDまたはキー。(最大128文字)
戻り値{template}。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "restore_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

ドメインとDNS

読み取り専用list_domains
GET /domains

ドメインを一覧表示する

送信ドメインを、集約されたsetup_status(verified | checking | pending)、レコードごとのDNS状態、受信のステータスとともに一覧表示します。未検証のドメインはその場で再チェックされるため、時間がかかる場合があります。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [レコードを含むドメイン], count, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_domains",
  "arguments": {}
}
読み取り専用get_domain
GET /domains/:domain_id

ドメインの設定詳細を取得する

1つのドメインについて、公開すべき正確なDNSレコード(type、name、value)、2つの公開リゾルバーから見た各レコードの現在の状態、修正方法付きのdns_issues、受信のステータスを取得します。

パラメータ型必須説明
domain_idstringはいドメインID(dom_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値{id, name, status, setup_status, dns_propagating, records: [{type, name, value, verified, dns_state}], dns_issues: [{code, message, …}], inbound_domain, inbound_status}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
状態を変更add_domain
POST /domains

送信ドメインを追加する

Register a domain you control for sending. Returns the DNS records (Easy DKIM CNAMEs) the owner must publish. Does not change DNS itself. Counts against the plan's domain limit.

パラメータ型必須説明
namestringはいドメイン名のみ。例:example.com、mail.example.com。(最大253文字)
default_fromstringいいえこのドメインの任意のデフォルト送信元アドレス。
戻り値{id: dom_…, name, status: pending, records: [...], ses: {configured}}。
tools/callのparamsの例
{
  "name": "add_domain",
  "arguments": {
    "name": "example.com"
  }
}
状態を変更verify_domain
POST /domains/:domain_id/verify

ドメインを検証する

Run a live DNS and DKIM verification check now. Safe to repeat; poll every 30–60 s after DNS changes (propagation can take minutes to hours). Sending is allowed once status is verified.

パラメータ型必須説明
domain_idstringはいドメインID(dom_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値{domain, checks: {ses, dkim, dkim_status}, status: verified|pending}。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "verify_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
破壊的操作delete_domain
DELETE /domains/:domain_id

ドメインを削除する

DESTRUCTIVE:受信のルーティングを含め、ドメインをワークスペースから削除します。その直後から、このドメインからの送信は失敗します。DNSプロバイダー上のDNSレコードは削除されません。

パラメータ型必須説明
domain_idstringはいドメインID(dom_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
読み取り専用get_dns_provider
GET /dns/provider

DNSプロバイダーとレコードのホストを検出する

ドメインの権威DNSプロバイダーを検出し、各レコードについてそのプロバイダーに入力する相対ホスト、推奨されるDMARCレコード、受信用MXのガイダンス、ワンクリック設定(Domain Connect)が利用可能かどうかを返します。

パラメータ型必須説明
domain_idstringはいドメインID(dom_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値{detectionStatus, detected, zone, nameservers, recordHosts: {recordId: host}, inbound, recommendations, authentication, providers: {domainConnect: {available, providerName}}}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_dns_provider",
  "arguments": {
    "domain_id": "dom_123"
  }
}

メール受信

状態を変更setup_inbound
POST /domains/:domain_id/inbound/setup

ドメインのメール受信を有効にする

Provision inbound receiving for a verified domain. Uses the root domain when it has no conflicting MX, otherwise inbound.<domain>. Returns the MX record the owner must publish; it does not edit DNS.

パラメータ型必須説明
domain_idstringはいドメインID(dom_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値{domain: 受信用ドメイン, status: dns_pending|ready, record: {type: MX, name, value}}。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "setup_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
状態を変更verify_inbound
POST /domains/:domain_id/inbound/verify

受信用MXを検証する

受信用MXレコードを再チェックします。両方の公開リゾルバーから確認できると、ステータスがreadyになります。

パラメータ型必須説明
domain_idstringはいドメインID(dom_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値{domain, status: ready|dns_pending|propagating|checking, record}。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "verify_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
読み取り専用list_inboxes
GET /inboxes

受信用アドレスを一覧表示する

受信用アドレスを一覧表示します。1つのドメインに絞り込むこともできます。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
domain_idstringいいえ任意のドメインIDによるフィルター。
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [{id, address, name, status, domainId}], count, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_inboxes",
  "arguments": {
    "domain_id": "dom_123"
  }
}
読み取り専用get_inbox
GET /inboxes/:inbox_id

インボックスを取得する

受信用アドレスを1つ取得します。

パラメータ型必須説明
inbox_idstringはいインボックスID(inb_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値インボックスオブジェクト。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}
状態を変更create_inbox
POST /inboxes

受信用アドレスを作成する

受信のステータスがreadyのドメイン上に、support@<receiving domain>のようなアドレスを作成します(先にsetup_inboundとverify_inboundを実行してください)。受信したメールは、direction inとしてlist_emailsに表示されます。

パラメータ型必須説明
domain_idstringはいドメインID(dom_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
local_partstringはい@より前の部分。例:support。(最大64文字)
namestringいいえ任意の表示名。
戻り値{id: inb_…, address, name, status: active}。
tools/callのparamsの例
{
  "name": "create_inbox",
  "arguments": {
    "domain_id": "dom_123",
    "local_part": "support",
    "name": "Support"
  }
}
状態を変更update_inbox
PATCH /inboxes/:inbox_id

インボックスの名前を変更する、有効化する、無効化する

インボックスの名前を変更するか、ステータスをactive / disabledに設定します。

パラメータ型必須説明
inbox_idstringはいインボックスID(inb_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
namestringいいえ新しい表示名。
statusstringいいえ新しいステータス。(active、disabledのいずれか)
戻り値更新されたインボックス。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_inbox",
  "arguments": {
    "inbox_id": "inb_123",
    "status": "disabled"
  }
}
実際にメールを送信set_inbox_forwarding
PUT /inboxes/:inbox_id/forwarding

インボックスを別のアドレスに転送する

アカウント所有者以外に転送する場合はSENDS REAL EMAIL。インボックスが受信したメールの転送先を設定します。所有者自身のアドレスは即座に有効になります。それ以外のアドレスには確認メールが届き、転送先で誰かが確認するまで転送はpendingのままです。転送を無効にするにはforward_to: nullを渡します。転送されたコピーはインボックスのアドレスから送信され、元の送信者がReply-Toに設定されます。

パラメータ型必須説明
inbox_idstringはいインボックスID(inb_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
forward_tostring,nullはい転送先のメールアドレス。転送を無効にする場合はnull。(最大254文字)
戻り値forwardToとforwardStatus(off、pending、active)を含むインボックス。
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "set_inbox_forwarding",
  "arguments": {
    "inbox_id": "inb_123",
    "forward_to": "team@example.net"
  }
}
破壊的操作delete_inbox
DELETE /inboxes/:inbox_id

インボックスを削除する

DESTRUCTIVE:受信用アドレスを削除します。受信済みのメールは保持されますが、このアドレス宛ての新着メールはここに振り分けられなくなります。

パラメータ型必須説明
inbox_idstringはいインボックスID(inb_で始まる)。一覧取得ツールや作成ツールから返されたもの。(最大128文字)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

到達率、バウンス、サプレッション

読み取り専用deliverability_stats
GET /deliverability/stats

過去30日間の配信統計を取得する

ワークスペース全体の過去30日間の合計:sent、delivery、bounce、complaint、reject、open、click、deliveryRate(%)。

パラメータはありません。

戻り値{window: 30d, sent, delivery, bounce, complaint, reject, open, click, deliveryRate}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "deliverability_stats",
  "arguments": {}
}
Read-onlydeliverability_account
GET /deliverability/account

Get account delivery rates

Daily ladder, today's usage, 7-day hard-bounce and complaint rates against the promote, hold, and pause thresholds, and a per-day trend. Diagnostic text is plain text.

パラメータ型必須説明
daysintegerいいえ(one of 7, 30, 90)
Returns{days, trend, rolling7d, thresholds, ladder}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "deliverability_account",
  "arguments": {
    "days": 30
  }
}
Read-onlydeliverability_domains
GET /deliverability/domains

Get domain delivery rates

Per sending domain: sent, delivered, hard and soft bounces, complaints, failures, rates, and an active Gmail cap or 4.7.28 backoff when one applies.

パラメータ型必須説明
daysintegerいいえ
domainstringいいえ
limitintegerいいえ
offsetintegerいいえ
Returns{days, data, count, limit, offset}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "deliverability_domains",
  "arguments": {
    "days": 30
  }
}
Read-onlydeliverability_senders
GET /deliverability/senders

Get sender delivery rates

Per From address: sent, delivered, hard and soft bounces, complaints, failures, and rates.

パラメータ型必須説明
daysintegerいいえ
domainstringいいえ
limitintegerいいえ
offsetintegerいいえ
Returns{days, data, count, limit, offset}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "deliverability_senders",
  "arguments": {
    "days": 30
  }
}
Read-onlyscore_email
POST /deliverability/score

Score an email's content

A checklist of one email's content before it is sent: 100 for a plain email with no links and no images, lower for each thing mail filters look at (a designed layout, links to another site than the sender's, link shorteners, images with few words, hidden text, capitals, an empty subject, very long HTML). Returns each finding with the points it costs and a one-line suggestion, most points first. Read-only: nothing is stored or sent. Pass the email as written; the unsubscribe footer and tracking SendHQ adds are not scored. It looks at content only: sender reputation, authentication and how recipients react decide more of where mail lands, so treat it as a checklist, not a prediction.

パラメータ型必須説明
subjectstringいいえThe subject line.
htmlstringいいえThe HTML as written, before SendHQ adds its footer or tracking. (max 2000000 chars)
textstringいいえThe plain-text part. Compared with the HTML when both are given; scored on its own when there is no HTML. (max 2000000 chars)
fromstringいいえThe sender: an email address or a domain such as example.com. Without it, links to other sites are not judged. (max 320 chars)
Returns{score (0 to 100), deductions: [{id, points, count, suggestion}], warnings: [{id, message}]}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "score_email",
  "arguments": {
    "from": "hello@example.com",
    "subject": "Your cart is still here",
    "html": "<p>Pick up where you left off.</p><p><a href=\"https://bit.ly/3xyz\">Finish checkout</a></p>"
  }
}
読み取り専用list_sender_reputation
GET /deliverability/reputation

送信者レピュテーションを一覧表示する

Fromアドレスごとのレピュテーションの状態:active、throttled(1日あたりの上限が低い)、paused(送信すると423が返る)と、その理由および1日あたりの上限。送信が423や429で失敗した場合に確認してください。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [{sender, status, dailyLimit, reason, cleanSince, warnedAt, pausedAt, evaluatedAt}], count, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_sender_reputation",
  "arguments": {}
}
読み取り専用list_suppressions
GET /suppressions

サプレッションを一覧表示する

ワークスペースのサプレッションリスト:恒久的なバウンスまたは迷惑メール報告の後にブロックされた受信者です。これらの受信者への送信は422で失敗します。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [{email, reason, detail, created_at}], count, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_suppressions",
  "arguments": {}
}
破壊的操作remove_suppression
DELETE /suppressions/:email

バウンスのサプレッションを解除する

DESTRUCTIVE(安全のためのブロックを弱めます):バウンスのサプレッションを解除し、そのアドレスに再びメールを送れるようにします。アドレスが現在は有効であることを人間が確認した場合にのみ実行してください。苦情によるサプレッションは解除できません(409)。

パラメータ型必須説明
emailstringはいサプレッション対象の受信者アドレス。(最大320文字)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "remove_suppression",
  "arguments": {
    "email": "fixed-mailbox@example.net"
  }
}
読み取り専用list_blocked_recipients
GET /blocked-recipients

ブロックされた受信者を一覧表示する

SendHQが送信を拒否するすべての受信者(バウンス、苦情、ドメイン単位のマーケティングの配信停止)を、種類別のサマリーとともに返します。最新の500件まで読み取ります。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [{email, domain, kind: bounce|complaint|unsubscribe, reason, detail, source, status, created_at}], count, summary: {total, bounce, complaint, unsubscribe}, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_blocked_recipients",
  "arguments": {}
}

Campaigns

Read-onlylist_contacts
GET /contacts

List contacts

Campaigns: Newest-first contacts with their status, consent evidence, tags, custom fields, engagement (bot-filtered, estimated opens and clicks), and the lists they are subscribed to. Filter by list, status (including dormant), email/name substring (* is an email wildcard, e.g. *@example.com), tag, source, signup date, or a saved segment. Paginated: the result includes pagination {offset, limit, returned, has_more, next_offset}.

パラメータ型必須説明
list_idstringいいえOnly members of this list (lst_…).
statusstringいいえOnly contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant)
querystringいいえEmail or name contains this text; * is a wildcard on the email. (max 200 chars)
tagstringいいえOnly contacts with this tag. (max 60 chars)
sourcestringいいえHow the contact was added. (one of form, api, import)
afterstringいいえSigned up at or after this time. ISO 8601 date or date-time. (max 40 chars)
beforestringいいえSigned up before this time. ISO 8601 date or date-time. (max 40 chars)
segment_idstringいいえOnly contacts matching this saved segment (seg_…).
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [contacts with tags, engagement, dormant, country], count, total, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_contacts",
  "arguments": {
    "status": "subscribed"
  }
}
Changes statecreate_contact
POST /contacts

Add a contact

Campaigns: Add one contact to the workspace, optionally to lists and with tags. A subscribed contact (the default) needs consent_basis: how this person agreed to receive your email. Only add people who asked for your email. Use status: unsubscribed to record an opt-out. Addresses already suppressed or unsubscribed from the workspace are stored with that status. Fails with 409 if the email already exists.

パラメータ型必須説明
emailstringはいEmail address. (max 320 chars)
namestringいいえDisplay name; the first word is {{first_name}}. (max 200 chars)
fieldsobjectいいえCustom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field.
tagsstring[]いいえTags to attach, e.g. ["VIP"]. Up to 50. (0–50 items)
list_idsstring[]いいえLists to add the contact to (lst_…). (0–100 items)
statusstringいいえsubscribed (default, requires consent_basis) or unsubscribed. (one of subscribed, unsubscribed)
consent_basisstringいいえHow these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars)
ReturnsThe contact.
tools/callのparamsの例
{
  "name": "create_contact",
  "arguments": {
    "email": "ada@example.net",
    "name": "Ada Lovelace",
    "consent_basis": "Ticked the newsletter box at checkout on acme.com"
  }
}
Changes stateupsert_contact
PUT /contacts

Create or update a contact by email

Campaigns: Create the contact with this email, or change the one that exists: set name, timezone, and locale, merge fields, and add tags. A new contact needs consent_basis and takes the status its address already has (bounced or complained when suppressed, unsubscribed when it opted out, otherwise subscribed). An existing contact's status is never changed, so nobody is resubscribed. Unlike create_contact it does not fail when the email exists. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
emailstringはいEmail address. (max 320 chars)
namestringいいえDisplay name; the first word is {{first_name}}. (max 200 chars)
fieldsobjectいいえCustom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
tagsstring[]いいえTags to add, e.g. ["VIP"]. Existing tags are kept. (0–50 items)
timezonestringいいえIANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
localestringいいえLanguage tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
consent_basisstringいいえHow this person agreed to receive your email, e.g. Created an account on acme.com and accepted product emails. Required when the email is not a contact yet. 10-500 characters. (max 500 chars)
ReturnsThe contact, plus timezone, locale, and created (true when it did not exist before).
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "upsert_contact",
  "arguments": {
    "email": "ada@example.net",
    "name": "Ada Lovelace",
    "fields": {
      "plan": "pro"
    },
    "timezone": "Europe/London",
    "consent_basis": "Created an account on acme.com and accepted product emails"
  }
}
Read-onlyget_contact
GET /contacts/:contact_id

Get a contact

Campaigns: One contact by ID or email: status, consent evidence (source, basis, opt-in and confirmation times), custom fields, and subscribed lists.

パラメータ型必須説明
contact_idstringはいContact ID (starts with ct_) or the contact's email address. (max 320 chars)
ReturnsThe contact.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_contact",
  "arguments": {
    "contact_id": "ct_123"
  }
}
Changes stateupdate_contact
PATCH /contacts/:contact_id

Update, tag, or unsubscribe a contact

Campaigns: Change a contact's name, merge custom fields (null removes one), change tags (tags replaces the whole set; add_tags and remove_tags change it), or set status to unsubscribed. A contact can never be resubscribed through the API; only the recipient can, by confirming a signup form.

パラメータ型必須説明
contact_idstringはいContact ID (starts with ct_) or the contact's email address. (max 320 chars)
namestringいいえNew display name. (max 200 chars)
fieldsobjectいいえCustom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field.
tagsstring[]いいえReplace all of the contact's tags with these. (0–50 items)
add_tagsstring[]いいえTags to add. (0–50 items)
remove_tagsstring[]いいえTags to remove. (0–50 items)
statusstringいいえOnly unsubscribed is accepted. (one of unsubscribed)
ReturnsThe updated contact.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_contact",
  "arguments": {
    "contact_id": "ct_123",
    "fields": {
      "plan": "team"
    }
  }
}
Destructivedelete_contact
DELETE /contacts/:contact_id

Delete a contact

DESTRUCTIVE: permanently delete a contact and its list memberships. Suppressions and recorded unsubscribes are kept, so the address still cannot be mailed if it is added again. Part of Campaigns.

パラメータ型必須説明
contact_idstringはいContact ID (starts with ct_) or the contact's email address. (max 320 chars)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_contact",
  "arguments": {
    "contact_id": "ct_123"
  }
}
Changes stateimport_contacts
POST /contact-imports

Import contacts from CSV

Campaigns: Import up to 5,000 CSV rows (5 MB) per call, optionally into a list. The header row needs an email column; name (or first_name/last_name), status, and tags (separated by ; or |) are recognized and other columns become custom fields. consent_basis is required and recorded on every new contact. tags are added to every accepted row. Rows whose status says unsubscribed import as unsubscribed; existing contacts keep their status. Returns counts of accepted, created, existing, skipped (duplicates), and invalid rows with line numbers.

パラメータ型必須説明
csvstringはいThe CSV file content, header row first. (max 5242880 chars)
list_idstringいいえAdd every accepted row to this list (lst_…).
consent_basisstringはいHow these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars)
tagsstring[]いいえTags to add to every accepted row, e.g. ["imported-2026-11"]. (0–50 items)
update_existingbooleanいいえMerge names and fields into contacts that already exist. Their status never changes.
Returns{id, accepted, created, existing, skipped, invalid, errors: [{line, reason}], tags}.
tools/callのparamsの例
{
  "name": "import_contacts",
  "arguments": {
    "csv": "email,name\nada@example.net,Ada Lovelace\n",
    "consent_basis": "Newsletter signups exported from Mailchimp (double opt-in)"
  }
}
Read-onlylist_contact_imports
GET /contact-imports

List contact imports

Campaigns: Recent CSV imports with their consent basis and row counts.

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [imports], count, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_contact_imports",
  "arguments": {}
}
Destructivebulk_update_contacts
POST /contacts/bulk

Bulk update contacts

DESTRUCTIVE when action is delete (permanent) or unsubscribe (cannot be undone through the API). Apply one action to up to 10,000 contacts: the IDs in contact_ids, or everyone matching filter (the list_contacts filters). Actions: tag / untag (with tags), add_to_list / remove_from_list (with list_id), unsubscribe, delete. Adding to a list mirrors each contact's status, so nobody is resubscribed. delete needs confirm_count equal to the number of contacts it would delete: call once without it to get that count (409), confirm with the user, then repeat with it. Part of Campaigns.

パラメータ型必須説明
actionstringはいWhat to do. (one of tag, untag, add_to_list, remove_from_list, unsubscribe, delete)
contact_idsstring[]いいえContact IDs (ct_…). Use this or filter. (0–10000 items)
filterobjectいいえEveryone matching these list_contacts filters. Use this or contact_ids.
filter.list_idstringいいえMembers of this list.
filter.statusstringいいえOnly contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant)
filter.querystringいいえEmail or name contains; * is an email wildcard. (max 200 chars)
filter.tagstringいいえHas this tag. (max 60 chars)
filter.sourcestringいいえHow the contact was added. (one of form, api, import)
filter.afterstringいいえSigned up at or after. ISO 8601 date or date-time. (max 40 chars)
filter.beforestringいいえSigned up before. ISO 8601 date or date-time. (max 40 chars)
filter.segment_idstringいいえMatches this segment.
tagsstring[]いいえFor tag and untag. (0–50 items)
list_idstringいいえFor add_to_list and remove_from_list (lst_…).
confirm_countintegerいいえFor delete: the number of contacts that will be deleted, from the 409 response. (0–…)
Returns{ok, action, count}; for an unconfirmed delete, a 409 error whose message gives the count.
AnnotationsdestructiveHint
tools/callのparamsの例
{
  "name": "bulk_update_contacts",
  "arguments": {
    "action": "tag",
    "tags": [
      "october"
    ],
    "filter": {
      "list_id": "lst_123",
      "status": "subscribed"
    }
  }
}
Read-onlylist_tags
GET /tags

List contact tags

Campaigns: The workspace's contact tags, most used first, with how many contacts carry each (up to 500). Paginated.

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [{tag, count}], count, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_tags",
  "arguments": {}
}
Read-onlylist_contact_fields
GET /contact-fields

List custom contact fields

Campaigns: Defined custom contact fields with label and type (text, number, date). Defined fields are known to check_broadcast's merge-tag check and typed in segment conditions. Contacts may also carry undefined keys. Paginated.

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [{key, label, type, createdAt}], count, types, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_contact_fields",
  "arguments": {}
}
Changes stateset_contact_field
PUT /contact-fields/:field_key

Define a custom contact field

Campaigns: Create or change a custom field definition (label and type). Values live on each contact's fields. Built-in merge tags (email, name, first_name, last_name, fields, unsubscribe_url) cannot be used as keys. A workspace may define 50 fields.

パラメータ型必須説明
field_keystringはいField key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars)
labelstringいいえLabel shown in the dashboard. Defaults to the key. (max 80 chars)
typestringいいえtext (default), number, or date. (one of text, number, date)
Returns{key, label, type, createdAt}.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "set_contact_field",
  "arguments": {
    "field_key": "plan",
    "label": "Plan",
    "type": "text"
  }
}
Destructivedelete_contact_field
DELETE /contact-fields/:field_key

Delete a custom field definition

DESTRUCTIVE: delete a custom field definition. Values already stored on contacts are kept. Fails with 404 when the field is not defined. Part of Campaigns.

パラメータ型必須説明
field_keystringはいField key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_contact_field",
  "arguments": {
    "field_key": "plan"
  }
}
Read-onlylist_segments
GET /segments

List segments

Campaigns: Saved segments with count (subscribed, non-dormant contacts in the workspace that match now) and fields, the condition fields and operators each accepts. Paginated.

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [{id, name, match, conditions, count}], count, fields, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_segments",
  "arguments": {}
}
Read-onlyget_segment
GET /segments/:segment_id

Get a segment

Campaigns: One segment with its conditions and live count.

パラメータ型必須説明
segment_idstringはいSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
Returns{id, name, match, conditions, count}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_segment",
  "arguments": {
    "segment_id": "seg_123"
  }
}
Read-onlypreview_segment
POST /segments/preview

Preview segment conditions

Campaigns: Count and sample (up to 5) the subscribed, non-dormant contacts that match conditions without saving them. Read-only; use it to check conditions before create_segment.

パラメータ型必須説明
matchstringいいえall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]いいえUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringはいtag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystringいいえCustom field key when field is field. (max 40 chars)
conditions[].opstringはいtag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,numberいいえRequired except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
Returns{count, sample: [contacts]}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "preview_segment",
  "arguments": {
    "match": "all",
    "conditions": [
      {
        "field": "tag",
        "op": "has",
        "value": "VIP"
      },
      {
        "field": "opened",
        "op": "in_last_days",
        "value": 90
      }
    ]
  }
}
Changes statecreate_segment
POST /segments

Create a segment

Campaigns: Save a segment: up to 20 conditions joined by match. Use it as a broadcast's audience.segment_id, as list_contacts segment_id, or in bulk_update_contacts filters. A workspace may have 200 segments.

パラメータ型必須説明
namestringはいSegment name. (max 120 chars)
matchstringいいえall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]いいえUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringはいtag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystringいいえCustom field key when field is field. (max 40 chars)
conditions[].opstringはいtag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,numberいいえRequired except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
ReturnsThe segment with its count.
tools/callのparamsの例
{
  "name": "create_segment",
  "arguments": {
    "name": "Engaged pro customers",
    "conditions": [
      {
        "field": "fields.plan",
        "op": "equals",
        "value": "pro"
      },
      {
        "field": "opened",
        "op": "in_last_days",
        "value": 90
      }
    ]
  }
}
Changes stateupdate_segment
PATCH /segments/:segment_id

Update a segment

Campaigns: Rename a segment or change match or conditions (which replaces the whole list). Broadcasts using it pick up the change when they start sending.

パラメータ型必須説明
segment_idstringはいSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
namestringいいえSegment name. (max 120 chars)
matchstringいいえall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]いいえUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringはいtag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystringいいえCustom field key when field is field. (max 40 chars)
conditions[].opstringはいtag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,numberいいえRequired except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
ReturnsThe updated segment with its count.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_segment",
  "arguments": {
    "segment_id": "seg_123",
    "name": "Pro customers"
  }
}
Destructivedelete_segment
DELETE /segments/:segment_id

Delete a segment

DESTRUCTIVE: delete a saved segment. Contacts are not affected. Fails with 409 while a sending or scheduled broadcast uses it. Part of Campaigns.

パラメータ型必須説明
segment_idstringはいSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_segment",
  "arguments": {
    "segment_id": "seg_123"
  }
}
Read-onlylist_lists
GET /lists

List contact lists

Campaigns: Contact lists with subscribed, pending, and unsubscribed counts and their hosted signup form settings.

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [lists], count, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_lists",
  "arguments": {}
}
Changes statecreate_list
POST /lists

Create a list

Campaigns: Create a contact list. Set form_enabled to publish a hosted double opt-in signup form (its URL is in form.url); form_from is the sender, on a verified domain, of the confirmation email, and redirect_url is an optional https page shown after confirming. welcome sends one welcome email when someone confirms. site publishes a public newsletter site at https://sendhq.cc/n/<slug> with the signup form, sent issues, and RSS.

パラメータ型必須説明
namestringはいList name, shown on the signup form. (max 200 chars)
descriptionstringいいえShort description shown on the signup form. (max 500 chars)
form_enabledbooleanいいえPublish the hosted signup form.
form_fromstringいいえSender of signup confirmation emails, e.g. Acme <news@example.com>, on a verified domain. (max 320 chars)
redirect_urlstringいいえhttps page to open after a signup is confirmed. (max 500 chars)
welcomeobjectいいえWelcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled.
welcome.enabledbooleanいいえSend it.
welcome.subjectstringいいえSubject; merge tags allowed. (max 300 chars)
welcome.htmlstringいいえHTML body; merge tags allowed. (max 500000 chars)
welcome.markdownstringいいえMarkdown body instead of html, rendered with the workspace design. (max 200000 chars)
siteobjectいいえPublic newsletter site at https://sendhq.cc/n/<slug>: a signup form, every issue sent with web.enabled, and an RSS feed at /n/<slug>/feed.xml. Needs the signup form on. A reserved or taken slug fails with 409.
site.enabledbooleanいいえPublish the site.
site.slugstring,nullいいえAddress after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars)
site.titlestring,nullいいえSite title. Defaults to the list name. (max 120 chars)
site.descriptionstring,nullいいえShort description under the title. (max 300 chars)
site.accentstring,nullいいえAccent color, e.g. #0a7d4f.
ReturnsThe list.
tools/callのparamsの例
{
  "name": "create_list",
  "arguments": {
    "name": "Product updates"
  }
}
Read-onlyget_list
GET /lists/:list_id

Get a list

Campaigns: One list with member counts and signup form settings.

パラメータ型必須説明
list_idstringはいList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
ReturnsThe list.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_list",
  "arguments": {
    "list_id": "lst_123"
  }
}
Changes stateupdate_list
PATCH /lists/:list_id

Update a list

Campaigns: Rename a list, change its description, or change its hosted signup form, welcome email, or newsletter site. Omitted keys inside welcome and site keep their value.

パラメータ型必須説明
list_idstringはいList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
namestringいいえNew name. (max 200 chars)
descriptionstringいいえNew description. (max 500 chars)
form_enabledbooleanいいえPublish or unpublish the hosted signup form.
form_fromstringいいえSender of signup confirmation emails, on a verified domain. (max 320 chars)
redirect_urlstringいいえhttps page to open after a signup is confirmed. (max 500 chars)
welcomeobjectいいえWelcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled.
welcome.enabledbooleanいいえSend it.
welcome.subjectstringいいえSubject; merge tags allowed. (max 300 chars)
welcome.htmlstringいいえHTML body; merge tags allowed. (max 500000 chars)
welcome.markdownstringいいえMarkdown body instead of html, rendered with the workspace design. (max 200000 chars)
siteobjectいいえPublic newsletter site at https://sendhq.cc/n/<slug>: a signup form, every issue sent with web.enabled, and an RSS feed at /n/<slug>/feed.xml. Needs the signup form on. A reserved or taken slug fails with 409.
site.enabledbooleanいいえPublish the site.
site.slugstring,nullいいえAddress after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars)
site.titlestring,nullいいえSite title. Defaults to the list name. (max 120 chars)
site.descriptionstring,nullいいえShort description under the title. (max 300 chars)
site.accentstring,nullいいえAccent color, e.g. #0a7d4f.
ReturnsThe updated list.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_list",
  "arguments": {
    "list_id": "lst_123",
    "form_enabled": false
  }
}
Destructivedelete_list
DELETE /lists/:list_id

Delete a list

DESTRUCTIVE: delete a list and its memberships. The contacts themselves are kept. Fails with 409 while a broadcast to the list is sending. Part of Campaigns.

パラメータ型必須説明
list_idstringはいList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_list",
  "arguments": {
    "list_id": "lst_123"
  }
}
Changes stateadd_list_contacts
POST /lists/:list_id/contacts

Add contacts to a list

Campaigns: Add up to 500 existing contacts to a list by ID or email. Subscribed contacts join subscribed; others join in their current state. Unknown references come back in notFound.

パラメータ型必須説明
list_idstringはいList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idsstring[]いいえContact IDs (ct_…). (0–500 items)
emailsstring[]いいえContact email addresses. (0–500 items)
Returns{listId, added, notFound, list}.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "add_list_contacts",
  "arguments": {
    "list_id": "lst_123",
    "emails": [
      "ada@example.net"
    ]
  }
}
Destructiveremove_list_contact
DELETE /lists/:list_id/contacts/:contact_id

Remove a contact from a list

DESTRUCTIVE: remove one contact from a list. The contact and its status are kept. Part of Campaigns.

パラメータ型必須説明
list_idstringはいList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idstringはいContact ID (starts with ct_) or the contact's email address. (max 320 chars)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "remove_list_contact",
  "arguments": {
    "list_id": "lst_123",
    "contact_id": "ct_123"
  }
}
Read-onlylist_broadcasts
GET /broadcasts

List broadcasts

Campaigns: Newest-first broadcasts with their status. Paginated: the result includes pagination.

パラメータ型必須説明
statusstringいいえOnly broadcasts with this status. (one of draft, sending, sent, cancelled, failed)
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [broadcasts], count, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_broadcasts",
  "arguments": {}
}
Changes statecreate_broadcast
POST /broadcasts

Create a broadcast draft

Campaigns: Create a draft broadcast to one list. Content is html and/or text, markdown, a block document in content, or a published hosted template. Raw content supports merge tags: {{first_name}}, {{name}}, {{email}}, {{fields.plan}}, with fallbacks like {{first_name | there}}. audience narrows it to a segment and/or a number of people (most engaged first with order: engaged); tracking turns open and click tracking off; web publishes it on the list's newsletter site once sent. Nothing is sent until send_broadcast or schedule_broadcast; run check_broadcast and send_broadcast_test first.

パラメータ型必須説明
namestringいいえInternal name. Defaults to the subject. (max 200 chars)
list_idstringいいえThe list to send to (lst_…).
fromstringいいえSender on a verified domain, e.g. Acme <news@example.com>. (max 320 chars)
reply_tostringいいえReply-To address. (max 320 chars)
subjectstringいいえSubject line; merge tags allowed. (max 998 chars)
preview_textstringいいえInbox preview text shown after the subject. (max 300 chars)
htmlstringいいえHTML body; merge tags allowed and escaped.
textstringいいえPlain-text body; merge tags allowed.
templateobjectいいえA published hosted template instead of subject/html/text. Template variables are filled from the contact's name, email, and fields.
template.idstringいいえ
template.keystringいいえ
template.version_idstringいいえ
markdownstringいいえMarkdown body instead of html: converted to a block document and rendered with the workspace design (get_newsletter_settings). Merge tags allowed. Not combinable with html or content. (max 1000000 chars)
contentobject,nullいいえBlock document ({"type": "doc", "content": [...]}, the dashboard editor's format: paragraph, heading, bulletList, orderedList, blockquote, image, button, callout, horizontalRule, codeBlock). Rendered with the workspace design unless html is also sent.
editorstringいいえWhich editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks)
audienceobjectいいえWho gets it, within the list. Subscribed, non-dormant members only.
audience.segment_idstring,nullいいえOnly list members matching this segment (seg_…), or null for the whole list.
audience.orderstringいいえWith a limit: signup (default) or engaged (most engaged first). (one of signup, engaged)
audience.limitinteger,nullいいえSend to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000)
trackingobjectいいえOpen and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email.
tracking.opensbooleanいいえAdd an open pixel.
tracking.clicksbooleanいいえRewrite links to signed SendHQ redirects (the unsubscribe link never is).
webobjectいいえPublish this issue on the list's newsletter site (see create_list site) once it is sent.
web.enabledbooleanいいえPublish it.
web.slugstring,nullいいえIssue address; defaults to the subject. (max 100 chars)
web.pinnedbooleanいいえKeep it at the top of the site.
ReturnsThe draft broadcast.
tools/callのparamsの例
{
  "name": "create_broadcast",
  "arguments": {
    "list_id": "lst_123",
    "from": "news@example.com",
    "subject": "October update",
    "markdown": "Hi {{first_name | there}}, here's what shipped.",
    "audience": {
      "order": "engaged",
      "limit": 1000
    }
  }
}
Read-onlyget_broadcast
GET /broadcasts/:broadcast_id

Get a broadcast

Campaigns: One broadcast with its content and, once sending, recipient totals (queued, sending, sent, held, skipped, failed). While a limit or reputation pause holds delivery, lastError explains why and nextAttemptAt says when it resumes.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe broadcast.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Changes stateupdate_broadcast
PATCH /broadcasts/:broadcast_id

Edit a draft broadcast

Campaigns: Change any field of an unscheduled draft broadcast (content, audience, tracking, web). A scheduled draft must be unscheduled first (unschedule_broadcast); sent or sending broadcasts cannot be edited.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
namestringいいえInternal name. (max 200 chars)
list_idstringいいえThe list to send to.
fromstringいいえSender on a verified domain. (max 320 chars)
reply_tostringいいえReply-To address. (max 320 chars)
subjectstringいいえ件名。(最大998文字)
preview_textstringいいえInbox preview text. (max 300 chars)
htmlstringいいえHTMLの本文。
textstringいいえプレーンテキストの本文。
templateobject,nullいいえA published hosted template, or null to remove it.
markdownstringいいえMarkdown body instead of html: converted to a block document and rendered with the workspace design (get_newsletter_settings). Merge tags allowed. Not combinable with html or content. (max 1000000 chars)
contentobject,nullいいえBlock document ({"type": "doc", "content": [...]}, the dashboard editor's format: paragraph, heading, bulletList, orderedList, blockquote, image, button, callout, horizontalRule, codeBlock). Rendered with the workspace design unless html is also sent.
editorstringいいえWhich editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks)
audienceobjectいいえWho gets it, within the list. Subscribed, non-dormant members only.
audience.segment_idstring,nullいいえOnly list members matching this segment (seg_…), or null for the whole list.
audience.orderstringいいえWith a limit: signup (default) or engaged (most engaged first). (one of signup, engaged)
audience.limitinteger,nullいいえSend to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000)
trackingobjectいいえOpen and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email.
tracking.opensbooleanいいえAdd an open pixel.
tracking.clicksbooleanいいえRewrite links to signed SendHQ redirects (the unsubscribe link never is).
webobjectいいえPublish this issue on the list's newsletter site (see create_list site) once it is sent.
web.enabledbooleanいいえPublish it.
web.slugstring,nullいいえIssue address; defaults to the subject. (max 100 chars)
web.pinnedbooleanいいえKeep it at the top of the site.
ReturnsThe updated draft.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "subject": "October product update"
  }
}
Destructivedelete_broadcast
DELETE /broadcasts/:broadcast_id

Delete a draft broadcast

DESTRUCTIVE: permanently delete a draft broadcast. Broadcasts that were sent cannot be deleted. Part of Campaigns.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast
POST /broadcasts/:broadcast_id/send

Send a broadcast

SENDS REAL EMAIL to the broadcast's audience: every subscribed, non-dormant member of its list, narrowed by its segment and limit. Only call it when the user asked to send this broadcast now. Each message goes through the normal checks (verified domain, marketing plan, suppressions, unsubscribes, reputation, daily and monthly limits) and carries one-click unsubscribe from this list; members that cannot be mailed are skipped. Each contact is sent at most once. Delivery continues in the background: poll get_broadcast for totals and get_broadcast_report for engagement. A scheduled broadcast fails with 409 until unscheduled. Unpaid workspaces (integration trial) can send only to the account email. Pass idempotency_key so a retry cannot start the send twice. Part of Campaigns.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
idempotency_keystringいいえIdempotency-Keyヘッダー(最大200文字)。このリクエストをまったく同じ内容で再試行する場合にのみ再利用してください。(最大200文字)
ReturnsThe broadcast with status sending and totals.
tools/callのparamsの例
{
  "name": "send_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "idempotency_key": "october-update"
  }
}
Destructivecancel_broadcast
POST /broadcasts/:broadcast_id/cancel

Cancel a broadcast

DESTRUCTIVE: stop a draft or sending broadcast for good. Recipients not yet sent are marked skipped; messages already handed to the provider are not recalled. Part of Campaigns.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe cancelled broadcast with totals.
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "cancel_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Read-onlylist_broadcast_recipients
GET /broadcasts/:broadcast_id/recipients

List broadcast recipients

Campaigns: Per-recipient outcomes and engagement of a broadcast: queued, sending, sent, held, skipped (with the reason), or failed (with the error), the inbox provider, delivered/opened/clicked/bounced/complained/unsubscribed times, and the email ID to inspect delivery events with list_email_events. Filter by outcome, by activity (who opened, clicked, did not open, ...), or by email. Opens are bot-filtered estimates, never proof of reading. Paginated.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
statusstringいいえOnly recipients with this outcome. (one of queued, sending, sent, held, skipped, failed)
activitystringいいえOnly recipients who did this. (one of opened, clicked, not_opened, not_delivered, bounced, complained, unsubscribed)
querystringいいえRecipient email contains this text. (max 200 chars)
includestringいいえlinks adds the links each recipient clicked (implied by activity: clicked). (one of links)
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [{contactId, email, status, skipReason, emailId, error, provider, deliveredAt, openedAt, clickedAt, opens, clicks, bouncedAt, complainedAt, unsubscribedAt, links?}], count, totals, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_broadcast_recipients",
  "arguments": {
    "broadcast_id": "bc_123",
    "status": "failed"
  }
}
Read-onlycheck_broadcast
GET /broadcasts/:broadcast_id/checks

Run a broadcast's pre-send checks

Campaigns: The review list shown before sending: sender verification, subject, preview text, content, audience size, size against Gmail's 102 KB clipping limit, postal address, merge tags without data or fallback, empty or shortened links, image descriptions, placeholder text, spam-prone wording, the trial's own-address rule, and whether a test was sent. ready is false while any check has level block; schedule_broadcast refuses then. Fix warn items or tell the user about them.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Returns{ready, checks: [{id, level: ok|warn|block, label, detail}], audience: {total, matching}}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "check_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast_test
POST /broadcasts/:broadcast_id/test

Send a broadcast test

SENDS REAL EMAIL: a copy of the draft marked [Test] to up to 5 addresses (default: the saved test recipients, or the account email), with merge tags filled from contact_id or a sample contact. Never goes to the list. Only send to addresses the user gave or owns. Limited to 100 test sends a day. Template broadcasts are tested with send_template_test. Part of Campaigns.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
tostring[]いいえTest recipients (up to 5). (1–5 items)
contact_idstringいいえFill merge tags from this contact (ct_…). (max 320 chars)
rememberbooleanいいえSave to as the default test recipients.
Returns{data: [{to, id, status: sent|failed, error?}]}.
tools/callのparamsの例
{
  "name": "send_broadcast_test",
  "arguments": {
    "broadcast_id": "bc_123",
    "to": [
      "owner@example.com"
    ]
  }
}
Sends real emailschedule_broadcast
POST /broadcasts/:broadcast_id/schedule

Schedule a broadcast

SENDS REAL EMAIL at scheduled_at to the broadcast's audience, with the same checks as send_broadcast. Only call it when the user asked to send this broadcast at that time. The pre-send checks run now (422 with checks if one blocks). It starts within about a minute of the time; if it can no longer send then, it returns to a draft with the reason in lastError. A scheduled draft cannot be edited until unschedule_broadcast. Part of Campaigns.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
scheduled_atstringはいWhen to send: ISO 8601 date-time with a timezone, at least a minute and at most a year ahead, e.g. 2026-11-10T09:00:00Z. (max 40 chars)
ReturnsThe broadcast with scheduledAt.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "schedule_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "scheduled_at": "2026-11-10T09:00:00Z"
  }
}
Changes stateunschedule_broadcast
POST /broadcasts/:broadcast_id/unschedule

Unschedule a broadcast

Campaigns: Return a scheduled broadcast to an editable draft so it does not send. Fails with 409 when it is not scheduled.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe draft broadcast.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "unschedule_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Changes stateduplicate_broadcast
POST /broadcasts/:broadcast_id/duplicate

Duplicate a broadcast

Campaigns: Copy any broadcast (draft, sent, or cancelled) into a new draft named <name> (copy) with the same list, sender, content, audience, and tracking settings. Nothing is sent.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe new draft broadcast.
tools/callのparamsの例
{
  "name": "duplicate_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast_to_more
POST /broadcasts/:broadcast_id/send-more

Send a broadcast to more people

SENDS REAL EMAIL: sends a sent or sending broadcast to up to limit more people in its audience who have not received it (the rest of a limited audience, or people who joined since), in its audience order. Only call it when the user asked for this. Same checks as send_broadcast; each contact still gets it at most once. Fails with 422 when everyone already got it. Pass idempotency_key so a retry cannot add people twice. Part of Campaigns.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
limitintegerはいHow many more people at most. (1–10000000)
idempotency_keystringいいえIdempotency-Keyヘッダー(最大200文字)。このリクエストをまったく同じ内容で再試行する場合にのみ再利用してください。(最大200文字)
Returns{added, broadcast}.
tools/callのparamsの例
{
  "name": "send_broadcast_to_more",
  "arguments": {
    "broadcast_id": "bc_123",
    "limit": 500,
    "idempotency_key": "october-update-more-1"
  }
}
Read-onlyget_broadcast_report
GET /broadcasts/:broadcast_id/report

Get a broadcast report

Campaigns: Engagement for a sending or sent broadcast: unique and total opens and clicks, bounces, complaints, and unsubscribes with rates in percent, the same per inbox provider, clicks per link, first opens and clicks by hour, and the average of the previous five broadcasts. Opens are estimates: automated requests (scanners, link previews, privacy prefetching) are counted only in machine. Never claim that a person read the email. Fails with 409 for a draft.

パラメータ型必須説明
broadcast_idstringはいBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Returns{stats: {sent, delivered, opened, clicked, bounced, complained, unsubscribed, opens, clicks, rates}, providers, links, timeline, average, machine, tracking, totals, remaining}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_broadcast_report",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Read-onlyget_newsletter_settings
GET /newsletter-settings

Get newsletter settings

Campaigns: The postal address added to every marketing email footer, the design (accent color, font, alignment) used for Markdown and block content, list cleanup settings, and default test recipients.

パラメータはありません。

Returns{postalAddress, design: {accentColor, font, align}, cleanup: {enabled, afterSends, quietDays, subject, body, from}, testRecipients}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_newsletter_settings",
  "arguments": {}
}
Changes stateupdate_newsletter_settings
PATCH /newsletter-settings

Update newsletter settings

Campaigns: Change the postal address (required in marketing email by CAN-SPAM and CASL), design, list cleanup, or default test recipients. Omitted keys keep their value. List cleanup is on by default and sends email automatically: a subscriber who got afterSends broadcasts in a row without opening or clicking and has been quiet for quietDays gets one "still want these?" email; a week later those who did not confirm become dormant (kept, but skipped by broadcasts). Confirm with the user before turning it on or changing its email.

パラメータ型必須説明
postal_addressstringいいえSender's postal address for the footer. Empty string removes it. (max 300 chars)
designobjectいいえRendering design for Markdown and block content.
design.accentColorstring,nullいいえHex color like #0a7d4f, or null for the default.
design.fontstringいいえFont family. (one of sans, serif, mono)
design.alignstringいいえText alignment. (one of left, center)
cleanupobjectいいえList cleanup of readers who stopped opening.
cleanup.enabledbooleanいいえTurn list cleanup on or off.
cleanup.afterSendsintegerいいえBroadcasts in a row without an open or click (3-50). (3–50)
cleanup.quietDaysintegerいいえDays without engagement (30-730). (30–730)
cleanup.subjectstring,nullいいえSubject of the cleanup email; merge tags allowed. (max 200 chars)
cleanup.bodystring,nullいいえBody text of the cleanup email. (max 2000 chars)
cleanup.fromstring,nullいいえSender on a verified domain. Defaults to the last sent broadcast's sender. (max 320 chars)
test_recipientsstring[]いいえDefault addresses for send_broadcast_test (up to 5). (0–5 items)
ReturnsThe updated settings.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_newsletter_settings",
  "arguments": {
    "postal_address": "Acme Inc., 1 Main St, Springfield",
    "design": {
      "accentColor": "#0a7d4f"
    }
  }
}
Read-onlyget_campaign_overview
GET /campaigns/overview

Get campaign overview

Campaigns: Subscriber growth and recent results for the last days (7-365, default 30): active, dormant, and pending subscribers, joined and left, a daily series, and the six latest broadcasts with open and click rates (bot-filtered estimates) and their average.

パラメータ型必須説明
daysintegerいいえWindow in days, 7 to 365. Defaults to 30. (7–365)
Returns{subscribers: {active, dormant, pending, joined, left}, series: [{day, subscribers, joined, left}], recent: [{id, name, subject, status, startedAt, sent, openRate, clickRate}], averages}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_campaign_overview",
  "arguments": {
    "days": 30
  }
}
Read-onlylist_uploaded_images
GET /uploads/images

List uploaded images

Campaigns: The workspace's 60 most recent editor image uploads with their public URLs (https://sendhq.cc/i/<id>), to reuse in broadcast HTML, Markdown, or image blocks. Uploading needs the dashboard or the REST API (raw image body). Paginated.

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [{id, url, width, height, size, filename, createdAt}], pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_uploaded_images",
  "arguments": {}
}

Automations, events, and sending limits

Sends real emailtrack_event
POST /events

Record something a contact did

SENDS REAL EMAIL later, when an automation is listening: the contact enters every automation that is on and starts on this event, and that automation then emails them on its schedule, within the workspace's sending limits and hours. Only record what the person really did. In order: the contact changes in contact and the event are saved; open enrolments whose automation names the event as its goal end as converted, and ones that list it as a stop event end; then the contact enters the automations that start on it, unless already in them or reentry forbids it. A contact that is unsubscribed, bounced, or complained is recorded and can leave automations but never enters one. A new contact needs contact.consent_basis. Pass dedupe_key so a retry changes nothing and returns the first result. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
emailstringはいThe contact's email address. (max 320 chars)
eventstringはいWhat they did: a lowercase letter, then a-z, 0-9, and _ (e.g. checkout_started). Names starting email. are reserved. (max 64 chars)
propertiesobjectいいえUp to 50 values (string, number, or boolean; strings are cut at 500 characters), e.g. {"plan": "pro"}. Usable in the automation's emails as merge tags such as {{ plan }}. The names email, name, first_name, last_name, and fields are reserved.
occurred_atstringいいえWhen it happened, ISO 8601 with a time zone. Defaults to now; may not be in the future. The automation's emails are timed from it. (max 40 chars)
dedupe_keystringいいえStable ID for this event (max 200 chars). A second call with the same key records nothing and returns the first result. (max 200 chars)
contactobjectいいえChanges to the contact, applied with the event.
contact.namestringいいえDisplay name. (max 200 chars)
contact.fieldsobjectいいえCustom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
contact.timezonestringいいえIANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
contact.localestringいいえLanguage tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
contact.consent_basisstringいいえHow this person agreed to receive your email, e.g. Created an account on acme.com and accepted product emails. Required when the email is not a contact yet. 10-500 characters. (max 500 chars)
Returns{id, contact_id, started: [automation keys the contact entered], ended: [automation keys the contact left]}.
tools/callのparamsの例
{
  "name": "track_event",
  "arguments": {
    "email": "ada@example.net",
    "event": "checkout_started",
    "properties": {
      "plan": "pro"
    },
    "dedupe_key": "checkout_8f3a"
  }
}
Read-onlylist_automations
GET /automations

List automations

Automations: Every automation in priority order with its status (draft, on, or off), how many emails it has, and totals for the last 30 days (entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held). held counts each time an email was made to wait by the sending limits, the sending hours, or the automation's daily cap. Each automation carries domain, the domain of its from_address (null while it has no sender). domain narrows the list to the automations that send from one domain (none: those with no sender yet); domains always lists every sender domain of the workspace, in alphabetical order, with how many automations each has. Email bodies are not included; use get_automation. For other date ranges and daily numbers use get_automation_report. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
domainstringいいえOnly the automations that send from this domain: the exact domain of their from_address (e.g. example.com), or none for automations with no sender yet. (max 253 chars)
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [{id, key, name, domain, audience_label, goal_label, status, entry, exit_rules, position, settings, from_name, from_address, reply_to, switched_on_at, created_at, updated_at} plus steps_count and totals], count, domains: [{domain, count}], pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_automations",
  "arguments": {
    "domain": "example.com"
  }
}
Read-onlyget_automation
GET /automations/:automation_key

Get an automation

Automations: One automation with its emails in order and their language versions, how many people are in it now, and overlap: the other automations that are on and currently have the same people in them, with goes_first true for one that ranks above this automation (the shared people get its emails first and wait in this one). to_fill lists what must still be filled in before it can be turned on: placeholders of the template library left in its emails, and workspace names they print that are blank. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
ReturnsThe automation (with domain, the domain of its from_address, or null) with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), enrollments {active, waiting}, overlap [{key, name, contacts, position, goes_first}], merge_fields [{key, label}]: the merge tags its emails print, in plain words, and to_fill [{id, position, locale, where, placeholder, key, message}].
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Changes statecreate_automation
POST /automations

Create an automation

Automations: Create a timed sequence of emails for one kind of person, as a draft. To start from a ready-made email instead (welcome, onboarding, trial, abandoned checkout, failed payment, winback and more), use use_automation_template. Nothing is sent until set_automation_status turns it on. key is its address and cannot be changed. entry says how people enter, exit_rules when they leave, and steps are the emails, each due offset_seconds after the person entered. from_address must be on a verified domain. Fails with 409 when the key is taken. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
keystringはいAddress of the automation: 1-63 characters of a-z, 0-9, and - (e.g. checkout-recovery). (max 63 chars)
namestringはいName shown in the dashboard. (max 200 chars)
audience_labelstringいいえWho this is for, in plain words, e.g. Started checkout and left. (max 200 chars)
goal_labelstringいいえWhat converting means, in a word or two, e.g. paid. (max 80 chars)
entryobjectいいえHow people enter. {type: "event", event} starts on an event recorded with track_event; {type: "manual"} only through enroll_contact. bucket (with segment_id) and date_field (with field) are stored, but nobody enters through them automatically yet. reentry: never (default) or after_end.
entry.typestringはいEntry type. (one of event, bucket, date_field, manual)
entry.eventstringいいえEvent name for an event entry, e.g. checkout_started.
entry.segment_idstringいいえSegment ID (seg_…) for a bucket entry. (max 128 chars)
entry.fieldstringいいえContact field key for a date_field entry. (max 40 chars)
entry.reentrystringいいえWhether someone who finished may enter again. (one of never, after_end)
exit_rulesobjectいいえWhen people leave. goal_event ends the enrolment as converted and credits the latest email sent within attribution_days before it. Each of stop_events ends it without a conversion. An automation with no goal must say so with no_goal: true. Sent whole: it replaces the current rules.
exit_rules.goal_eventstring,nullいいえEvent that counts as converting, e.g. payment_completed.
exit_rules.no_goalbooleanいいえTrue when this automation deliberately has no goal.
exit_rules.stop_eventsstring[]いいえEvents that take a person out, e.g. ["account_closed"]. (0–20 items)
exit_rules.attribution_daysintegerいいえDays before the goal within which an email earns the conversion. Default 14. (1–90)
settingsobjectいいえPer-automation settings. Omitted keys keep their value.
settings.exempt_from_holdbooleanいいえSkip the workspace's per-person limits (max_emails and min_gap_hours) for this automation. The sending hours still apply, and its emails still count toward the limits of other automations.
settings.daily_send_capinteger,nullいいえAt most this many emails a day from this automation, counted by the day of the workspace's default_timezone; emails over it wait until the next day. null for no cap. (1–…)
settings.daily_entry_capinteger,nullいいえStored for bucket entries, which are not started automatically yet. It does not limit people entering by event or through enroll_contact. null for no cap. (1–…)
settings.holdout_pctnumberいいえPercent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100)
settings.stale_daysintegerいいえAn email more than this many days overdue is skipped instead of sent late. Default 4. (1–365)
settings.resume_after_daysintegerいいえHow long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365)
positionintegerいいえPriority. While one person is in several automations that are on, only the one with the lowest position emails them; the others wait and resume resume_after_days after it ends. (0–100000)
from_namestringいいえSender display name, e.g. Acme. (max 120 chars)
from_addressstringいいえSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringいいえReply-To address. (max 320 chars)
stepsobject[]いいえThe emails, in order. position defaults to the place in this list. (0–50 items)
steps[].positionintegerいいえPosition of the email in the automation, 1 to 50. (1–50)
steps[].subjectstringいいえSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
steps[].preheaderstringいいえInbox preview line. (max 300 chars)
steps[].contentobjectいいえBlock document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html.
steps[].htmlstringいいえHTML body. The unsubscribe footer is added automatically.
steps[].textstringいいえプレーンテキストの本文。
steps[].editorstringいいえHow the email is made: blocks (the dashboard's writing editor, the default), html (your own HTML) or design (the dashboard's drag-and-drop builder). Only the builder makes a design; to send a designed email yourself, send html with editor html. (one of blocks, html, design)
steps[].offset_secondsintegerいいえWhen the email is due, in seconds after the moment the person entered (3600 = one hour, 86400 = one day). May be negative for emails that lead up to a date. When several emails are due at once, only the latest is sent and the earlier ones are skipped. (-31622400–31622400)
steps[].skip_if_emptystring[]いいえMerge keys, e.g. ["fields.plan"]. The email is skipped for a contact where any of them is blank, 0, or false. (0–20 items)
steps[].ignore_send_windowbooleanいいえSend as soon as it is due, outside the workspace's sending hours too. The per-person limits still apply.
ReturnsThe automation with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), enrollments {active, waiting}, and overlap [{key, name, contacts}].
tools/callのparamsの例
{
  "name": "create_automation",
  "arguments": {
    "key": "checkout-recovery",
    "name": "Checkout recovery",
    "audience_label": "Started checkout and left",
    "goal_label": "paid",
    "from_name": "Acme",
    "from_address": "hello@example.com",
    "entry": {
      "type": "event",
      "event": "checkout_started"
    },
    "exit_rules": {
      "goal_event": "payment_completed"
    },
    "steps": [
      {
        "offset_seconds": 3600,
        "subject": "Still thinking it over, {{ first_name | there }}?",
        "html": "<p>Your cart is waiting.</p>"
      }
    ]
  }
}
Changes stateupdate_automation
PATCH /automations/:automation_key

Edit an automation

Automations: Change an automation's name, labels, entry, exit rules, sender, or priority. settings are merged; entry and exit_rules replace the current ones. The key and the status cannot be changed here (use set_automation_status), and emails are changed with set_automation_step. If the automation is on, the change applies to people in it now, and an edit that would leave it unable to send is refused with 422 automation_not_ready. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
namestringいいえName shown in the dashboard. (max 200 chars)
audience_labelstringいいえWho this is for, in plain words, e.g. Started checkout and left. (max 200 chars)
goal_labelstringいいえWhat converting means, in a word or two, e.g. paid. (max 80 chars)
entryobjectいいえHow people enter. {type: "event", event} starts on an event recorded with track_event; {type: "manual"} only through enroll_contact. bucket (with segment_id) and date_field (with field) are stored, but nobody enters through them automatically yet. reentry: never (default) or after_end.
entry.typestringはいEntry type. (one of event, bucket, date_field, manual)
entry.eventstringいいえEvent name for an event entry, e.g. checkout_started.
entry.segment_idstringいいえSegment ID (seg_…) for a bucket entry. (max 128 chars)
entry.fieldstringいいえContact field key for a date_field entry. (max 40 chars)
entry.reentrystringいいえWhether someone who finished may enter again. (one of never, after_end)
exit_rulesobjectいいえWhen people leave. goal_event ends the enrolment as converted and credits the latest email sent within attribution_days before it. Each of stop_events ends it without a conversion. An automation with no goal must say so with no_goal: true. Sent whole: it replaces the current rules.
exit_rules.goal_eventstring,nullいいえEvent that counts as converting, e.g. payment_completed.
exit_rules.no_goalbooleanいいえTrue when this automation deliberately has no goal.
exit_rules.stop_eventsstring[]いいえEvents that take a person out, e.g. ["account_closed"]. (0–20 items)
exit_rules.attribution_daysintegerいいえDays before the goal within which an email earns the conversion. Default 14. (1–90)
settingsobjectいいえPer-automation settings. Omitted keys keep their value.
settings.exempt_from_holdbooleanいいえSkip the workspace's per-person limits (max_emails and min_gap_hours) for this automation. The sending hours still apply, and its emails still count toward the limits of other automations.
settings.daily_send_capinteger,nullいいえAt most this many emails a day from this automation, counted by the day of the workspace's default_timezone; emails over it wait until the next day. null for no cap. (1–…)
settings.daily_entry_capinteger,nullいいえStored for bucket entries, which are not started automatically yet. It does not limit people entering by event or through enroll_contact. null for no cap. (1–…)
settings.holdout_pctnumberいいえPercent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100)
settings.stale_daysintegerいいえAn email more than this many days overdue is skipped instead of sent late. Default 4. (1–365)
settings.resume_after_daysintegerいいえHow long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365)
positionintegerいいえPriority. While one person is in several automations that are on, only the one with the lowest position emails them; the others wait and resume resume_after_days after it ends. (0–100000)
from_namestringいいえSender display name, e.g. Acme. (max 120 chars)
from_addressstringいいえSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringいいえReply-To address. (max 320 chars)
ReturnsThe automation with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), enrollments {active, waiting}, and overlap [{key, name, contacts}].
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_automation",
  "arguments": {
    "automation_key": "checkout-recovery",
    "name": "Checkout recovery",
    "settings": {
      "holdout_pct": 10
    }
  }
}
Destructivedelete_automation
DELETE /automations/:automation_key

Delete an automation

DESTRUCTIVE: permanently delete an automation with its emails, language versions, enrolments, send records, and statistics. Only a draft or switched-off automation that nobody is currently in can be deleted; otherwise it fails with 409. Confirm with the user first. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Changes stateset_automation_step
PUT /automations/:automation_key/steps/:position

Create or change an email of an automation

Automations: Create the email at position, or change the fields you pass on the one that is there; fields left out keep their value. If the automation is on, people who have not received this email yet get the new version, so confirm the wording with the user. An existing email keeps its ID: people who already received it are not sent it again. With template, the email becomes that template of the library (see list_automation_templates): its subject, preview text and content replace the email's and its language versions are removed. While the automation is on, an email must keep a subject and content, and may not hold a placeholder of the template library such as [First step] or print a workspace name that is blank (422 automation_not_ready with problems). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerはいPosition of the email in the automation, 1 to 50. (1–50)
templatestringいいえId of a template of the library, e.g. welcome-note (not a set). The email becomes that template; other fields passed here are applied on top. The email's wait is not the template's: pass offset_seconds. (max 63 chars)
subjectstringいいえSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstringいいえInbox preview line. (max 300 chars)
contentobjectいいえBlock document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html.
htmlstringいいえHTML body. The unsubscribe footer is added automatically.
textstringいいえプレーンテキストの本文。
editorstringいいえHow the email is made: blocks (the dashboard's writing editor, the default), html (your own HTML) or design (the dashboard's drag-and-drop builder). Only the builder makes a design; to send a designed email yourself, send html with editor html. (one of blocks, html, design)
offset_secondsintegerいいえWhen the email is due, in seconds after the moment the person entered (3600 = one hour, 86400 = one day). May be negative for emails that lead up to a date. When several emails are due at once, only the latest is sent and the earlier ones are skipped. (-31622400–31622400)
skip_if_emptystring[]いいえMerge keys, e.g. ["fields.plan"]. The email is skipped for a contact where any of them is blank, 0, or false. (0–20 items)
ignore_send_windowbooleanいいえSend as soon as it is due, outside the workspace's sending hours too. The per-person limits still apply.
ReturnsThe email: {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "set_automation_step",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 2,
    "offset_seconds": 86400,
    "subject": "Your cart is still here",
    "html": "<p>Pick up where you left off.</p>"
  }
}
Destructivedelete_automation_step
DELETE /automations/:automation_key/steps/:position

Remove an email from an automation

DESTRUCTIVE: remove the email at position from an automation. It is no longer sent or listed; records of who already received it are kept. While the automation is on, its only email cannot be removed (409). Confirm with the user first. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerはいPosition of the email in the automation, 1 to 50. (1–50)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_automation_step",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 3
  }
}
Changes stateset_automation_step_variant
PUT /automations/:automation_key/steps/:position/variants/:locale

Create or change a language version of an email

Automations: Save the version of one email for contacts whose locale is this language tag (e.g. fr); a contact with a regional locale such as pt-br gets the pt version when there is no pt-br one. Fields left out keep their value. A version without a body uses the email's own body, and a blank subject or preheader falls back to the email's. Contacts without a matching version get the email as written. If the automation is on, matching contacts who have not received this email yet get this version. While the automation is on, a version may not hold a placeholder of the template library or print a workspace name that is blank (422 automation_not_ready). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerはいPosition of the email in the automation, 1 to 50. (1–50)
localestringはいLanguage tag of the version, e.g. fr or pt-br. (max 35 chars)
subjectstringいいえSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstringいいえInbox preview line. (max 300 chars)
contentobjectいいえBlock document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html.
htmlstringいいえHTML body. The unsubscribe footer is added automatically.
textstringいいえプレーンテキストの本文。
Returns{locale, subject, preheader, content, html, text, updated_at}.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "set_automation_step_variant",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 1,
    "locale": "fr",
    "subject": "Vous hésitez encore ?",
    "html": "<p>Votre panier vous attend.</p>"
  }
}
Sends real emailset_automation_status
POST /automations/:automation_key/status

Turn an automation on or off

SENDS REAL EMAIL when status is on: from then on, everyone who enters the automation is emailed on its schedule, within the workspace's sending limits and hours (get_sending_limits), and people already in it continue. Use preview_automation to see who would get which email. Only turn it on when the user asked for this automation to start. Turning on checks an entry, a goal or exit_rules.no_goal, at least one email with a subject and content, no placeholder of the template library such as [First step] or [Link to plans] left in any email (subject, preview text, body, or a link's address), and no blank workspace name that an email prints (422 automation_not_ready with problems, which names each email and detail; get_automation lists the same under to_fill), a sender on a verified domain (403), and an active subscription (402). off stops new entries and sending; people in it stay and continue if it is turned on again, except that an email more than stale_days overdue by then is skipped. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
statusstringはいon to start sending, off to stop. (one of on, off)
ReturnsThe automation: {id, key, name, domain, audience_label, goal_label, status, entry, exit_rules, position, settings, from_name, from_address, reply_to, switched_on_at, created_at, updated_at}.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "set_automation_status",
  "arguments": {
    "automation_key": "checkout-recovery",
    "status": "off"
  }
}
Sends real emailsend_automation_test_email
POST /automations/:automation_key/steps/:position/test

Send one automation email to yourself as a test

SENDS REAL EMAIL: one email of an automation, marked [Test], to the account's own address (get_account -> user.email) and nowhere else; a recipient cannot be given. It is the email as the automation would send it (the language version for locale, the same sender, unsubscribe footer and checks), with stand-in values for its merge tags; sample replaces any of them. A test is not part of the automation: nobody is enrolled, it is in no report, it counts toward nobody's per-person sending limits, it is not tracked, and the automation does not have to be on. It counts toward the workspace's own sending allowance. With dry_run: true nothing is sent and the result is the email as the test would deliver it, with locales and the sample values used. Fails with 422 automation_not_ready when the automation has no sender or the email has no subject or content, and 429 test_limit_reached after 100 test emails in 24 hours. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerはいPosition of the email in the automation, 1 to 50. (1–50)
localestringいいえSend the language version a contact with this language would get (such as fr or pt-br). Omit for the email as written. (max 35 chars)
sampleobjectいいえValues to print for merge tags, by key, in place of the stand-ins (first_name is Alex, and so on). email, product_name, and sender_name cannot be set.
dry_runbooleanいいえSend nothing; return the email as the test would deliver it.
Returns{to, position, locale, subject, id: em_…, status: sent|held}. With dry_run: {dry_run: true, to, from, position, locale, locales, subject, preheader, html, text, sample: [{key, label, value}]}.
tools/callのparamsの例
{
  "name": "send_automation_test_email",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 1
  }
}
Sends real emailsend_automation_test
POST /automations/:automation_key/test

Send every email of an automation to yourself as tests

SENDS REAL EMAIL: every email of an automation, in order, marked [Test 1 of 3], [Test 2 of 3] and so on, to the account's own address (get_account -> user.email) and nowhere else, without waiting for the emails' delays. Rendering, footer, checks and stand-in values are as in send_automation_test_email. A test is not part of the automation: nobody is enrolled, it is in no report, it counts toward nobody's per-person sending limits, it is not tracked, and the automation does not have to be on. It counts toward the workspace's own sending allowance. Nothing is sent unless everything can be: a sender, a subject and content on every email (422 automation_not_ready with problems), and room for all of them under 100 test emails in 24 hours (429 test_limit_reached). If a send is refused after others went out, the rest are not tried and each email's outcome is returned. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
localestringいいえSend the language version a contact with this language would get (such as fr or pt-br). Omit for the email as written. (max 35 chars)
sampleobjectいいえValues to print for merge tags, by key, in place of the stand-ins (first_name is Alex, and so on). email, product_name, and sender_name cannot be set.
Returns{to, data: [{position, locale, subject, id: em_…, status: sent|held|failed, error?}], count, sent, failed, not_sent}.
tools/callのparamsの例
{
  "name": "send_automation_test",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Sends real emailenroll_contact
POST /automations/:automation_key/enroll

Add a contact to an automation

SENDS REAL EMAIL on the automation's schedule: starts the automation for one existing, subscribed contact, counting from anchor_at (now by default). Only call it when the user asked for this person to get this sequence. The automation must be on (409 automation_not_on). Fails with 404 when the email is not a contact (add it with upsert_contact), 422 when the contact cannot be mailed, and 409 when the contact is already in it or went through it before and re-entry is not allowed. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstringはいEmail address of an existing contact. (max 320 chars)
propertiesobjectいいえUp to 50 values (string, number, or boolean; strings are cut at 500 characters), e.g. {"plan": "pro"}. Usable in the automation's emails as merge tags such as {{ plan }}. The names email, name, first_name, last_name, and fields are reserved.
anchor_atstringいいえThe moment the emails' offsets count from, ISO 8601 with a time zone. Defaults to now; may lie ahead for emails that lead up to a date. (max 40 chars)
ReturnsThe enrolment: {id, automation_key, contact_id, status, source, is_holdout, anchor_at, entered_at, next_due_at, exit_reason, ended_at, converted_at}.
tools/callのparamsの例
{
  "name": "enroll_contact",
  "arguments": {
    "automation_key": "checkout-recovery",
    "email": "ada@example.net",
    "properties": {
      "plan": "pro"
    }
  }
}
Changes stateexit_contact
POST /automations/:automation_key/exit

Take a contact out of an automation

Automations: End a contact's open enrolment in one automation, so no further emails of it are sent to them. Other automations and broadcasts are not affected, and the contact stays subscribed. Fails with 404 when the contact is not in it. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstringはいEmail address of the contact. (max 320 chars)
reasonstringいいえWhy, for the record (max 200 chars). Defaults to manual. (max 200 chars)
ReturnsThe ended enrolment: {id, automation_key, contact_id, status, source, is_holdout, anchor_at, entered_at, next_due_at, exit_reason, ended_at, converted_at}.
tools/callのparamsの例
{
  "name": "exit_contact",
  "arguments": {
    "automation_key": "checkout-recovery",
    "email": "ada@example.net",
    "reason": "Asked support to stop"
  }
}
Read-onlypreview_automation
GET /automations/:automation_key/preview

Preview what an automation would send now

Automations: A dry run. For the people in the automation now, in the order they come due, what would happen if each were evaluated at this moment. outcome is send (the email in step would go out), scheduled (nothing is due before until), held (the email waits until until; reason is limit_cap, limit_gap, window, or daily_cap), waiting (behind the higher-priority automation in behind), skip (reason is stale, empty_field, or holdout), exit (the contact can no longer be mailed and would leave), complete, blocked (automation_off or subscription_required), or in_progress. Read-only: nothing is sent or changed. Use it before set_automation_status, or after changing limits, to see who gets which email. It applies the automation's own rules and does not foresee a refusal only a real send meets, such as the workspace's daily sending limit or a paused sender. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{automation_key, status, evaluated_at, data: [{enrollment_id, contact_id, email, status, next_due_at, outcome, reason, until, step: {position, subject, locale}, behind: {key, name}, superseded}], count, counts, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "preview_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Read-onlyget_automations_overview
GET /automations/overview

Get results across all automations

Automations: What every automation of the workspace did in a date range (the last 30 days by default, at most 366 days): totals and one entry per day for people who entered, emails sent, delivered, opened, clicked, and converted (a goal event credited to an email), plus bounces, complaints, unsubscribes, and held (emails made to wait by a limit). Days on which nothing happened are in the series with zeros. domain narrows it to the automations that send from one domain (none: those with no sender yet). Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
fromstringいいえFirst day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostringいいえLast day of the report as a UTC date (YYYY-MM-DD), inclusive.
domainstringいいえOnly the automations that send from this domain: the exact domain of their from_address (e.g. example.com), or none for automations with no sender yet. (max 253 chars)
Returns{from, to, totals: {entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}, series: [{day, entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}]}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_automations_overview",
  "arguments": {
    "from": "2026-10-20",
    "to": "2026-11-18"
  }
}
Read-onlyget_automation_report
GET /automations/:automation_key/report

Get the results of one automation

Automations: The results of one automation in a date range (the last 30 days by default, at most 366 days): the same totals and daily series as get_automations_overview, and steps, one row per email with what it sent and what came of it. An email that was removed is listed with archived: true while it still has numbers in the range. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
fromstringいいえFirst day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostringいいえLast day of the report as a UTC date (YYYY-MM-DD), inclusive.
Returns{automation: {key, name, status, goal_label}, from, to, totals, series: [{day, ...}], steps: [{step_id, position, subject, offset_seconds, archived, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}]}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_automation_report",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Read-onlylist_automation_people
GET /automations/:automation_key/people

List the people in an automation

Automations: One row per person who did did in an automation, most recent first: entered (the default: everyone who was ever in it), sent, delivered, opened, clicked, converted (their goal was credited to an email), bounced, unsubscribed, or waiting (waiting now behind a higher-priority automation). step narrows every filter except entered and waiting to one email. Each row has the contact's email and name, when they did it, their enrolment's status, and latest: the most recent thing that happened to them in the automation. counts says how many people each filter would list. Read one person's full history with get_automation_person. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
didstringいいえWhat the people did. Defaults to entered. (one of entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, waiting)
stepintegerいいえOnly this email of the automation, by its position. (1–50)
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{automation_key, did, step, data: [{contact_id, email, name, contact_status, enrollment_id, enrollment_status, at, latest: {did, at, step_position, reason}}], count, next_cursor, counts, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_automation_people",
  "arguments": {
    "automation_key": "checkout-recovery",
    "did": "clicked"
  }
}
Read-onlyget_automation_person
GET /automations/:automation_key/people/:contact_id

Get one person's history in an automation

Automations: Everything that happened to one contact in an automation: each enrolment and how it ended, each email with when it was sent, delivered, first opened, first clicked, bounced, complained about, or unsubscribed from, every open and click on it (machine: true marks an automated request, which is not counted), and the conversion with the email it was credited to. Fails with 404 for a contact that was never in the automation. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
automation_keystringはいAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
contact_idstringはいContact ID (starts with ct_) or the contact's email address. (max 320 chars)
Returns{automation_key, contact: {id, email, name, status}, enrollments: [{id, status, source, is_holdout, anchor_at, entered_at, next_due_at, last_sent_at, exit_reason, ended_at, converted_at, converted_send_id}], sends: [{id, enrollment_id, step_id, step_position, subject, status, skip_reason, locale, email_id, sent_at, delivered_at, opened_at, clicked_at, bounced_at, complained_at, unsubscribed_at, converted_at, open_count, machine_open_count, click_count, events: [{kind, machine, reason, position, url, country, at}]}], conversion: {enrollment_id, converted_at, goal_event, send_id, step_position}}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_automation_person",
  "arguments": {
    "automation_key": "checkout-recovery",
    "contact_id": "ct_123"
  }
}
Read-onlyget_sending_limits
GET /automation-settings

Get automation sending limits

Automations: How much automation email one person may get across every automation, and when: at most max_emails in any period_days, at least min_gap_hours apart, only between window_start and window_end (hours in the contact's time zone, or default_timezone) on weekdays (0 = Sunday to 6 = Saturday). An email that would break a limit is not dropped: it waits until the limits allow it. Also product_name and sender_name, available to every automation email as merge tags. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータはありません。

Returns{max_emails, period_days, min_gap_hours, window_start, window_end, weekdays, default_timezone, product_name, sender_name, updated_at}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_sending_limits",
  "arguments": {}
}
Changes stateupdate_sending_limits
PUT /automation-settings

Update automation sending limits

Automations: Change the workspace's per-person limits and sending hours for automation email. Omitted keys keep their value. Looser limits mean people can get more email, sooner: confirm with the user before raising max_emails, shortening min_gap_hours, or widening the hours. product_name and sender_name are the names the emails of the template library print; one that an automation that is on prints cannot be cleared (409 workspace_name_in_use). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
max_emailsintegerいいえMost automation emails one person may get in period_days. Default 2. (1–50)
period_daysintegerいいえThe period max_emails applies to, in days. Default 7. (1–90)
min_gap_hoursintegerいいえLeast time between two automation emails to one person, in hours. Default 44. (0–720)
window_startintegerいいえFirst hour of the day emails may go out, local time (0-23). Default 9. (0–23)
window_endintegerいいえHour sending stops, local time (1-24); must be later than window_start. Default 18. (1–24)
weekdaysinteger[]いいえDays emails may go out: 0 = Sunday to 6 = Saturday. Default [1, 2, 3, 4, 5]. (1–7 items)
default_timezonestringいいえIANA time zone used for contacts that have none, e.g. Europe/London. (max 64 chars)
product_namestringいいえYour product's name, for {{ product_name }}. (max 120 chars)
sender_namestringいいえWho the emails are from, for {{ sender_name }}. (max 120 chars)
ReturnsThe updated limits.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_sending_limits",
  "arguments": {
    "max_emails": 3,
    "min_gap_hours": 24,
    "default_timezone": "Europe/London"
  }
}
Read-onlylist_automation_templates
GET /automation-library

List automation templates

Automations: The template library: ready-made lifecycle emails to start an automation from instead of writing one. It covers welcome, onboarding tips, a nudge to finish setup (activation), trial ending and trial ended, abandoned checkout, failed payment (dunning), receipt, upgrade at a usage limit, feature announcement, review request, feedback score (NPS), cancellation survey, and winback for retention. Each template has a name, a one-line purpose, the goal it serves (group), its subject, the merge tags it prints, and start: the suggested entry event, the email's wait, and the goal event that ends the automation for a person. sets are templates that arrive together as one automation: three onboarding tips, trial ending then trial ended, and payment failed then a last notice. fill_in lists what only the user knows: placeholders in square brackets such as [First step] or [Link to plans], and the workspace names the email prints. Email bodies are not included; use get_automation_template. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{version, groups, data: [{id, kind, name, purpose, group, set, subject, preview_text, needs_consent, start: {entry, offset_seconds, goal_event, goal_label, skip_if_empty}, merge_keys, fill_in: [{kind, key, placeholder, label, example}]}], sets: [{id, kind, name, purpose, group, needs_consent, emails: [{template, offset_seconds}], start, merge_keys, fill_in}], count, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_automation_templates",
  "arguments": {}
}
Read-onlyget_automation_template
GET /automation-library/:template_id

Get an automation template

Automations: One template or one set of the template library, as the draft automation it would make: the suggested start and goal, what the user must fill in, and every email in order with its wait, subject, the email as a block document (content), and preview: the subject and text as this workspace would send them, with sample values for the merge tags. Read it to show the user a welcome, onboarding, trial, abandoned checkout, failed payment (dunning), upgrade, cancellation or winback email before using it. Placeholders such as [First step] are shown as written; a workspace name that is not set reads "Your product" or "Your name" in the preview. Then use_automation_template makes the draft, or set_automation_step with template loads one email into an existing automation. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
template_idstringはいId of a template or a set, as returned by list_automation_templates (e.g. welcome-note, checkout-not-finished, payment-failed-notices). (max 63 chars)
Returns{id, kind (email or set), name, purpose, group, set, needs_consent, start: {entry, goal_event, goal_label}, merge_keys, fill_in: [{kind, key, placeholder, label, example}], emails: [{template, name, offset_seconds, skip_if_empty, subject, preview_text, content, preview: {subject, preheader, text, html}}]}. preview.html is null.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_automation_template",
  "arguments": {
    "template_id": "welcome-note"
  }
}
Changes stateuse_automation_template
POST /automation-library/:template_id/use

Create an automation from a template

Automations: Create a draft automation from a template or a set of the library, ready-made: a welcome email, three onboarding tips, a nudge to finish setup, trial ending and trial ended, abandoned checkout, failed payment (dunning) notices, a receipt, an upgrade email at a usage limit, a feature announcement, a review request, a feedback score, a cancellation survey, or a winback for retention. The draft has the emails, the suggested entry event and the suggested goal. Nothing is sent: it stays a draft until set_automation_status turns it on, and that is refused while anything in to_fill is left. to_fill lists each placeholder to replace, by email (ask the user for the real words and links, then use set_automation_step), and each workspace name the emails print that is blank (product_name, sender_name: set with update_sending_limits). Make sure the entry event is one the workspace records (list_event_names); change the start with update_automation. from_address must be on a verified domain. Fails with 404 for an unknown template and 409 when key is taken. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
template_idstringはいId of a template or a set, as returned by list_automation_templates (e.g. welcome-note, checkout-not-finished, payment-failed-notices). (max 63 chars)
keystringいいえAddress of the new automation: 1-63 characters of a-z, 0-9, and -. Defaults to the template's id, with a number added when that is taken. (max 63 chars)
namestringいいえName shown in the dashboard. Defaults to the template's own name. (max 200 chars)
from_namestringいいえSender display name, e.g. Acme. (max 120 chars)
from_addressstringいいえSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringいいえReply-To address. (max 320 chars)
ReturnsThe new automation (status draft) with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), merge_fields [{key, label}], template, and to_fill [{id, position, locale, where, placeholder, key, message}]: what must be filled in before it can be turned on.
tools/callのparamsの例
{
  "name": "use_automation_template",
  "arguments": {
    "template_id": "welcome-note",
    "name": "Welcome",
    "from_name": "Dana from Acme",
    "from_address": "dana@example.com"
  }
}
Read-onlylist_events
GET /events

List what contacts did

Automations: The events recorded for the workspace, newest first: who (the contact's id, email, and name), what they did (the event name, and the same as words), when, its properties, where it came from (source.type: api for the workspace's own code, connection with the connection's name, upload for a spreadsheet, system for SendHQ itself), and effects: the automations it started, ended, or converted for that contact. Filter by contact (a contact ID or an email address), name (one event name), and from / to. With contact, the result also lists every automation that contact is or was in (enrollments). An event being recorded does not mean an email was sent: check the automation with list_automation_people. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
contactstringいいえOnly this contact: a contact ID or an email address. (max 320 chars)
namestringいいえOnly this event, e.g. checkout_started. See list_event_names. (max 64 chars)
fromstringいいえEvents from this UTC date (YYYY-MM-DD) or ISO 8601 date-time on. (max 40 chars)
tostringいいえEvents up to this UTC date (the whole day) or ISO 8601 date-time. (max 40 chars)
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [{id, contact: {id, email, name}, event, words, occurred_at, received_at, source: {type, label, connection_id}, properties, effects: [{did, automation_key, automation_name}]}], count, next_cursor, enrollments (with contact), pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_events",
  "arguments": {
    "name": "checkout_started",
    "from": "2026-11-01"
  }
}
Read-onlylist_event_names
GET /events/names

List the kinds of event recorded

Automations: Every distinct event name recorded in the last 30 days with how many times, the most frequent first, each with the name as words (checkout_started reads checkout started). Use it to see what the workspace is being told about before creating an automation that starts on an event. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [{event, words, count}], count, days, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_event_names",
  "arguments": {}
}
Read-onlylist_connections
GET /connections

List connections

Automations: The workspace's connections. A connection is a secret address another system posts to, such as a payment provider's webhook; what arrives is recorded as events, exactly as track_event records them. Each has its kind (stripe, dodo, or generic), whether it is enabled, whether a signing secret is set, the last four characters of its address, and last_delivery in plain words such as "Recorded 2 events" or "Refused: bad signature". The address and the signing secret are never returned here. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
Returns{data: [{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus last_delivery {id, at, result, reason, recorded, events, text, provider_event, email}], count, limit, pagination}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_connections",
  "arguments": {}
}
Read-onlyget_connection
GET /connections/:connection_id

Get a connection and its last deliveries

Automations: One connection with its last 50 deliveries, newest first: when each arrived, whether it was recorded, skipped, or refused and why (text says it in plain words), the sender's own event type, the names of the events recorded, and the contact's email address. Payloads are not stored. Use it to find out why something a provider sent did not show up. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
connection_idstringはいConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
Returns{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus last_delivery and deliveries: [{id, at, result, reason, recorded, events, text, provider_event, email}].
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_connection",
  "arguments": {
    "connection_id": "acn_123"
  }
}
Sends real emailcreate_connection
POST /connections

Create a connection

SENDS REAL EMAIL later, when an automation is listening: from the moment the address this returns is given to another system, everything that system posts is recorded as events without anyone looking, and a recorded event starts every automation that is on and starts on it. Only create one when the user asked to connect that system. Returns address once; it cannot be read again, so hand it to the user at once. kind is stripe or dodo (mapped for you: checkout_completed, checkout_abandoned, paid, payment_failed, subscription_started, subscription_renewed, subscription_cancelled, plan_changed) or generic with a mapping. consent_basis is recorded on every contact the connection creates. The provider's signing secret is set by a person in the dashboard or with the REST API, not here. A workspace may have 10 connections (409 connection_limit_reached). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
namestringはいWhat to call it, e.g. Stripe. (max 80 chars)
kindstringはいstripe, dodo, or generic. (one of generic, stripe, dodo)
consent_basisstringはいHow the people this connection tells you about agreed to receive your email, e.g. Bought a plan on acme.com and accepted product emails. Recorded on every contact it creates. 10-500 characters. (max 500 chars)
event_prefixstringいいえPut in front of every event name, e.g. stripe_. (max 32 chars)
enabledbooleanいいえDefaults to true. Pass false to create it switched off.
mappingobjectいいえFor a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name.
mapping.emailstringいいえWhere the contact's email address is. (max 120 chars)
mapping.eventstringいいえWhere the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars)
mapping.event_namestringいいえOne fixed event name, instead of event. (max 64 chars)
mapping.timestringいいえWhere the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars)
mapping.idstringいいえWhere a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars)
mapping.keepstring[]いいえThe fields to keep as event properties. Defaults to the top-level text, number, and boolean fields. (0–50 items)
Returns{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus address (shown once) and last_delivery: null.
tools/callのparamsの例
{
  "name": "create_connection",
  "arguments": {
    "name": "Stripe",
    "kind": "stripe",
    "consent_basis": "Bought a plan on acme.com and accepted product emails"
  }
}
Sends real emailupdate_connection
PATCH /connections/:connection_id

Change a connection or switch it on or off

SENDS REAL EMAIL later when enabled is set to true: what the connected system posts is recorded as events again, and a recorded event starts every automation that is on and starts on it. Only switch one on when the user asked. Also changes name, consent_basis, event_prefix, or a generic connection's mapping. While enabled is false the address answers 404 and records nothing. The kind cannot be changed. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
connection_idstringはいConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
namestringいいえA new name. (max 80 chars)
enabledbooleanいいえtrue: record what arrives. false: answer 404 and record nothing.
consent_basisstringいいえHow the people this connection tells you about agreed to receive your email, e.g. Bought a plan on acme.com and accepted product emails. Recorded on every contact it creates. 10-500 characters. (max 500 chars)
event_prefixstringいいえPut in front of every event name, e.g. stripe_. (max 32 chars)
mappingobjectいいえFor a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name.
mapping.emailstringいいえWhere the contact's email address is. (max 120 chars)
mapping.eventstringいいえWhere the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars)
mapping.event_namestringいいえOne fixed event name, instead of event. (max 64 chars)
mapping.timestringいいえWhere the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars)
mapping.idstringいいえWhere a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars)
mapping.keepstring[]いいえThe fields to keep as event properties. Defaults to the top-level text, number, and boolean fields. (0–50 items)
Returns{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at}.
アノテーションidempotentHint
tools/callのparamsの例
{
  "name": "update_connection",
  "arguments": {
    "connection_id": "acn_123",
    "enabled": false
  }
}
Destructivedelete_connection
DELETE /connections/:connection_id

Delete a connection

DESTRUCTIVE: permanently delete a connection with its delivery records. Its address stops working at once, so the system that posts to it starts getting 404 and nothing more is recorded from it. The events it already recorded stay. Confirm with the user first; to pause one instead, use update_connection with enabled: false. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

パラメータ型必須説明
connection_idstringはいConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
戻り値{ok: true}。
アノテーションdestructiveHint idempotentHint
tools/callのparamsの例
{
  "name": "delete_connection",
  "arguments": {
    "connection_id": "acn_123"
  }
}

アカウント、使用量、分析、キー

読み取り専用get_account
GET /account

アカウント、使用量、請求情報を取得する

アカウント所有者のメールアドレス、プラン/アクセスティア、当期の受信者配信数の使用量とクォータ、ドメインの使用数と上限、添付ファイルの転送量、レピュテーションのサマリー、サブスクリプションの状態、公開されているプラン、ワークスペースの各種件数。残りのクォータや、トライアルで配信できる相手(アカウントのメールアドレス)の確認に使います。

パラメータはありません。

戻り値{user: {email, …}, usage: {domainsUsed, domainLimit, recipientDeliveries, emailQuotaMonth, attachmentBytes, attachmentByteLimit, periodKey}, access: {tier, planCode}, reputation, infrastructure, billing: {status, subscriptions, …}, plans, workspace: {mailer, stats}}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_account",
  "arguments": {}
}
Read-onlyget_account_diagnostics
GET /account/diagnostics

Diagnose sending and receiving

One read that explains what is wrong with sending or receiving in this workspace: an issues list (unverified domains and missing DKIM records, inbound MX not ready, paused or throttled senders, quota or daily limit reached, trial restrictions, high bounce or complaint rates, failing webhooks), plan and usage against limits, each domain with its DKIM and inbound state, sending identities, 30-day deliverability and sender reputation, suppressions and unsubscribes, and the last 30 days of messages that were not sent (with reasons) plus bounce, complaint and reject events. Start here when a user asks why mail is not arriving. Never returns message bodies or secrets.

パラメータはありません。

Returns{generatedAt, windowDays, issues: [{severity, code, message}], plan: {tier, usage, sendingLimit}, domains: [{name, status, dkim: {required, verified, missing}, inbound}], sendingIdentities, inbound, deliverability: {sent, delivered, bounced, complained, rates, senders}, suppressions: {total, byReason, unsubscribes, recent}, failures: {notSent, recentNotSent, recentProviderEvents}, webhooks}.
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_account_diagnostics",
  "arguments": {}
}
読み取り専用get_analytics
GET /analytics

送信の分析データを取得する

過去7日、30日、90日間のダッシュボード分析:sent/received/delivered/bounced/blocked/opened/clicked/complaintの合計、日別のタイムライン、送信数の多いドメイン、件名の上位。

パラメータ型必須説明
daysintegerいいえ日数単位の期間:7、30(デフォルト)、90。(7、30、90のいずれか)
戻り値{window, days, metrics, timeline: [{day, sent, received}], domains, topContent}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_analytics",
  "arguments": {
    "days": 30
  }
}
読み取り専用list_api_keys
GET /keys

APIキーのメタデータを一覧表示する

APIキーの名前、秘密でないプレフィックス、最終使用日時を一覧表示します。読み取り専用:このMCPサーバーはキーの作成、ローテーション、失効ができません。それらは人間がダッシュボードで行います。ページネーションあり:結果にはpagination {offset, limit, returned, total?, has_more, next_offset}が含まれます。

パラメータ型必須説明
limitintegerいいえページサイズ。デフォルトは50です。(デフォルト50、1〜200)
offsetintegerいいえスキップするレコード数。前のページのpagination.next_offsetを使います。(デフォルト0、0〜…)
戻り値{data: [{id, name, prefix, lastUsedAt, createdAt}], count, pagination}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "list_api_keys",
  "arguments": {}
}
読み取り専用get_service_health
GET /health

SendHQサービスの稼働状況を確認する

SendHQ APIが稼働しているかどうかと、どのメールプロバイダーが有効かを確認します。有効なAPIキーは不要です。

パラメータはありません。

戻り値{ok, service, mailer}。
アノテーションreadOnlyHint idempotentHint
tools/callのparamsの例
{
  "name": "get_service_health",
  "arguments": {}
}

APIカバレッジ一覧

公開APIのすべての操作と、それに対応するツールです。ダッシュボードでできる操作のうちAPIがあるものはすべてカバーしています。以下の除外は意図的なものです。

エンドポイントツール備考
POST /emailssend_emailメールを1通送信する
POST /emails/batchsend_batch個別化したメッセージを最大100通送信する
GET /emailslist_emails送信済みメールと受信メールを一覧表示する
GET /emails/:idget_emailメールとその添付ファイルを取得する
PATCH /emails/:idmark_email既読、アーカイブ、迷惑メール、カテゴリ、重要度を更新する
POST /emails/:id/labelslabel_emailメールのラベルを追加・削除する
DELETE /emails/:iddelete_email保持されているメールを削除する
GET /emails/:id/eventslist_email_eventsメールの配信イベントを一覧表示する
GET /threads/:idget_thread会話を時系列順に取得する
GET /labelslist_labelsメッセージ数と振り分けルールを含めてラベルを一覧表示する
POST /labelscreate_labelラベルを作成する(自動振り分けルールも指定可能)
GET /labels/:idget_labelIDまたは名前でラベルを取得する
PATCH /labels/:idupdate_labelラベルの名前や色を変更する、またはバケットにする
DELETE /labels/:iddelete_labelメールを削除せずにラベルを削除する
POST /labels/:id/rulescreate_label_ruleラベルに自動振り分けルールを追加する
DELETE /labels/:id/rules/:rule_iddelete_label_rule自動振り分けルールを削除する
POST /draftscreate_draft作成画面用の下書きを作成する
GET /draftslist_drafts作成画面用の下書きを一覧表示する
GET /drafts/:idget_draft下書きと添付ファイルを取得する
PUT /drafts/:idupdate_draft下書きの内容を置き換える
DELETE /drafts/:iddelete_draft下書きを破棄する
POST /drafts/:id/attachmentsupload_attachment下書きに添付ファイルをアップロードする
GET /attachments/:iddownload_attachment非公開の添付ファイルをダウンロードする
DELETE /attachments/:iddelete_attachment非公開の添付ファイルを削除する
GET /sending-identitieslist_sending_identities検証済みの送信者IDを一覧表示する
GET /templateslist_templatesホスト型テンプレートを一覧表示する
POST /templatescreate_templateホスト型テンプレートを作成する
GET /templates/:idget_template下書き、リリース、使用状況を取得する
PUT /templates/:id/draftupdate_template_draftテンプレートの下書きを自動保存する
POST /templates/:id/draftcreate_template_draft公開済みリリースから新しい下書きを作成する
POST /templates/:id/renderrender_templateサーバーの出力をそのままレンダリングする
POST /templates/:id/testsend_template_testテスト用スナップショットを送信する
POST /templates/:id/publishpublish_template変更不可のテンプレートリリースを公開する
POST /templates/:id/archivearchive_templateテンプレートをアーカイブする
POST /templates/:id/restorerestore_templateアーカイブしたテンプレートを復元する
POST /domainsadd_domain送信ドメインを追加する
GET /domainslist_domainsドメインとキャッシュ済みのDNS状態を一覧表示する
GET /domains/:idget_domainドメインの設定詳細を取得する
POST /domains/:id/verifyverify_domainRefresh domain and DNS verification
POST /domains/:id/inbound/setupsetup_inboundProvision inbound receiving
POST /domains/:id/inbound/verifyverify_inbound受信用MXのルーティングを検証する
DELETE /domains/:iddelete_domainドメインを削除する
GET /dns/providerget_dns_provider権威DNSプロバイダーとレコードの相対ホストを検出する
GET /dns/domain-connect/connectget_domain_connect_linkワンクリックDNS設定用のDomain Connect同意リンクを作成する
POST /inboxescreate_inbox受信用アドレスを作成する
GET /inboxeslist_inboxes受信用アドレスを一覧表示する
GET /inboxes/:idget_inbox受信用アドレスを取得する
PATCH /inboxes/:idupdate_inboxインボックスの名前を変更する、有効化する、無効化する
PUT /inboxes/:id/forwardingset_inbox_forwardingインボックスの受信メールを別のアドレスに転送する
DELETE /inboxes/:iddelete_inboxメッセージを保持したままインボックスを削除する
GET /deliverability/statsdeliverability_stats過去30日間の配信統計を取得する
GET /deliverability/reputationlist_sender_reputation送信者IDごとのレピュテーションの状態を一覧表示する
GET /deliverability/accountdeliverability_accountAccount delivery rates, daily ladder, and bounce trend
GET /deliverability/domainsdeliverability_domainsPer-domain sent, delivered, hard and soft bounces, complaints, and failures
GET /deliverability/sendersdeliverability_sendersPer-From-address delivery rates
POST /deliverability/scorescore_emailScore an email's content before it is sent
GET /emails/:id/deliveryemail_deliveryDelivery timeline for one email, with bounce and complaint reasons
GET /threads/:id/deliverythread_deliveryPer-thread delivery counts and per-message failure reasons
GET /suppressionslist_suppressionsワークスペースのサプレッションを一覧表示する
DELETE /suppressions/:emailremove_suppression削除可能なバウンスのサプレッションを解除する
GET /blocked-recipientslist_blocked_recipientsバウンス、苦情、配信停止を一覧表示する
GET /webhooks公開していませんWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks公開していませんWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:id公開していませんWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
PATCH /webhooks/:id公開していませんWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
DELETE /webhooks/:id公開していませんWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/rotate-secret公開していませんWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/test公開していませんWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:id/deliveries公開していませんWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:id/deliveries/:deliveryId公開していませんWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/deliveries/:deliveryId/retry公開していませんWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /contactslist_contactsList contacts
POST /contactscreate_contactAdd a contact with its consent basis
PUT /contactsupsert_contactCreate or update a contact by email
POST /contacts/bulkbulk_update_contactsTag, move, unsubscribe, or delete many contacts at once
GET /contacts/export公開していませんImage uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
GET /contacts/:idget_contactRetrieve a contact by ID or email
PATCH /contacts/:idupdate_contactUpdate a contact's name, fields, or tags, or unsubscribe it
DELETE /contacts/:iddelete_contactDelete a contact and its list memberships
POST /contact-importsimport_contactsImport contacts from CSV
GET /contact-importslist_contact_importsList recent contact imports
GET /tagslist_tagsList contact tags with how many contacts carry each
GET /contact-fieldslist_contact_fieldsList custom contact field definitions
PUT /contact-fields/:keyset_contact_fieldDefine or change a custom contact field
DELETE /contact-fields/:keydelete_contact_fieldDelete a custom field definition
GET /segmentslist_segmentsList saved segments with live counts
POST /segmentscreate_segmentSave a segment
POST /segments/previewpreview_segmentCount and sample the contacts that match unsaved conditions
GET /segments/:idget_segmentRetrieve a segment and its live count
PATCH /segments/:idupdate_segmentRename a segment or change its conditions
DELETE /segments/:iddelete_segmentDelete a segment
GET /listslist_listsList contact lists with member counts
POST /listscreate_listCreate a list with an optional signup form, welcome email, and newsletter site
GET /lists/:idget_listRetrieve a list
PATCH /lists/:idupdate_listRename a list or change its signup form, welcome email, or site
DELETE /lists/:iddelete_listDelete a list without deleting its contacts
POST /lists/:id/contactsadd_list_contactsAdd existing contacts to a list
DELETE /lists/:id/contacts/:contact_idremove_list_contactRemove a contact from a list
GET /broadcastslist_broadcastsList broadcasts
POST /broadcastscreate_broadcastCreate a broadcast draft
GET /broadcasts/:idget_broadcastRetrieve a broadcast and its delivery totals
PATCH /broadcasts/:idupdate_broadcastEdit a draft broadcast
DELETE /broadcasts/:iddelete_broadcastDelete a draft broadcast
GET /broadcasts/:id/checkscheck_broadcastRun the pre-send checks for a broadcast
POST /broadcasts/:id/testsend_broadcast_testSend a test copy of a draft
POST /broadcasts/:id/scheduleschedule_broadcastSchedule a draft to send later
POST /broadcasts/:id/unscheduleunschedule_broadcastUnschedule a draft
POST /broadcasts/:id/duplicateduplicate_broadcastCopy a broadcast into a new draft
POST /broadcasts/:id/sendsend_broadcastSend a broadcast to its audience
POST /broadcasts/:id/send-moresend_broadcast_to_moreSend a sent broadcast to more of its audience
POST /broadcasts/:id/cancelcancel_broadcastCancel a draft or sending broadcast
GET /broadcasts/:id/recipientslist_broadcast_recipientsList a broadcast's recipients, outcomes, and engagement
GET /broadcasts/:id/reportget_broadcast_reportRetrieve a broadcast's engagement report
GET /campaigns/overviewget_campaign_overviewRetrieve subscriber growth and recent broadcast performance
GET /newsletter-settingsget_newsletter_settingsRetrieve newsletter settings
PATCH /newsletter-settingsupdate_newsletter_settingsChange newsletter settings
POST /uploads/images公開していませんImage uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
GET /uploads/imageslist_uploaded_imagesList recently uploaded images
POST /eventstrack_eventRecord something a contact did
POST /events/batch公開していませんHistory import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
GET /automationslist_automationsList automations with their 30-day totals
POST /automationscreate_automationCreate an automation as a draft
GET /automations/:keyget_automationRetrieve an automation with its emails
PATCH /automations/:keyupdate_automationEdit an automation
DELETE /automations/:keydelete_automationDelete an automation and its history
PUT /automations/:key/steps/:positionset_automation_stepCreate or change one email of an automation
DELETE /automations/:key/steps/:positiondelete_automation_stepRemove one email from an automation
PUT /automations/:key/steps/:position/variants/:localeset_automation_step_variantCreate or change a language version of an email
POST /automations/:key/steps/:position/testsend_automation_test_emailSend one email of an automation to yourself as a test
POST /automations/:key/testsend_automation_testSend every email of an automation to yourself as tests
POST /automations/:key/statusset_automation_statusTurn an automation on or off
POST /automations/:key/enrollenroll_contactAdd a contact to an automation
POST /automations/:key/exitexit_contactTake a contact out of an automation
GET /automations/:key/previewpreview_automationDry run: what each person in an automation would get now
GET /automations/overviewget_automations_overviewTotals and a daily series across every automation
GET /automations/:key/reportget_automation_reportResults of one automation, with one row per email
GET /automations/:key/peoplelist_automation_peopleList the people in an automation by what they did
GET /automations/:key/people/:contact_idget_automation_personOne person's history in an automation
POST /automations/:key/import-history公開していませんHistory import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
GET /automation-settingsget_sending_limitsRetrieve the workspace's sending limits for automations
PUT /automation-settingsupdate_sending_limitsChange the workspace's sending limits for automations
GET /automation-librarylist_automation_templatesList the template library: ready-made lifecycle emails
GET /automation-library/:idget_automation_templateRead one template or set, with the email as it will look
POST /automation-library/:id/useuse_automation_templateCreate a draft automation from a template or set
GET /eventslist_eventsList what contacts did, newest first
GET /events/nameslist_event_namesList the kinds of event recorded in the last 30 days
POST /events/preview公開していませんThese answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.
GET /connectionslist_connectionsList the workspace's connections (incoming webhooks)
POST /connectionscreate_connectionCreate a connection and get its address
POST /connections/test公開していませんThese answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.
GET /connections/:idget_connectionRetrieve a connection with its last deliveries
PATCH /connections/:idupdate_connectionChange a connection or switch it on or off
DELETE /connections/:iddelete_connectionDelete a connection
POST /connections/:id/address公開していませんThe address is a credential: whoever holds it can record events for the workspace. Replacing it cuts off the system that uses the old one, so a person does it in the dashboard, next to that system's own settings.
GET /accountget_accountAPIキーを使って、アカウント、使用量、請求状態、ワークスペースの各種件数を取得する
GET /account/diagnosticsget_account_diagnosticsDiagnose sending and receiving problems in the workspace
GET /analyticsget_analytics過去7日、30日、90日間のダッシュボードの送信分析を取得する
GET /profileget_accountGET /accountのセッション専用版です。MCPサーバーはAPIキー用のルートを読み取ります。
POST /billing/checkout公開していません請求の変更は設計上セッション専用で、アカウント所有者がダッシュボードで行う必要があります。請求状態はget_accountで読み取れます。
POST /billing/cancel公開していません請求の変更は設計上セッション専用で、アカウント所有者がダッシュボードで行う必要があります。請求状態はget_accountで読み取れます。
POST /keys公開していません意図的に除外しています。エージェントが認証情報を発行したり破棄したりしてはいけません。キーは人間がダッシュボードで管理します。
GET /keyslist_api_keysAPIキーのメタデータを一覧表示する
DELETE /keys/:id公開していません意図的に除外しています。エージェントが認証情報を発行したり破棄したりしてはいけません。キーは人間がダッシュボードで管理します。

意図的に提供していない機能

機能エンドポイント理由
APIキーの作成、ローテーション、失効、削除POST /keys, DELETE /keys/:id意図的に除外しています。エージェントが認証情報を発行したり破棄したりしてはいけません。キーは人間がダッシュボードで管理します。
チェックアウトの開始またはサブスクリプションのキャンセルPOST /billing/checkout, POST /billing/cancel請求の変更は設計上セッション専用で、アカウント所有者がダッシュボードで行う必要があります。請求状態はget_accountで読み取れます。
CloudflareのワンクリックDNS設定(OAuth)GET /api/dns/cloudflare/connect対話的なブラウザセッションとCloudflareのOAuth同意が必要です。代わりに、get_domainのレコード、get_dns_providerのホスト、またはget_domain_connect_linkを使ってください。
サインアップ、ログイン、ログアウト、Googleアカウントの連携/api/auth/*人間によるブラウザ認証です。MCPサーバーはAPIキーで認証します。
サポートへのお問い合わせフォームPOST /api/contact人間向けの公開マーケティングサイトのフォームで、ワークスペースの操作ではありません。
Webhook endpoints and deliveriesGET /webhooks, POST /webhooks, GET /webhooks/:id, PATCH /webhooks/:id, DELETE /webhooks/:id, POST /webhooks/:id/rotate-secret, POST /webhooks/:id/test, GET /webhooks/:id/deliveries, GET /webhooks/:id/deliveries/:deliveryId, POST /webhooks/:id/deliveries/:deliveryId/retryWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
Upload editor images and export contacts as CSVPOST /uploads/images, GET /contacts/exportImage uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
Import an automation's send history and record events in bulkPOST /automations/:key/import-history, POST /events/batchHistory import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
Move SendHQ's own win-back emails onto automations (backfill and comparison)POST /automations/platform-backfill, GET /automations/platform-compareInternal cutover tools for SendHQ's own workspace only: they answer nobody else, need its owner's dashboard session, and are not part of the public API or of /api/v1. The backfill enrols SendHQ's own accounts, so it is run by a person, one page at a time, after reading the dry run.
Replace a connection's secret addressPOST /connections/:id/addressThe address is a credential: whoever holds it can record events for the workspace. Replacing it cuts off the system that uses the old one, so a person does it in the dashboard, next to that system's own settings.
Dry runs for a sample payload and for a set of eventsPOST /connections/test, POST /events/previewThese answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.

機械可読なカタログ:/docs/mcp/tools.json(スキーマ、アノテーション、エンドポイントの対応、除外項目)。このページのMarkdown版:/docs/mcp.md。CLIをインストールしていれば、sendhq commands --format jsonで同じカタログを出力できます。