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.
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에 대한 문서화된 요청 하나로 변환되므로, MCP 서버는 그 키가 가진 권한만큼만, 그 이상은 갖지 않습니다.
- 142 tools in 10 groups, generated from one catalog that is also published as tools.json.
- 엄격한 JSON 스키마: 알 수 없는 인수, 잘못된 타입, 누락된 필수 필드는 SendHQ에 도달하기 전에 로컬에서 거부됩니다.
- 안정적인
code, HTTPstatus,explanation, 구체적인remedy, 재시도가 도움이 되는지 여부를 담은 구조화된 오류를 반환합니다. - 실제 이메일을 발송하거나 데이터를 삭제하는 모든 도구는 설명의 첫머리에서 이를 밝히며 MCP 안전 어노테이션을 포함합니다.
--read-only모드는 발송 및 변경 도구를 모두 숨깁니다.- 아무것도 로그로 남기지 않습니다. stdout에는 프로토콜 메시지만 흐르며, API 키와 메시지 내용은 어떤 로그에도 기록되지 않습니다.
https://sendhq.cc/api/mcp에서 읽기 전용의 작은 문서용 MCP 엔드포인트도 호스팅합니다(요금 및 문서 조회 전용이며 계정에는 접근하지 않습니다). 이 페이지의 서버는 계정 범위의 전체 기능 서버이며, 로컬에서 실행하거나 아래의 호스팅 커넥터로 사용할 수 있습니다.Use SendHQ in Claude, ChatGPT and Grok
설치가 필요 없습니다. SendHQ는 이 서버를 같은 도구가 포함된 호스팅 커넥터로도 https://mcp.sendhq.cc/mcp에서 운영합니다. 키를 붙여 넣는 대신 SendHQ 계정으로 로그인합니다.
Claude
- Settings → Connectors를 열어 디렉터리에서 SendHQ를 찾거나, Add custom connector를 선택하고
https://mcp.sendhq.cc/mcp를 붙여 넣으세요. - Connect를 클릭하고 SendHQ에 로그인한 뒤 접근 권한을 검토하고 Allow를 클릭하세요.
- Claude에게 받은편지함을 확인하거나, 검증된 도메인으로 이메일을 보내거나, 반송 원인을 설명해 달라고 요청해 보세요.
ChatGPT
- Open Settings → Security and login and turn on Developer mode.
- Go to chatgpt.com/plugins, click Create MCP app, name it SendHQ and enter
https://mcp.sendhq.cc/mcp. - Sign in to SendHQ and click Allow, then pick SendHQ from the tools menu in a new chat.
Grok
- Go to grok.com/connectors, click New Connector, then Custom.
- 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_featuretool 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 Keys에서 이 키를 삭제하면 즉시 연결이 해제됩니다.
- 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 바이너리를 설치하세요(x86-64와 arm64의 Linux, macOS, Windows 지원). 설치 프로그램은 릴리스 체크섬을 검증하고 기본적으로 바이너리를 ~/.local/bin에 넣습니다.
curl -fsSL https://downloads.sendhq.cc/install.sh | shirm https://downloads.sendhq.cc/install.ps1 | iexsendhq version
SENDHQ_API_KEY=re_your_key sendhq doctor대시보드 https://sendhq.cc/app#/keys에서 API 키를 만드세요. MCP 서버는 키를 만들 수 없습니다. 서버를 실행하는 명령어는 다음 하나뿐입니다.
SENDHQ_API_KEY=re_your_key sendhq mcp보통은 직접 실행할 일이 없으며 MCP 클라이언트가 실행합니다. 터미널에서 실행하면 stdin에서 JSON-RPC를 기다립니다.
클라이언트 설정
Claude Code
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를, 프로젝트의 .mcp.json에 기록하려면 --scope project를 추가하세요. 공유 .mcp.json에서는 키를 커밋하지 말고 환경 변수에서 참조하세요. Claude Code는 .mcp.json의 ${VAR}를 확장합니다.
{
"mcpServers": {
"sendhq": {
"command": "sendhq",
"args": [
"mcp"
],
"env": {
"SENDHQ_API_KEY": "${SENDHQ_API_KEY}"
}
}
}
}OpenAI Codex
[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)를 사용하세요.
{
"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가 함께 들어 있습니다.
{"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), andsend_broadcast_to_moredeliver mail to real people and consume delivery credits. Their descriptions start withSENDS 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), andbulk_update_contactsare markeddestructiveHint: trueand their descriptions start withDESTRUCTIVE. Confirm with the user first.remove_suppressionweakens 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 (machineinget_broadcast_report). 423일시 중지를 우회하려고 다른 From 주소로 바꾸지 말고, 수신 거부하거나 스팸 신고한 수신자를 다시 추가하지 마세요.
API 키는 범위 밖입니다
설계상 API 키를 만들거나, 수정하거나, 교체하거나, 폐기하거나, 삭제하는 도구는 없습니다. 에이전트가 자격 증명을 발급하거나 파기해서는 안 되기 때문입니다. list_api_keys는 이름, 비밀이 아닌 접두사, 마지막 사용 시각만 반환합니다. 키 관리는 로그인한 사람이 대시보드에서 수행합니다.
워크플로
1. 첫 발송
get_service_health로 API에 연결할 수 있는지 확인합니다(키 없이도 동작).get_accountshows the plan (access.tier) and remaining quota. If there is no active plan, do not send: the call returnssubscription_required.list_sending_identities로 사용할 수 있는 From 주소를 조회합니다. 목록이 비어 있으면 먼저 도메인 워크플로를 진행하세요.- 발신자, 수신자, 제목, 본문을 사용자에게 확인한 뒤
idempotency_key와 함께send_email을 호출합니다. - 반환된
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. 도메인 검증 전 과정
add_domainwithname: "example.com". The result includes the DNS records (DKIM CNAMEs, domain verification, SPF, recommended DMARC).domain_id로get_dns_provider를 호출하면 권한 있는 DNS 제공업체를 감지하고 해당 제공업체에서 각 레코드에 입력할 정확한 상대 호스트를 반환합니다.- If
providers.domainConnect.availableis true,get_domain_connect_linkreturns 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 existingv=spf1value. verify_domainrechecks DNS and DKIM verification. Status moves throughpending,checking, andpropagatingtoverified. Pollverify_domainorget_domainevery 30–60 seconds; DNS can take minutes to hours.status가verified가 되면 도메인의 주소가list_sending_identities에 나타납니다.
3. 반송, 스팸 신고, 발송 제외
list_blocked_recipients는 차단된 모든 주소를 사유(bounce,complaint,unsubscribe)와 요약 건수와 함께 반환합니다.list_suppressions는 하드 바운스 및 스팸 신고로 인한 발송 제외 항목을 반환하고,deliverability_stats는 최근 30일의 전달률, 반송률, 스팸 신고율을 제공하며,list_sender_reputation은 속도가 제한되었거나 일시 중지된 From 주소를 보여 줍니다.- 발송 제외된 수신자가 포함된 발송은
422 recipient_suppressed로 실패합니다. 그 수신자를 제거하고 다시 발송하세요. - 사람이 반송된 메일함이 이제 정상 작동한다고 확인한 경우에만
remove_suppression을 호출하세요. 스팸 신고로 인한 발송 제외는 영구적입니다(409 complaint_suppression_locked).
4. 수신 이메일 받기
- 도메인(
inbound.example.com같은 서브도메인인 경우가 많음)이 검증되어 있어야 합니다. setup_inbound가 수신을 프로비저닝하고 MX 레코드 하나를 반환합니다. 사람이 이를 게시합니다.status가ready가 될 때까지verify_inbound를 호출합니다.domain_id와local_part(예:support)로create_inbox를 호출하면support@inbound.example.com이 만들어집니다.direction: "in"과unread: true(선택적으로inbox_id)로list_emails를 폴링합니다. 메시지는get_email로, 대화는get_thread로, 첨부 파일은download_attachment로 읽고, 처리를 마치면mark_email(read: true)로 표시합니다.send_email과reply_to_email_id로 같은 스레드에서 답장합니다. SendHQ가 In-Reply-To, References, 스레드를 설정합니다.
5. 웹훅과 이벤트 알림
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. 전달 실패 진단
- 메시지 찾기:
direction: "out"과to또는query를 지정한list_emails를 사용하거나, ID를 알면get_email을 사용합니다.status: failed는 SendHQ 또는 제공업체가 제출 단계에서 거부했다는 뜻이며, 이메일의 오류가 이유를 설명합니다. list_email_events:bounce(제공업체 진단과 함께 영구적 또는 일시적),complaint,reject,delivery. 아직 이벤트가 없다면 제공업체가 보고하지 않은 것이므로 기다렸다가 다시 확인하세요.- 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→ inspectlist_sender_reputation;account_paused→ the workspace is paused for review, read the rates;daily_limit_reached→ wait until midnight UTC;quota_exhausted→get_accountusage. get_domain으로 DKIM, SPF, DMARC가 여전히 게시되어 있는지 확인하고,deliverability_stats로 문제가 메시지 하나의 문제인지 추세인지 확인합니다.- 증거가 보여 주는 내용을 그대로 보고하세요.
delivery이벤트는 수신자의 서버가 메시지를 받아들였다는 뜻이지, 받은편지함에 도달했거나 읽혔다는 뜻이 아닙니다.
7. 작업 버킷 운영하기(라벨)
name(예:Agent/Orders)과skip_inbox: true로create_label을 호출합니다. 그러면 라벨이 버킷이 됩니다. 이 라벨이 붙는 수신 메일은 보관 처리되어 라벨에만 표시되고 사람의 받은편지함에는 나타나지 않습니다.send_email(또는send_batch)에labels: ["Agent/Orders"]를 지정해 작업 메일을 발송합니다. 그 대화에 대한 답장은 라벨을 자동으로 상속하고 받은편지함을 건너뜁니다.- 내 대화 밖에서 시작되는 메일에는 분류 규칙을 추가합니다.
inbox_id(orders@…같은 전용 주소),from,to,subject를 지정해create_label_rule을 호출하세요. 이미 받은 메일도 분류하려면apply_to_existing: true를 전달합니다. - 버킷 처리:
label: "Agent/Orders",direction: "in",unread: true로list_emails를 호출하고,get_email또는get_thread로 읽고,send_email과reply_to_email_id로 답장하며, 처리를 마치면mark_emailread: true로 표시합니다. - 엉뚱한 메시지는
label_email(add/remove)로 버킷에 넣거나 뺍니다. 수신 메시지에 버킷 라벨을 추가하면 그 메시지도 보관 처리됩니다. - 선택적으로
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의 기본값은 파일의 basename입니다). 호스팅 템플릿의 경우 create_template → update_template_draft → 샘플 데이터로 미리 보는 render_template → 실제 테스트 메일 한 통을 보내는 send_template_test → publish_template 순서로 진행한 다음, template: {key, data}와 정확히 한 명의 to 수신자로 send_email 또는 send_batch를 호출해 발송합니다.
9. Send a newsletter
- Audience:
list_lists(orcreate_listwith a signup form), and optionallypreview_segmentthencreate_segmentto narrow it, for example to contacts taggedVIPwho opened in the last 90 days. Add only people who asked for your email: every subscribed contact needs aconsent_basis. get_newsletter_settings: ifpostalAddressis empty, ask the user for one and set it withupdate_newsletter_settings(marketing email needs it).create_broadcastwithlist_id, a verifiedfrom,subject,preview_text, content (markdownis simplest), and optionallyaudience(segment_id,limit,order: engaged).check_broadcast: fix everyblockitem and tell the user aboutwarnitems. Thensend_broadcast_testto the user's own address so they can look at it.- Only when the user says to send:
send_broadcastnow (with anidempotency_key), orschedule_broadcastwithscheduled_at(unschedule_broadcastto change it). - Follow up with
get_broadcast(delivery totals),get_broadcast_report(opens, clicks, links, inbox providers, against your average), andlist_broadcast_recipientswithactivity. Report opens as estimates. With a limited audience,send_broadcast_to_moresends to the next people.
{
"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.
create_automationwith akey, theentryevent,exit_rules(thegoal_eventthat counts as converting, orno_goal: true), a verifiedfrom_address, andsteps, each dueoffset_secondsafter the person entered. It starts as a draft and sends nothing. Every automation carriesdomain, the domain of itsfrom_address; in a workspace that sends from several domains,list_automationsandget_automations_overviewtakedomainto show the automations of one of them.- To let the user read it first:
send_automation_test_emailsends one email, andsend_automation_testevery 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_emailwithdry_run: truereturns the rendered email without sending anything. get_sending_limitsshows how much automation email one person may get across every automation, and during which hours. Change them withupdate_sending_limitsonly when the user asks.- To start from a ready-made email instead of writing one:
list_automation_templatesis 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_templateshows one with the email as this workspace would send it, anduse_automation_templatemakes 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_stepwithtemplateloads one template into an email of an automation that already exists. - An email can also be built in the dashboard's drag-and-drop builder.
get_automationshows such an email witheditordesign: itscontentis the builder's project, which only the builder writes, and itshtmlis 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 ownhtmlwitheditorhtml. - 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_fillon 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 withset_automation_step, and setproduct_nameandsender_namewithupdate_sending_limits. Never invent them.set_automation_statusrefuses to turn the automation on while anything is left (422automation_not_ready, with aproblemslist that names each email and detail); test emails are allowed, so the user can read it first. - Only when the user says to start:
set_automation_statuswithstatus: "on". - Record what people do with
track_event(a new contact needscontact.consent_basis). The entry event starts the sequence, the goal event ends it as converted, and adedupe_keymakes a retry harmless.enroll_contactandexit_contactadd or remove one person by hand. preview_automationshows, 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.list_automationsgives 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.- Results:
get_automations_overview(every automation) andget_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_peoplelists who did what (did: entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, or waiting), andget_automation_persongives 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 labelledmachineand never counted.
{
"name": "use_automation_template",
"arguments": {
"template_id": "payment-failed-notices",
"from_name": "Dana from Acme",
"from_address": "dana@example.com"
}
}{
"name": "preview_automation",
"arguments": {
"automation_key": "checkout-recovery"
}
}{
"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.
list_eventsis 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 bycontact, byname, or by date.list_event_nameslists the kinds of event seen in the last 30 days.list_connectionsshows each connection with its last delivery in plain words, andget_connectionits last 50 deliveries: "Recorded 2 events", "Skipped: no email address", "Refused: bad signature". Start there when something a provider sent did not show up.- Only when the user asks to connect a system:
create_connectionwithkindstripeordodo(mapped for you) orgenericwith amapping. It returns the secretaddressonce; 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. update_connectionwithenabled: falsepauses a connection (its address answers 404);delete_connectionremoves it. The provider's signing secret and a replacement address are set by a person in the dashboard.
{
"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.
{
"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 헤더로 전송됩니다. 논리적 메시지 하나당 고정된 키 하나를 생성하세요(예: 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의 초당 요청 수 제한을 고정 값으로 공개하지 않습니다. 에이전트가 실제로 마주치는 제한은 사용량 한도이며 429로 반환됩니다.
- 요금제별 월간 수신자 전달 수. To, Cc, Bcc 주소 각각이 전달 1건으로 집계됩니다.
get_account→usage.recipientDeliveries와usage.emailQuotaMonth를 비교해 확인하세요. - 정확한 From 주소별 일일 수신자 수는 해당 발신자의 평판 상태에 따라 정해집니다(
list_sender_reputation→dailyLimit, 유료 요금제의 기본값은 2,000). - Subscription: sending is refused with
subscription_requireduntil 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 afterresets_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_reachedwaits 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_limitedmeans Gmail returned 4.7.28; wait untilresets_atand keep sending to other providers. - 첨부 파일: 메시지당 최대 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가 아니라 이 값으로 분기하세요.
| code | HTTP | 재시도 여부 | 의미와 대응 방법 |
|---|---|---|---|
invalid_arguments | — | 아니요 | 인수가 도구의 JSON 스키마 검증에 로컬에서 실패했습니다. SendHQ에는 아무것도 도달하지 않았습니다. problems에 나열된 필드를 수정하세요. |
auth_error | 401 | 아니요 | API 키가 없거나, 폐기되었거나, 잘못되었습니다. 서버 프로세스에 SENDHQ_API_KEY를 설정하세요. 키는 사람이 대시보드에서 만듭니다. |
subscription_required | 402 | 아니요 | No active subscription. Nothing is sent, including to the account owner. The owner chooses a plan. Do not retry until then. |
payment_required | 402 | 아니요 | 이 기능에는 유료 요금제가 필요합니다(예: 첨부 파일). 해당 기능 없이 발송하거나 업그레이드하세요. |
sender_domain_not_owned | 403 | 아니요 | From 도메인이 이 워크스페이스에 없습니다. list_sending_identities 또는 add_domain을 사용하세요. |
sender_domain_unverified | 403 | 아니요 | From 도메인이 아직 검증되지 않았습니다. get_domain을 호출하고, 누락된 레코드를 게시한 뒤 verify_domain을 호출하세요. |
domain_limit_reached | 403 | 아니요 | 요금제의 도메인 한도에 도달했습니다. 사용하지 않는 도메인을 (승인을 받아) 제거하거나 업그레이드하세요. |
marketing_not_enabled | 403 | 아니요 | 이 도메인 또는 요금제에서는 marketing 클래스가 활성화되어 있지 않습니다. 메시지가 실제로 트랜잭션 성격일 때만 transactional을 사용하세요. |
forbidden | 403 | 아니요 | 정책상 허용되지 않는 작업입니다. 요청을 수정하세요. |
not_found | 404 | 아니요 | ID가 이 워크스페이스에 없습니다. 리소스 목록을 조회해 올바른 ID를 찾고, 보관된 템플릿은 먼저 복원하세요. |
idempotency_conflict | 409 | 아니요 | 키를 다른 본문으로 재사용했습니다. 원래 요청을 그대로 다시 보내거나, 새 메시지에는 새 키를 사용하세요. |
idempotency_in_progress | 409 | 예 | 원래 요청이 아직 실행 중입니다. 기다렸다가 같은 키와 본문으로 재시도하세요. |
revision_conflict | 409 | 아니요 | 템플릿 초안을 읽은 뒤 변경되었습니다. get_template을 호출하고, 병합한 뒤 다시 저장하세요. |
complaint_suppression_locked | 409 | 아니요 | 수신자가 스팸으로 신고했습니다. 다시는 이메일을 보내지 마세요. |
inbound_not_ready | 409 | 아니요 | 수신 준비가 되지 않았습니다. setup_inbound, MX 게시, verify_inbound 순서로 진행하세요. |
conflict | 409 | 아니요 | 리소스가 이미 존재하거나 잘못된 상태입니다. 읽어 보고 조정하세요. |
attachments_too_large | 413 | 아니요 | 파일이 10개를 넘거나 10 MB를 넘습니다. 첨부 파일을 제거하거나 줄이세요. |
recipient_suppressed | 422 | 아니요 | 수신자가 이전에 하드 바운스되었거나 스팸으로 신고했습니다. 그 수신자를 제거하세요. list_blocked_recipients를 참고하세요. |
recipient_unsubscribed | 422 | 아니요 | 수신자가 마케팅 메일 수신을 거부했습니다. 그 수신자를 영구적으로 제거하세요. |
validation_failed | 422 | 아니요 | 콘텐츠가 거부되었습니다(예: 변수 계약을 위반하는 템플릿 데이터). 입력을 수정하세요. |
sender_paused | 423 | 아니요 | 이 From 주소는 7일 반송/스팸 신고 차단기에 의해 일시 중지되었습니다. 발송을 중단하고, 목록을 고친 뒤 자동 복구를 기다리세요. |
account_paused | 423 | 아니요 | 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_exhausted | 429 | 아니요 | 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_reached | 429 | after reset | Workspace daily ladder. Not a short backoff. Wait until resets_at (midnight UTC). The message was not queued. |
hourly_limit_reached | 429 | after reset | Hourly pace (about a tenth of the day's cap). Wait until the next UTC hour. Not a short backoff. |
gmail_recipient_limit | 429 | after reset | 500 Gmail recipients a day for a sending domain under 30 days old, on any ladder rung. Wait until midnight UTC. Not queued. |
gmail_rate_limited | 429 | after reset | Gmail returned 4.7.28 for this domain. Wait until resets_at. Other providers keep sending. |
rate_limited | 429 | 예 | Slow down; wait retry_after_seconds. This is not a daily, hourly, or Gmail cap. |
server_error | 5xx | 예 | SendHQ 또는 제공업체의 일시적인 장애입니다. 백오프 후 재시도하세요. 발송은 같은 키와 본문으로 재시도합니다. idempotent_replayed가 true이면 아무것도 발송되지 않았음을 확인한 후 새 키를 사용하세요. |
network_error | — | 예 | 요청 또는 응답이 유실되었습니다. 재시도하세요. 발송은 같은 idempotency_key를 쓰면 안전합니다. |
invalid_request | 400 | 아니요 | 형식이 잘못된 요청입니다. 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이메일 한 통 발송
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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
from | string | 예 | 발신자입니다. 예: Acme <hello@example.com>. 도메인은 이 워크스페이스에서 검증되어 있어야 합니다(list_sending_identities 참조). (최대 998자) |
to | string[] | 예 | 수신자입니다. 각 항목은 주소이며 표시 이름을 붙일 수 있습니다. To+cc+bcc는 합쳐서 최대 100개이며, 모든 대상은 전송 크레딧을 1개씩 소모합니다. (1–100개 항목) |
cc | string[] | 아니요 | 참조(Cc) 수신자. (0–100개 항목) |
bcc | string[] | 아니요 | 숨은 참조(Bcc) 수신자. (0–100개 항목) |
subject | string | 아니요 | 제목입니다. 템플릿을 보낼 때는 생략하세요. (최대 998자) |
text | string | 아니요 | 일반 텍스트 본문. text, html 또는 template 중 하나를 지정하세요. |
html | string | 아니요 | HTML 본문. SendHQ가 이를 정제하며 text를 생략하면 텍스트를 생성합니다. |
reply_to | string | 아니요 | Reply-To 주소. |
headers | object | 아니요 | 안전한 추가 사용자 정의 헤더(문자열 값). 예: {"X-Entity-Ref-ID": "123"}. From/To/Message-ID 같은 라우팅 헤더는 SendHQ가 제어합니다. |
message_class | string | 아니요 | transactional(기본값) 또는 marketing입니다. marketing에는 마케팅이 활성화된 요금제 또는 도메인이 필요하며 수신 거부 처리가 추가됩니다. (다음 중 하나: transactional, marketing) |
reply_to_email_id | string | 아니요 | 기존 대화 안에서 답장합니다. 답장하려는 메시지의 em_… ID입니다. SendHQ가 In-Reply-To/References와 스레드를 설정합니다. |
thread_id | string | 아니요 | 메시지를 분류할 명시적 스레드 ID. |
draft_id | string | 아니요 | 저장된 초안의 첨부 파일을 이 메시지와 함께 보냅니다(dr_…). 발송에 성공하면 초안이 삭제됩니다. |
template | object | 아니요 | 원본 html/text 대신 게시된 호스팅 템플릿을 발송합니다. to 수신자가 정확히 한 명이어야 하며 cc/bcc는 없어야 합니다. 제목은 템플릿이 제공합니다. id, key 중 하나 이상을 지정하세요. |
template.id | string | 아니요 | 템플릿 ID(tmpl_…). id 또는 key를 지정하세요. |
template.key | string | 아니요 | account-welcome 같은 템플릿 키. id 또는 key를 지정하세요. |
template.version_id | string | 아니요 | 선택 사항인 게시 릴리스 ID(tmplv_…). 기본값은 현재 게시된 릴리스입니다. |
template.data | object | 아니요 | 템플릿에 정의된 타입 변수의 값. |
labels | string[] | 아니요 | 이 메시지를 분류할 라벨 이름 또는 lbl_… ID. 알 수 없는 이름은 새로 생성됩니다. 대화의 답장은 라벨을 상속하며, 버킷 라벨(skip_inbox)은 그 답장이 받은편지함에 들어오지 않게 합니다. 최대 10개. (0–10개 항목) |
idempotency_key | string | 아니요 | Idempotency-Key 헤더(최대 200자). 이 요청을 그대로 재시도할 때만 재사용하세요. (최대 200자) |
attachments | object[] | 아니요 | 첨부할 파일(최대 10개 파일, 총 10 MB). 각 파일에는 content_base64(와 filename) 또는 로컬 file_path가 필요합니다. (0–10개 항목) 다음 중 하나 이상을 지정하세요: content_base64, file_path. |
attachments[].filename | string | 아니요 | 수신자에게 표시되는 파일 이름. content_base64와 함께 쓸 때는 필수이며, 기본값은 file_path의 basename입니다. (최대 255자) |
attachments[].content_type | string | 아니요 | MIME 타입. 예: application/pdf. 기본값은 application/octet-stream입니다. |
attachments[].content_base64 | string | 아니요 | 표준 base64 파일 내용. |
attachments[].file_path | string | 아니요 | MCP 서버 프로세스가 읽을 수 있는 로컬 파일의 절대 경로. |
{
"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개별화된 이메일 일괄 발송
SENDS REAL EMAIL(실제 이메일이 발송됩니다). 독립적인 메시지 1~100개를 한 요청으로 발송합니다(수신자별 템플릿 개인화에 사용). 각 항목은 send_email과 같은 형태입니다(attachments/idempotency_key 제외). 항목은 각각 성공하거나 실패합니다. HTTP 207은 부분 성공을 뜻하므로 각 data[i].ok와 data[i].error를 확인하세요. idempotency_key 하나가 일괄 발송 본문 전체를 포괄합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
emails | object[] | 예 | 발송할 메시지. (1–100개 항목) 다음 중 하나 이상을 지정하세요: html, text, template. |
idempotency_key | string | 아니요 | 일괄 발송 전체에 대한 Idempotency-Key(최대 200자). (최대 200자) |
{
"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이메일 목록 조회 및 검색
발신(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}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
direction | string | 아니요 | 수신은 in, 발신은 out. (다음 중 하나: in, out) |
status | string | 아니요 | 상태 필터. 예: queued, sent, delivered, bounced, complained, failed. |
domain | string | 아니요 | 이 도메인 또는 쉼표로 구분한 도메인 목록(하나라도 일치)의 메시지만. |
inbox_id | string | 아니요 | 이 수신함(inb_…)이 받은 메시지만. |
label | string | 아니요 | 이 라벨이 붙은 메시지만: 라벨 ID lbl_… 또는 정확한 이름, 또는 쉼표로 구분한 목록(하나라도 일치). 폴더를 보려면 list_labels를 사용하세요. |
archived | boolean | 아니요 | false = 받은편지함 보기(보관되지 않은 수신 메일), true = 보관된 메일만. 생략하면 모든 메일. |
category | string | 아니요 | primary(사람), updates(뉴스레터, 대량 메일, 자동 메일), spam 또는 쉼표로 구분한 목록. 스팸은 요청하지 않으면 숨겨집니다. |
important | boolean | 아니요 | true = 중요로 표시된 메시지만(내가 시작한 대화에 대한 답장과 중요로 지정한 발신자). |
include_spam | boolean | 아니요 | 결과에 스팸을 포함합니다(모든 폴더에 걸친 검색용). |
from | string | 아니요 | 발신자 주소가 이 값을 포함합니다. |
to | string | 아니요 | 수신자 주소가 이 값을 포함합니다. |
unread | boolean | 아니요 | true = 읽지 않은 메일만, false = 읽은 메일만. |
after | string | 아니요 | ISO-8601 타임스탬프. 그 이후에 생성된 메시지만. (date-time) |
before | string | 아니요 | ISO-8601 타임스탬프. 그 이전에 생성된 메시지만. (date-time) |
query | string | 아니요 | 제목, 본문, 발신자/수신자 주소, 첨부 파일 이름에 대한 자유 텍스트 검색. (최대 200자) |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_emails",
"arguments": {
"direction": "in",
"unread": true,
"limit": 25
}
}get_email이메일 한 통 조회
헤더, html/text 본문, 상태, 스레드 메타데이터, 첨부 파일 메타데이터가 포함된 메시지 하나를 조회합니다(바이트 다운로드는 download_attachment 사용).
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
email_id | string | 예 | 이메일 ID(em_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "get_email",
"arguments": {
"email_id": "em_123"
}
}mark_email읽음, 보관, 스팸, 중요 표시
메시지 하나를 업데이트합니다. read, archived, category(primary, updates, spam, 수신 메일 전용), important를 지정할 수 있습니다. 스팸으로 신고하거나 중요로 표시하면 SendHQ가 이후 메일에 대해 해당 발신자를 학습합니다. 이 메시지만 변경하려면 learn: false를 전달하세요. 필드를 하나 이상 지정해야 합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
email_id | string | 예 | 이메일 ID(em_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
read | boolean | 아니요 | true = 읽음, false = 읽지 않음. |
archived | boolean | 아니요 | true = 보관(받은편지함 건너뜀), false = 받은편지함으로 되돌림. |
category | string | 아니요 | 수신 메시지를 primary, updates 또는 spam으로 이동합니다. (다음 중 하나: primary, updates, spam) |
important | boolean | 아니요 | 메시지를 중요로 표시하거나 표시를 해제합니다. |
learn | boolean | 아니요 | false = 이 판단을 발신자에 대해 기억하지 않습니다(기본값 true). |
{
"name": "mark_email",
"arguments": {
"email_id": "em_123",
"read": true
}
}delete_email이메일 삭제
DESTRUCTIVE(파괴적 작업): 보관 중인 메시지와 저장된 첨부 파일을 SendHQ에서 영구적으로 삭제합니다. 이미 전달된 메시지를 회수하지는 않습니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
email_id | string | 예 | 이메일 ID(em_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "delete_email",
"arguments": {
"email_id": "em_123"
}
}list_email_events이메일의 전송 이벤트 목록 조회
발송된 메시지 하나에 대한 제공업체 이벤트: delivery, bounce, complaint, reject, open, click. 메시지가 전달되었는지, 또는 실패한 이유가 무엇인지에 대한 근거입니다. 페이지네이션: 결과에 pagination {offset, limit, returned, total?, has_more, next_offset}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
email_id | string | 예 | 이메일 ID(em_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_email_events",
"arguments": {
"email_id": "em_123"
}
}get_thread대화 조회
대화의 모든 메시지(발신 및 수신)를 시간순으로, 각각 첨부 파일 메타데이터와 함께 조회합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
thread_id | string | 예 | 스레드 ID(보통 첫 메시지의 em_… ID이며, 아무 이메일의 threadId를 참조). (최대 128자) |
{
"name": "get_thread",
"arguments": {
"thread_id": "em_123"
}
}email_deliveryGet 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_id | string | 예 | |
limit | integer | 아니요 | |
offset | integer | 아니요 |
{
"name": "email_delivery",
"arguments": {
"email_id": "em_123"
}
}thread_deliveryGet a thread delivery summary
Counts of delivered, bounced, complained, and failed outbound messages in one conversation, plus each message's failure reason.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
thread_id | string | 예 |
{
"name": "thread_delivery",
"arguments": {
"thread_id": "thr_123"
}
}라벨 및 자동 분류 규칙
list_labels라벨 목록 조회
워크스페이스의 라벨(폴더)을 전체 및 읽지 않은 메시지 수, 자동 분류 규칙과 함께 나열합니다. 페이지네이션: 결과에 pagination {offset, limit, returned, total?, has_more, next_offset}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_labels",
"arguments": {}
}get_label라벨 조회
메시지 수와 자동 분류 규칙이 포함된 라벨 하나를 조회합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
label_id | string | 예 | 라벨 ID(lbl_로 시작) 또는 정확한 라벨 이름. (최대 128자) |
{
"name": "get_label",
"arguments": {
"label_id": "Billing"
}
}create_label라벨 생성
폴더 형태의 라벨을 생성합니다. skip_inbox: true를 설정하면 에이전트가 소유하는 버킷이 됩니다. labels: [name]으로 발송하면 답장이 해당 라벨로 분류되고 받은편지함에는 들어오지 않습니다. 선택 사항인 자동 분류 규칙은 새로 발송하거나 수신한 메일을 분류합니다(규칙의 모든 조건이 일치해야 함). 보관 중인 메일도 분류하려면 apply_to_existing을 설정하세요.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | 라벨 이름. 예: Billing 또는 Clients/Acme. 워크스페이스 안에서 고유해야 합니다(대소문자 구분 없음). (최대 64자) |
color | string | 아니요 | #1a73e8 같은 16진수 색상. 선택 사항. |
skip_inbox | boolean | 아니요 | 버킷 모드: 이 라벨이 붙는 수신 메일(규칙, 이 라벨로 발송한 대화에 대한 답장, 수동 추가 중 어느 경우든)은 보관 처리되어 받은편지함이 아닌 라벨에만 표시됩니다. |
rules | object[] | 아니요 | 선택 사항인 자동 분류 규칙(최대 20개). 각 규칙에는 inbox_id, from, to, subject 중 하나 이상이 필요합니다. (0–20개 항목) |
rules[].direction | string | 아니요 | in(수신) 또는 out(발신) 메일만. 생략하면 둘 다. (다음 중 하나: in, out) |
rules[].inbox_id | string | 아니요 | 이 수신함(inb_…)이 받은 메일만. 수신 주소마다 별도의 폴더로 분류합니다. |
rules[].from | string | 아니요 | 발신자가 이 텍스트를 포함합니다(대소문자 구분 없음). 예: @stripe.com. (최대 200자) |
rules[].to | string | 아니요 | To/Cc가 이 텍스트를 포함합니다(대소문자 구분 없음). (최대 200자) |
rules[].subject | string | 아니요 | 제목이 이 텍스트를 포함합니다(대소문자 구분 없음). (최대 200자) |
rules[].skip_inbox | boolean | 아니요 | 일치하는 수신 메일을 보관 처리해 받은편지함이 아닌 라벨 폴더에만 표시합니다. |
apply_to_existing | boolean | 아니요 | 규칙과 일치하는, 이미 보관 중인 메일도 분류합니다. |
{
"name": "create_label",
"arguments": {
"name": "Agent/Orders",
"skip_inbox": true,
"rules": [
{
"from": "@stripe.com"
}
]
}
}update_label라벨 이름 변경, 색상 변경, 버킷 전환
라벨 이름을 바꾸거나, 색상을 변경하거나, 버킷 모드(skip_inbox)를 전환합니다. 버킷 모드를 켜면 이미 라벨에 있는 수신 메일도 보관 처리됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
label_id | string | 예 | 라벨 ID(lbl_로 시작) 또는 정확한 라벨 이름. (최대 128자) |
name | string | 아니요 | 새 이름. (최대 64자) |
color | string | 아니요 | 새 16진수 색상. |
skip_inbox | boolean | 아니요 | 버킷 모드: 이 라벨이 붙는 수신 메일(규칙, 이 라벨로 발송한 대화에 대한 답장, 수동 추가 중 어느 경우든)은 보관 처리되어 받은편지함이 아닌 라벨에만 표시됩니다. |
{
"name": "update_label",
"arguments": {
"label_id": "lbl_123",
"name": "Finance/Billing"
}
}delete_label라벨 삭제
DESTRUCTIVE(파괴적 작업): 라벨과 그 규칙을 삭제합니다. 이메일 자체는 유지되며 이 라벨만 사라집니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
label_id | string | 예 | 라벨 ID(lbl_로 시작) 또는 정확한 라벨 이름. (최대 128자) |
{
"name": "delete_label",
"arguments": {
"label_id": "lbl_123"
}
}create_label_rule자동 분류 규칙 추가
라벨에 규칙을 추가해 조건에 맞는 새 메일이 자동으로 분류되게 합니다. 설정한 모든 조건이 일치해야 합니다. 수신 주소마다 별도 폴더를 만들려면 inbox_id를 사용하고, 받은편지함에 들어오지 않게 하려면 skip_inbox를 추가하세요.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
label_id | string | 예 | 라벨 ID(lbl_로 시작) 또는 정확한 라벨 이름. (최대 128자) |
direction | string | 아니요 | in(수신) 또는 out(발신) 메일만. 생략하면 둘 다. (다음 중 하나: in, out) |
inbox_id | string | 아니요 | 이 수신함(inb_…)이 받은 메일만. 수신 주소마다 별도의 폴더로 분류합니다. |
from | string | 아니요 | 발신자가 이 텍스트를 포함합니다(대소문자 구분 없음). 예: @stripe.com. (최대 200자) |
to | string | 아니요 | To/Cc가 이 텍스트를 포함합니다(대소문자 구분 없음). (최대 200자) |
subject | string | 아니요 | 제목이 이 텍스트를 포함합니다(대소문자 구분 없음). (최대 200자) |
skip_inbox | boolean | 아니요 | 일치하는 수신 메일을 보관 처리해 받은편지함이 아닌 라벨 폴더에만 표시합니다. |
apply_to_existing | boolean | 아니요 | 조건에 일치하는, 이미 보관 중인 메일도 분류합니다. |
{
"name": "create_label_rule",
"arguments": {
"label_id": "Billing",
"inbox_id": "inb_123",
"skip_inbox": true
}
}delete_label_rule자동 분류 규칙 삭제
DESTRUCTIVE(파괴적 작업): 자동 분류 규칙 하나를 제거합니다. 이미 분류된 메일은 라벨이 유지됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
label_id | string | 예 | 라벨 ID(lbl_로 시작) 또는 정확한 라벨 이름. (최대 128자) |
rule_id | string | 예 | 규칙 ID(lrule_로 시작). get_label에서 가져옵니다. (최대 128자) |
{
"name": "delete_label_rule",
"arguments": {
"label_id": "lbl_123",
"rule_id": "lrule_123"
}
}label_email이메일에 라벨 추가 또는 제거
메시지를 폴더 사이에서 이동합니다. 이름 또는 lbl_… ID로 라벨을 추가하거나 제거하세요. add의 알 수 없는 이름은 create가 false가 아닌 한 새로 생성됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
email_id | string | 예 | 이메일 ID(em_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
add | string[] | 아니요 | 추가할 라벨. (0–10개 항목) |
remove | string[] | 아니요 | 제거할 라벨. (0–10개 항목) |
create | boolean | 아니요 | add의 알 수 없는 라벨을 생성합니다(기본값 true). |
{
"name": "label_email",
"arguments": {
"email_id": "em_123",
"add": [
"Billing"
],
"remove": [
"Support"
]
}
}초안, 첨부 파일, 발신 ID
list_sending_identities검증된 발신 ID 목록 조회
이 워크스페이스가 지금 발신할 수 있는 주소와 도메인(검증된 도메인, 기본 From, 활성 수신함 주소)입니다. 유효한 from을 고르려면 send_email 전에 호출하세요.
매개변수 없음.
{
"name": "list_sending_identities",
"arguments": {}
}create_draft초안 생성
작성기 초안을 생성합니다. 초안에는 첨부 파일이 들어갑니다. 초안을 만들고, upload_attachment를 호출한 뒤, draft_id와 함께 send_email을 호출하세요. 아무것도 발송하지 않습니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
from | string | 아니요 | 검증된 도메인의 발신 주소(초안 작성 중에는 비워 둘 수 있음). |
to | string[] | 아니요 | 수신자. (0–100개 항목) |
cc | string[] | 아니요 | 참조(Cc) 수신자. (0–100개 항목) |
bcc | string[] | 아니요 | 숨은 참조(Bcc) 수신자. (0–100개 항목) |
subject | string | 아니요 | 제목. (최대 998자) |
html | string | 아니요 | HTML 본문. |
text | string | 아니요 | 일반 텍스트 본문. |
reply_to_email_id | string | 아니요 | 이 초안이 답장하는 이메일 ID. |
thread_id | string | 아니요 | 이 초안이 속한 스레드 ID. |
{
"name": "create_draft",
"arguments": {
"from": "hello@example.com",
"to": [
"owner@example.com"
],
"subject": "Invoice"
}
}list_drafts초안 목록 조회
작성기 초안을 최근 업데이트순으로 나열합니다. 페이지네이션: 결과에 pagination {offset, limit, returned, total?, has_more, next_offset}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_drafts",
"arguments": {}
}get_draft초안 조회
첨부 파일 메타데이터가 포함된 초안 하나를 조회합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
draft_id | string | 예 | 초안 ID(dr_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "get_draft",
"arguments": {
"draft_id": "dr_123"
}
}update_draft초안 내용 교체
초안의 내용과 수신자를 교체합니다. 전체 교체이므로 생략한 필드는 지워집니다. 먼저 get_draft를 읽고 유지하려는 모든 필드를 함께 보내세요. 첨부 파일은 영향을 받지 않습니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
draft_id | string | 예 | 초안 ID(dr_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
from | string | 아니요 | 검증된 도메인의 발신 주소(초안 작성 중에는 비워 둘 수 있음). |
to | string[] | 아니요 | 수신자. (0–100개 항목) |
cc | string[] | 아니요 | 참조(Cc) 수신자. (0–100개 항목) |
bcc | string[] | 아니요 | 숨은 참조(Bcc) 수신자. (0–100개 항목) |
subject | string | 아니요 | 제목. (최대 998자) |
html | string | 아니요 | HTML 본문. |
text | string | 아니요 | 일반 텍스트 본문. |
reply_to_email_id | string | 아니요 | 이 초안이 답장하는 이메일 ID. |
thread_id | string | 아니요 | 이 초안이 속한 스레드 ID. |
{
"name": "update_draft",
"arguments": {
"draft_id": "dr_123",
"from": "hello@example.com",
"to": [
"owner@example.com"
],
"subject": "Invoice (updated)",
"text": "Attached."
}
}delete_draft초안 폐기
DESTRUCTIVE(파괴적 작업): 초안을 폐기하고 저장된 첨부 파일을 영구 삭제합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
draft_id | string | 예 | 초안 ID(dr_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "delete_draft",
"arguments": {
"draft_id": "dr_123"
}
}upload_attachment초안에 첨부 파일 업로드
초안에 파일 하나를 업로드합니다(메시지당 최대 10개 파일, 총 10 MB). content_base64 또는 로컬 file_path를 지정하세요. 첨부 파일은 발송 시점에 유료 요금제가 필요합니다.
다음 중 하나 이상을 지정하세요: content_base64, file_path.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
draft_id | string | 예 | 초안 ID(dr_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
filename | string | 아니요 | 수신자에게 표시되는 파일 이름. 기본값은 file_path의 basename입니다. (최대 255자) |
content_type | string | 아니요 | MIME 타입. 예: application/pdf. 기본값은 application/octet-stream입니다. |
content_base64 | string | 아니요 | 표준 base64 파일 내용. |
file_path | string | 아니요 | MCP 서버 프로세스가 읽을 수 있는 로컬 파일의 절대 경로. |
{
"name": "upload_attachment",
"arguments": {
"draft_id": "dr_123",
"filename": "invoice.pdf",
"content_type": "application/pdf",
"file_path": "/tmp/invoice.pdf"
}
}download_attachment첨부 파일 다운로드
비공개 첨부 파일(발신, 수신 또는 초안)을 다운로드합니다. base64 내용을 반환하거나, save_to_path가 설정되면 파일로 씁니다(overwrite가 true가 아니면 덮어쓰기를 거부).
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
attachment_id | string | 예 | 첨부 파일 ID(att_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
save_to_path | string | 아니요 | base64를 반환하는 대신 파일을 쓸 로컬 절대 경로(선택 사항). |
overwrite | boolean | 아니요 | save_to_path에 있는 기존 파일을 교체하도록 허용합니다. 기본값은 false입니다. |
{
"name": "download_attachment",
"arguments": {
"attachment_id": "att_123",
"save_to_path": "/tmp/invoice.pdf"
}
}delete_attachment첨부 파일 삭제
DESTRUCTIVE(파괴적 작업): 저장된 첨부 파일을 영구 삭제합니다(예: 발송 전에 초안에서 파일 제거).
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
attachment_id | string | 예 | 첨부 파일 ID(att_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "delete_attachment",
"arguments": {
"attachment_id": "att_123"
}
}호스팅 템플릿
list_templates호스팅 템플릿 목록 조회
게시 상태와 사용 현황이 포함된 호스팅 이메일 템플릿을 나열합니다. 페이지네이션: 결과에 pagination {offset, limit, returned, total?, has_more, next_offset}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
lifecycle | string | 아니요 | active(기본값), archived, all. (다음 중 하나: active, archived, all) |
query | string | 아니요 | 이름 또는 키로 검색. (최대 120자) |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_templates",
"arguments": {
"lifecycle": "active"
}
}create_template호스팅 템플릿 생성
편집 가능한 초안이 있는 템플릿을 생성하며, 선택적으로 스타터(welcome, reset, receipt, blank)에서 시작할 수 있습니다. 키로 발송하기 전에 게시하세요.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | 사람이 읽는 이름. (최대 120자) |
key | string | 아니요 | 고정된 발송 키: 소문자, 숫자, 하이픈이며 영문자로 시작합니다(2–64자). 생략하면 이름에서 만들어집니다. |
starter | string | 아니요 | 스타터 콘텐츠. (다음 중 하나: blank, welcome, reset, receipt) |
{
"name": "create_template",
"arguments": {
"name": "Account welcome",
"key": "account-welcome",
"starter": "welcome"
}
}get_template템플릿 조회
템플릿의 현재 초안(revision 포함), 활성 게시 릴리스, 릴리스 이력, 사용 현황을 조회합니다. ID 또는 키를 받습니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
template_id | string | 예 | 템플릿 ID(tmpl_…) 또는 키. (최대 128자) |
{
"name": "get_template",
"arguments": {
"template_id": "account-welcome"
}
}update_template_draft템플릿 초안 저장
낙관적 동시성으로 템플릿의 편집 가능한 초안을 저장합니다. get_template에서 가져온 현재 revision을 전달하세요(409는 다른 사람이 먼저 저장했다는 뜻이므로 다시 읽고 재시도). 초안 내용의 전체 교체이므로 생략한 필드는 지워집니다. 유지하려는 모든 필드를 함께 보내세요. {{variable}} 자리 표시자를 사용하세요.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
template_id | string | 예 | 템플릿 ID 또는 키. (최대 128자) |
revision | integer | 예 | get_template에서 가져온 현재 초안 리비전. (1–…) |
name | string | 아니요 | 템플릿 이름. (최대 120자) |
subject_template | string | 아니요 | 자리 표시자가 포함된 제목. (최대 998자) |
preheader_template | string | 아니요 | 미리 보기 텍스트. (최대 240자) |
html_template | string | 아니요 | 자리 표시자가 포함된 HTML 본문. |
text_template | string | 아니요 | 자리 표시자가 포함된 일반 텍스트 본문. |
from | string | 아니요 | 이 템플릿으로 발송할 때의 기본 발신자. |
reply_to | string | 아니요 | 기본 Reply-To. |
variables | object[] | 아니요 | 타입이 지정된 변수 계약. 각 항목: {key(소문자/밑줄), label, type: text|number|url|boolean, required(기본값 true), fallback, description}. |
variables[].key | string | 예 | |
variables[].label | string | 아니요 | |
variables[].type | string | 아니요 | (다음 중 하나: text, number, url, boolean) |
variables[].required | boolean | 아니요 | |
variables[].fallback | any | 아니요 | |
variables[].description | string | 아니요 | |
sample_data | object | 아니요 | 미리 보기와 테스트에 사용하는 샘플 값. |
{
"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게시된 릴리스에서 새 초안 시작
현재 게시된 릴리스를 복사해 편집 가능한 새 초안을 생성합니다(이미 초안이 있거나 게시된 것이 없으면 409).
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
template_id | string | 예 | 템플릿 ID 또는 키. (최대 128자) |
{
"name": "create_template_draft",
"arguments": {
"template_id": "account-welcome"
}
}render_template템플릿 미리 보기 렌더링
초안, 게시된 릴리스 또는 특정 버전을 주어진 데이터로 렌더링해 서버의 실제 출력(subject, html, text)을 확인합니다. 발송하지 않습니다. 데이터가 변수 계약을 위반하면 findings와 함께 422를 반환합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
template_id | string | 예 | 템플릿 ID 또는 키. (최대 128자) |
version_id | string | 아니요 | 선택 사항인 버전 ID. 기본값은 초안이며, 없으면 게시된 릴리스입니다. |
data | object | 아니요 | 변수 값. 기본값은 해당 버전의 샘플 데이터입니다. |
{
"name": "render_template",
"arguments": {
"template_id": "account-welcome",
"data": {
"first_name": "Asha"
}
}
}send_template_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_id | string | 예 | 템플릿 ID 또는 키. (최대 128자) |
to | string[] | 예 | 테스트 수신자. (1–100개 항목) |
from | string | 아니요 | 검증된 도메인의 발신자. 기본값은 템플릿의 From입니다. |
version_id | string | 아니요 | 선택 사항인 버전 ID. |
data | object | 아니요 | 변수 값. 기본값은 샘플 데이터입니다. |
{
"name": "send_template_test",
"arguments": {
"template_id": "account-welcome",
"to": [
"owner@example.com"
]
}
}publish_template템플릿 릴리스 게시
현재 초안을 template.key를 사용하는 send_email이 쓰게 될 변경 불가능한 릴리스로 게시합니다. 유효성 검사 오류가 있으면 422 findings로 실패하고, 이미 프로덕션에서 사용 중인 템플릿의 라이브 변수 계약을 깨뜨리는 경우 409로 실패합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
template_id | string | 예 | 템플릿 ID 또는 키. (최대 128자) |
{
"name": "publish_template",
"arguments": {
"template_id": "account-welcome"
}
}archive_template템플릿 보관 처리
이 템플릿을 사용하는 새 발송을 중단합니다(이력은 유지되며 restore_template으로 되돌릴 수 있음). 이 키로 발송하는 모든 연동은 404로 실패하기 시작합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
template_id | string | 예 | 템플릿 ID 또는 키. (최대 128자) |
{
"name": "archive_template",
"arguments": {
"template_id": "account-welcome"
}
}restore_template보관된 템플릿 복원
보관된 템플릿을 다시 활성화합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
template_id | string | 예 | 템플릿 ID 또는 키. (최대 128자) |
{
"name": "restore_template",
"arguments": {
"template_id": "account-welcome"
}
}도메인과 DNS
list_domains도메인 목록 조회
집계된 setup_status(verified | checking | pending), 레코드별 DNS 상태, 수신 상태와 함께 발신 도메인을 나열합니다. 느릴 수 있습니다. 검증되지 않은 도메인은 실시간으로 다시 확인합니다. 페이지네이션: 결과에 pagination {offset, limit, returned, total?, has_more, next_offset}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_domains",
"arguments": {}
}get_domain도메인 설정 세부 정보 조회
게시할 정확한 DNS 레코드(type, name, value), 공개 리졸버 두 곳에서 확인한 각 레코드의 실시간 상태, 해결 방법이 담긴 dns_issues, 수신 상태와 함께 도메인 하나를 조회합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
domain_id | string | 예 | 도메인 ID(dom_으로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "get_domain",
"arguments": {
"domain_id": "dom_123"
}
}add_domain발신 도메인 추가
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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | example.com 또는 mail.example.com 같은 순수 도메인 이름. (최대 253자) |
default_from | string | 아니요 | 이 도메인의 기본 발신 주소(선택 사항). |
{
"name": "add_domain",
"arguments": {
"name": "example.com"
}
}verify_domain도메인 검증
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_id | string | 예 | 도메인 ID(dom_으로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "verify_domain",
"arguments": {
"domain_id": "dom_123"
}
}delete_domain도메인 삭제
DESTRUCTIVE(파괴적 작업): 수신 라우트를 포함해 도메인을 워크스페이스에서 제거합니다. 이후 이 도메인에서의 발송은 즉시 실패합니다. DNS 제공업체에 있는 DNS 레코드는 삭제하지 않습니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
domain_id | string | 예 | 도메인 ID(dom_으로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "delete_domain",
"arguments": {
"domain_id": "dom_123"
}
}get_dns_providerDNS 제공업체와 레코드 호스트 감지
도메인의 권한 있는 DNS 제공업체를 감지하고, 각 레코드에 대해 해당 제공업체에 입력할 상대 호스트, 권장 DMARC 레코드, 수신 MX 안내, 원클릭 설정(Domain Connect) 사용 가능 여부를 반환합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
domain_id | string | 예 | 도메인 ID(dom_으로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "get_dns_provider",
"arguments": {
"domain_id": "dom_123"
}
}get_domain_connect_link원클릭 DNS 설정 링크 가져오기
get_dns_provider가 providers.domainConnect.available을 보고하면 서명된 동의 URL을 생성합니다. 이를 사람에게 전달하세요. 사람이 URL을 열어 DNS 제공업체에서 DNS 변경을 승인합니다. 승인 전까지는 아무것도 바뀌지 않습니다. 지원되지 않으면 409.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
domain_id | string | 예 | 도메인 ID(dom_으로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "get_domain_connect_link",
"arguments": {
"domain_id": "dom_123"
}
}수신 이메일
setup_inbound도메인의 수신 활성화
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_id | string | 예 | 도메인 ID(dom_으로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "setup_inbound",
"arguments": {
"domain_id": "dom_123"
}
}verify_inbound수신 MX 검증
수신 MX 레코드를 다시 확인합니다. 공개 리졸버 두 곳 모두에서 레코드가 보이면 상태가 ready가 됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
domain_id | string | 예 | 도메인 ID(dom_으로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "verify_inbound",
"arguments": {
"domain_id": "dom_123"
}
}list_inboxes수신 주소 목록 조회
수신 주소를 나열하며, 도메인 하나로 한정할 수도 있습니다. 페이지네이션: 결과에 pagination {offset, limit, returned, total?, has_more, next_offset}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
domain_id | string | 아니요 | 선택 사항인 도메인 ID 필터. |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_inboxes",
"arguments": {
"domain_id": "dom_123"
}
}get_inbox수신함 조회
수신 주소 하나를 조회합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
inbox_id | string | 예 | 수신함 ID(inb_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "get_inbox",
"arguments": {
"inbox_id": "inb_123"
}
}create_inbox수신 주소 생성
수신 상태가 ready인 도메인에 support@<receiving domain> 같은 주소를 생성합니다(먼저 setup_inbound와 verify_inbound를 실행하세요). 수신한 메일은 direction in으로 list_emails에 나타납니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
domain_id | string | 예 | 도메인 ID(dom_으로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
local_part | string | 예 | @ 앞부분. 예: support. (최대 64자) |
name | string | 아니요 | 선택 사항인 표시 이름. |
{
"name": "create_inbox",
"arguments": {
"domain_id": "dom_123",
"local_part": "support",
"name": "Support"
}
}update_inbox수신함 이름 변경, 활성화 또는 비활성화
수신함 이름을 바꾸거나 상태를 active / disabled로 설정합니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
inbox_id | string | 예 | 수신함 ID(inb_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
name | string | 아니요 | 새 표시 이름. |
status | string | 아니요 | 새 상태. (다음 중 하나: active, disabled) |
{
"name": "update_inbox",
"arguments": {
"inbox_id": "inb_123",
"status": "disabled"
}
}set_inbox_forwarding수신함을 다른 주소로 전달
SENDS REAL EMAIL(실제 이메일이 발송됩니다) - 계정 소유자가 아닌 다른 사람에게 전달하도록 설정하는 경우: 수신함이 받은 메일을 전달할 곳을 설정합니다. 소유자 본인의 주소는 즉시 활성화되고, 그 밖의 주소에는 확인 이메일이 발송되며 그곳에서 누군가 확인할 때까지 전달 상태는 pending으로 유지됩니다. 전달을 끄려면 forward_to: null을 전달하세요. 전달된 사본은 수신함 주소에서 발송되며 원래 발신자가 Reply-To로 지정됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
inbox_id | string | 예 | 수신함 ID(inb_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
forward_to | string,null | 예 | 전달 대상 이메일 주소. 전달을 끄려면 null. (최대 254자) |
{
"name": "set_inbox_forwarding",
"arguments": {
"inbox_id": "inb_123",
"forward_to": "team@example.net"
}
}delete_inbox수신함 삭제
DESTRUCTIVE(파괴적 작업): 수신 주소를 삭제합니다. 이미 받은 메일은 보관되며, 이 주소로 오는 새 메일은 더 이상 그 수신함으로 분류되지 않습니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
inbox_id | string | 예 | 수신함 ID(inb_로 시작). 목록 또는 생성 도구가 반환한 값. (최대 128자) |
{
"name": "delete_inbox",
"arguments": {
"inbox_id": "inb_123"
}
}전달성, 반송, 발송 제외
deliverability_stats최근 30일 전송 통계 조회
워크스페이스 전체의 최근 30일 합계: sent, delivery, bounce, complaint, reject, open, click, deliveryRate(%).
매개변수 없음.
{
"name": "deliverability_stats",
"arguments": {}
}deliverability_accountGet 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
days | integer | 아니요 | (one of 7, 30, 90) |
{
"name": "deliverability_account",
"arguments": {
"days": 30
}
}deliverability_domainsGet 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
days | integer | 아니요 | |
domain | string | 아니요 | |
limit | integer | 아니요 | |
offset | integer | 아니요 |
{
"name": "deliverability_domains",
"arguments": {
"days": 30
}
}deliverability_sendersGet sender delivery rates
Per From address: sent, delivered, hard and soft bounces, complaints, failures, and rates.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
days | integer | 아니요 | |
domain | string | 아니요 | |
limit | integer | 아니요 | |
offset | integer | 아니요 |
{
"name": "deliverability_senders",
"arguments": {
"days": 30
}
}score_emailScore 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
subject | string | 아니요 | The subject line. |
html | string | 아니요 | The HTML as written, before SendHQ adds its footer or tracking. (max 2000000 chars) |
text | string | 아니요 | The plain-text part. Compared with the HTML when both are given; scored on its own when there is no HTML. (max 2000000 chars) |
from | string | 아니요 | The sender: an email address or a domain such as example.com. Without it, links to other sites are not judged. (max 320 chars) |
{
"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발신자 평판 목록 조회
정확한 From 주소별 평판 상태: active, throttled(일일 한도 하향), paused(발송 시 423 반환), 그리고 사유와 일일 한도. 발송이 423 또는 429로 실패할 때 확인하세요. 페이지네이션: 결과에 pagination {offset, limit, returned, total?, has_more, next_offset}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_sender_reputation",
"arguments": {}
}list_suppressions발송 제외 목록 조회
워크스페이스 발송 제외 목록: 영구 반송 또는 스팸 신고 이후 차단된 수신자. 이들에게 보내는 발송은 422로 실패합니다. 페이지네이션: 결과에 pagination {offset, limit, returned, total?, has_more, next_offset}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_suppressions",
"arguments": {}
}remove_suppression반송 발송 제외 삭제
DESTRUCTIVE(파괴적 작업, 안전 차단을 약화시킴): 해당 주소로 다시 메일을 보낼 수 있도록 반송 발송 제외를 삭제합니다. 사람이 그 주소가 이제 유효하다고 확인한 경우에만 수행하세요. 스팸 신고로 인한 발송 제외는 삭제할 수 없습니다(409).
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
email | string | 예 | 발송 제외된 수신자 주소. (최대 320자) |
{
"name": "remove_suppression",
"arguments": {
"email": "fixed-mailbox@example.net"
}
}list_blocked_recipients차단된 수신자 목록 조회
SendHQ가 거부하는 모든 수신자: 반송, 스팸 신고, 도메인 단위 마케팅 수신 거부이며 유형별 요약이 포함됩니다. 최신 500건까지 읽습니다. 페이지네이션: 결과에 pagination {offset, limit, returned, total?, has_more, next_offset}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_blocked_recipients",
"arguments": {}
}Campaigns
list_contactsList 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_id | string | 아니요 | Only members of this list (lst_…). |
status | string | 아니요 | 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) |
query | string | 아니요 | Email or name contains this text; * is a wildcard on the email. (max 200 chars) |
tag | string | 아니요 | Only contacts with this tag. (max 60 chars) |
source | string | 아니요 | How the contact was added. (one of form, api, import) |
after | string | 아니요 | Signed up at or after this time. ISO 8601 date or date-time. (max 40 chars) |
before | string | 아니요 | Signed up before this time. ISO 8601 date or date-time. (max 40 chars) |
segment_id | string | 아니요 | Only contacts matching this saved segment (seg_…). |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_contacts",
"arguments": {
"status": "subscribed"
}
}create_contactAdd 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
email | string | 예 | Email address. (max 320 chars) |
name | string | 아니요 | Display name; the first word is {{first_name}}. (max 200 chars) |
fields | object | 아니요 | 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. |
tags | string[] | 아니요 | Tags to attach, e.g. ["VIP"]. Up to 50. (0–50 items) |
list_ids | string[] | 아니요 | Lists to add the contact to (lst_…). (0–100 items) |
status | string | 아니요 | subscribed (default, requires consent_basis) or unsubscribed. (one of subscribed, unsubscribed) |
consent_basis | string | 아니요 | 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) |
{
"name": "create_contact",
"arguments": {
"email": "ada@example.net",
"name": "Ada Lovelace",
"consent_basis": "Ticked the newsletter box at checkout on acme.com"
}
}upsert_contactCreate 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
email | string | 예 | Email address. (max 320 chars) |
name | string | 아니요 | Display name; the first word is {{first_name}}. (max 200 chars) |
fields | object | 아니요 | Custom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field. |
tags | string[] | 아니요 | Tags to add, e.g. ["VIP"]. Existing tags are kept. (0–50 items) |
timezone | string | 아니요 | IANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars) |
locale | string | 아니요 | Language tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars) |
consent_basis | string | 아니요 | 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) |
{
"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"
}
}get_contactGet 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_id | string | 예 | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "get_contact",
"arguments": {
"contact_id": "ct_123"
}
}update_contactUpdate, 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_id | string | 예 | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
name | string | 아니요 | New display name. (max 200 chars) |
fields | object | 아니요 | 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. |
tags | string[] | 아니요 | Replace all of the contact's tags with these. (0–50 items) |
add_tags | string[] | 아니요 | Tags to add. (0–50 items) |
remove_tags | string[] | 아니요 | Tags to remove. (0–50 items) |
status | string | 아니요 | Only unsubscribed is accepted. (one of unsubscribed) |
{
"name": "update_contact",
"arguments": {
"contact_id": "ct_123",
"fields": {
"plan": "team"
}
}
}delete_contactDelete 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_id | string | 예 | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "delete_contact",
"arguments": {
"contact_id": "ct_123"
}
}import_contactsImport 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
csv | string | 예 | The CSV file content, header row first. (max 5242880 chars) |
list_id | string | 아니요 | Add every accepted row to this list (lst_…). |
consent_basis | string | 예 | 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) |
tags | string[] | 아니요 | Tags to add to every accepted row, e.g. ["imported-2026-11"]. (0–50 items) |
update_existing | boolean | 아니요 | Merge names and fields into contacts that already exist. Their status never changes. |
{
"name": "import_contacts",
"arguments": {
"csv": "email,name\nada@example.net,Ada Lovelace\n",
"consent_basis": "Newsletter signups exported from Mailchimp (double opt-in)"
}
}list_contact_importsList contact imports
Campaigns: Recent CSV imports with their consent basis and row counts.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_contact_imports",
"arguments": {}
}bulk_update_contactsBulk 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
action | string | 예 | What to do. (one of tag, untag, add_to_list, remove_from_list, unsubscribe, delete) |
contact_ids | string[] | 아니요 | Contact IDs (ct_…). Use this or filter. (0–10000 items) |
filter | object | 아니요 | Everyone matching these list_contacts filters. Use this or contact_ids. |
filter.list_id | string | 아니요 | Members of this list. |
filter.status | string | 아니요 | 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.query | string | 아니요 | Email or name contains; * is an email wildcard. (max 200 chars) |
filter.tag | string | 아니요 | Has this tag. (max 60 chars) |
filter.source | string | 아니요 | How the contact was added. (one of form, api, import) |
filter.after | string | 아니요 | Signed up at or after. ISO 8601 date or date-time. (max 40 chars) |
filter.before | string | 아니요 | Signed up before. ISO 8601 date or date-time. (max 40 chars) |
filter.segment_id | string | 아니요 | Matches this segment. |
tags | string[] | 아니요 | For tag and untag. (0–50 items) |
list_id | string | 아니요 | For add_to_list and remove_from_list (lst_…). |
confirm_count | integer | 아니요 | For delete: the number of contacts that will be deleted, from the 409 response. (0–…) |
{
"name": "bulk_update_contacts",
"arguments": {
"action": "tag",
"tags": [
"october"
],
"filter": {
"list_id": "lst_123",
"status": "subscribed"
}
}
}list_tagsList contact tags
Campaigns: The workspace's contact tags, most used first, with how many contacts carry each (up to 500). Paginated.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_tags",
"arguments": {}
}list_contact_fieldsList 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_contact_fields",
"arguments": {}
}set_contact_fieldDefine 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_key | string | 예 | 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) |
label | string | 아니요 | Label shown in the dashboard. Defaults to the key. (max 80 chars) |
type | string | 아니요 | text (default), number, or date. (one of text, number, date) |
{
"name": "set_contact_field",
"arguments": {
"field_key": "plan",
"label": "Plan",
"type": "text"
}
}delete_contact_fieldDelete 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_key | string | 예 | 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) |
{
"name": "delete_contact_field",
"arguments": {
"field_key": "plan"
}
}list_segmentsList 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_segments",
"arguments": {}
}get_segmentGet a segment
Campaigns: One segment with its conditions and live count.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
segment_id | string | 예 | Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars) |
{
"name": "get_segment",
"arguments": {
"segment_id": "seg_123"
}
}preview_segmentPreview 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
match | string | 아니요 | all (default): every condition must match. any: at least one. (one of all, any) |
conditions | object[] | 아니요 | Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items) |
conditions[].field | string | 예 | 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[].key | string | 아니요 | Custom field key when field is field. (max 40 chars) |
conditions[].op | string | 예 | 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[].value | string,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. |
{
"name": "preview_segment",
"arguments": {
"match": "all",
"conditions": [
{
"field": "tag",
"op": "has",
"value": "VIP"
},
{
"field": "opened",
"op": "in_last_days",
"value": 90
}
]
}
}create_segmentCreate 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | Segment name. (max 120 chars) |
match | string | 아니요 | all (default): every condition must match. any: at least one. (one of all, any) |
conditions | object[] | 아니요 | Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items) |
conditions[].field | string | 예 | 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[].key | string | 아니요 | Custom field key when field is field. (max 40 chars) |
conditions[].op | string | 예 | 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[].value | string,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. |
{
"name": "create_segment",
"arguments": {
"name": "Engaged pro customers",
"conditions": [
{
"field": "fields.plan",
"op": "equals",
"value": "pro"
},
{
"field": "opened",
"op": "in_last_days",
"value": 90
}
]
}
}update_segmentUpdate 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_id | string | 예 | Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars) |
name | string | 아니요 | Segment name. (max 120 chars) |
match | string | 아니요 | all (default): every condition must match. any: at least one. (one of all, any) |
conditions | object[] | 아니요 | Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items) |
conditions[].field | string | 예 | 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[].key | string | 아니요 | Custom field key when field is field. (max 40 chars) |
conditions[].op | string | 예 | 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[].value | string,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. |
{
"name": "update_segment",
"arguments": {
"segment_id": "seg_123",
"name": "Pro customers"
}
}delete_segmentDelete 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_id | string | 예 | Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars) |
{
"name": "delete_segment",
"arguments": {
"segment_id": "seg_123"
}
}list_listsList contact lists
Campaigns: Contact lists with subscribed, pending, and unsubscribed counts and their hosted signup form settings.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_lists",
"arguments": {}
}create_listCreate 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | List name, shown on the signup form. (max 200 chars) |
description | string | 아니요 | Short description shown on the signup form. (max 500 chars) |
form_enabled | boolean | 아니요 | Publish the hosted signup form. |
form_from | string | 아니요 | Sender of signup confirmation emails, e.g. Acme <news@example.com>, on a verified domain. (max 320 chars) |
redirect_url | string | 아니요 | https page to open after a signup is confirmed. (max 500 chars) |
welcome | object | 아니요 | Welcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled. |
welcome.enabled | boolean | 아니요 | Send it. |
welcome.subject | string | 아니요 | Subject; merge tags allowed. (max 300 chars) |
welcome.html | string | 아니요 | HTML body; merge tags allowed. (max 500000 chars) |
welcome.markdown | string | 아니요 | Markdown body instead of html, rendered with the workspace design. (max 200000 chars) |
site | object | 아니요 | 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.enabled | boolean | 아니요 | Publish the site. |
site.slug | string,null | 아니요 | Address after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars) |
site.title | string,null | 아니요 | Site title. Defaults to the list name. (max 120 chars) |
site.description | string,null | 아니요 | Short description under the title. (max 300 chars) |
site.accent | string,null | 아니요 | Accent color, e.g. #0a7d4f. |
{
"name": "create_list",
"arguments": {
"name": "Product updates"
}
}get_listGet a list
Campaigns: One list with member counts and signup form settings.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
list_id | string | 예 | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
{
"name": "get_list",
"arguments": {
"list_id": "lst_123"
}
}update_listUpdate 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_id | string | 예 | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
name | string | 아니요 | New name. (max 200 chars) |
description | string | 아니요 | New description. (max 500 chars) |
form_enabled | boolean | 아니요 | Publish or unpublish the hosted signup form. |
form_from | string | 아니요 | Sender of signup confirmation emails, on a verified domain. (max 320 chars) |
redirect_url | string | 아니요 | https page to open after a signup is confirmed. (max 500 chars) |
welcome | object | 아니요 | Welcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled. |
welcome.enabled | boolean | 아니요 | Send it. |
welcome.subject | string | 아니요 | Subject; merge tags allowed. (max 300 chars) |
welcome.html | string | 아니요 | HTML body; merge tags allowed. (max 500000 chars) |
welcome.markdown | string | 아니요 | Markdown body instead of html, rendered with the workspace design. (max 200000 chars) |
site | object | 아니요 | 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.enabled | boolean | 아니요 | Publish the site. |
site.slug | string,null | 아니요 | Address after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars) |
site.title | string,null | 아니요 | Site title. Defaults to the list name. (max 120 chars) |
site.description | string,null | 아니요 | Short description under the title. (max 300 chars) |
site.accent | string,null | 아니요 | Accent color, e.g. #0a7d4f. |
{
"name": "update_list",
"arguments": {
"list_id": "lst_123",
"form_enabled": false
}
}delete_listDelete 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_id | string | 예 | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
{
"name": "delete_list",
"arguments": {
"list_id": "lst_123"
}
}add_list_contactsAdd 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_id | string | 예 | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
contact_ids | string[] | 아니요 | Contact IDs (ct_…). (0–500 items) |
emails | string[] | 아니요 | Contact email addresses. (0–500 items) |
{
"name": "add_list_contacts",
"arguments": {
"list_id": "lst_123",
"emails": [
"ada@example.net"
]
}
}remove_list_contactRemove a contact from a list
DESTRUCTIVE: remove one contact from a list. The contact and its status are kept. Part of Campaigns.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
list_id | string | 예 | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
contact_id | string | 예 | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "remove_list_contact",
"arguments": {
"list_id": "lst_123",
"contact_id": "ct_123"
}
}list_broadcastsList broadcasts
Campaigns: Newest-first broadcasts with their status. Paginated: the result includes pagination.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
status | string | 아니요 | Only broadcasts with this status. (one of draft, sending, sent, cancelled, failed) |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_broadcasts",
"arguments": {}
}create_broadcastCreate 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 아니요 | Internal name. Defaults to the subject. (max 200 chars) |
list_id | string | 아니요 | The list to send to (lst_…). |
from | string | 아니요 | Sender on a verified domain, e.g. Acme <news@example.com>. (max 320 chars) |
reply_to | string | 아니요 | Reply-To address. (max 320 chars) |
subject | string | 아니요 | Subject line; merge tags allowed. (max 998 chars) |
preview_text | string | 아니요 | Inbox preview text shown after the subject. (max 300 chars) |
html | string | 아니요 | HTML body; merge tags allowed and escaped. |
text | string | 아니요 | Plain-text body; merge tags allowed. |
template | object | 아니요 | A published hosted template instead of subject/html/text. Template variables are filled from the contact's name, email, and fields. |
template.id | string | 아니요 | |
template.key | string | 아니요 | |
template.version_id | string | 아니요 | |
markdown | string | 아니요 | 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) |
content | object,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. |
editor | string | 아니요 | Which editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks) |
audience | object | 아니요 | Who gets it, within the list. Subscribed, non-dormant members only. |
audience.segment_id | string,null | 아니요 | Only list members matching this segment (seg_…), or null for the whole list. |
audience.order | string | 아니요 | With a limit: signup (default) or engaged (most engaged first). (one of signup, engaged) |
audience.limit | integer,null | 아니요 | Send to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000) |
tracking | object | 아니요 | Open and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email. |
tracking.opens | boolean | 아니요 | Add an open pixel. |
tracking.clicks | boolean | 아니요 | Rewrite links to signed SendHQ redirects (the unsubscribe link never is). |
web | object | 아니요 | Publish this issue on the list's newsletter site (see create_list site) once it is sent. |
web.enabled | boolean | 아니요 | Publish it. |
web.slug | string,null | 아니요 | Issue address; defaults to the subject. (max 100 chars) |
web.pinned | boolean | 아니요 | Keep it at the top of the site. |
{
"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
}
}
}get_broadcastGet 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "get_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}update_broadcastEdit 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
name | string | 아니요 | Internal name. (max 200 chars) |
list_id | string | 아니요 | The list to send to. |
from | string | 아니요 | Sender on a verified domain. (max 320 chars) |
reply_to | string | 아니요 | Reply-To address. (max 320 chars) |
subject | string | 아니요 | 제목. (최대 998자) |
preview_text | string | 아니요 | Inbox preview text. (max 300 chars) |
html | string | 아니요 | HTML 본문. |
text | string | 아니요 | 일반 텍스트 본문. |
template | object,null | 아니요 | A published hosted template, or null to remove it. |
markdown | string | 아니요 | 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) |
content | object,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. |
editor | string | 아니요 | Which editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks) |
audience | object | 아니요 | Who gets it, within the list. Subscribed, non-dormant members only. |
audience.segment_id | string,null | 아니요 | Only list members matching this segment (seg_…), or null for the whole list. |
audience.order | string | 아니요 | With a limit: signup (default) or engaged (most engaged first). (one of signup, engaged) |
audience.limit | integer,null | 아니요 | Send to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000) |
tracking | object | 아니요 | Open and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email. |
tracking.opens | boolean | 아니요 | Add an open pixel. |
tracking.clicks | boolean | 아니요 | Rewrite links to signed SendHQ redirects (the unsubscribe link never is). |
web | object | 아니요 | Publish this issue on the list's newsletter site (see create_list site) once it is sent. |
web.enabled | boolean | 아니요 | Publish it. |
web.slug | string,null | 아니요 | Issue address; defaults to the subject. (max 100 chars) |
web.pinned | boolean | 아니요 | Keep it at the top of the site. |
{
"name": "update_broadcast",
"arguments": {
"broadcast_id": "bc_123",
"subject": "October product update"
}
}delete_broadcastDelete a draft broadcast
DESTRUCTIVE: permanently delete a draft broadcast. Broadcasts that were sent cannot be deleted. Part of Campaigns.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
broadcast_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "delete_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}send_broadcastSend 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
idempotency_key | string | 아니요 | Idempotency-Key 헤더(최대 200자). 이 요청을 그대로 재시도할 때만 재사용하세요. (최대 200자) |
{
"name": "send_broadcast",
"arguments": {
"broadcast_id": "bc_123",
"idempotency_key": "october-update"
}
}cancel_broadcastCancel 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "cancel_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}list_broadcast_recipientsList 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
status | string | 아니요 | Only recipients with this outcome. (one of queued, sending, sent, held, skipped, failed) |
activity | string | 아니요 | Only recipients who did this. (one of opened, clicked, not_opened, not_delivered, bounced, complained, unsubscribed) |
query | string | 아니요 | Recipient email contains this text. (max 200 chars) |
include | string | 아니요 | links adds the links each recipient clicked (implied by activity: clicked). (one of links) |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_broadcast_recipients",
"arguments": {
"broadcast_id": "bc_123",
"status": "failed"
}
}check_broadcastRun 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "check_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}send_broadcast_testSend 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
to | string[] | 아니요 | Test recipients (up to 5). (1–5 items) |
contact_id | string | 아니요 | Fill merge tags from this contact (ct_…). (max 320 chars) |
remember | boolean | 아니요 | Save to as the default test recipients. |
{
"name": "send_broadcast_test",
"arguments": {
"broadcast_id": "bc_123",
"to": [
"owner@example.com"
]
}
}schedule_broadcastSchedule 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
scheduled_at | string | 예 | 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) |
{
"name": "schedule_broadcast",
"arguments": {
"broadcast_id": "bc_123",
"scheduled_at": "2026-11-10T09:00:00Z"
}
}unschedule_broadcastUnschedule 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "unschedule_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}duplicate_broadcastDuplicate 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "duplicate_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}send_broadcast_to_moreSend 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
limit | integer | 예 | How many more people at most. (1–10000000) |
idempotency_key | string | 아니요 | Idempotency-Key 헤더(최대 200자). 이 요청을 그대로 재시도할 때만 재사용하세요. (최대 200자) |
{
"name": "send_broadcast_to_more",
"arguments": {
"broadcast_id": "bc_123",
"limit": 500,
"idempotency_key": "october-update-more-1"
}
}get_broadcast_reportGet 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_id | string | 예 | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "get_broadcast_report",
"arguments": {
"broadcast_id": "bc_123"
}
}get_newsletter_settingsGet 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.
매개변수 없음.
{
"name": "get_newsletter_settings",
"arguments": {}
}update_newsletter_settingsUpdate 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_address | string | 아니요 | Sender's postal address for the footer. Empty string removes it. (max 300 chars) |
design | object | 아니요 | Rendering design for Markdown and block content. |
design.accentColor | string,null | 아니요 | Hex color like #0a7d4f, or null for the default. |
design.font | string | 아니요 | Font family. (one of sans, serif, mono) |
design.align | string | 아니요 | Text alignment. (one of left, center) |
cleanup | object | 아니요 | List cleanup of readers who stopped opening. |
cleanup.enabled | boolean | 아니요 | Turn list cleanup on or off. |
cleanup.afterSends | integer | 아니요 | Broadcasts in a row without an open or click (3-50). (3–50) |
cleanup.quietDays | integer | 아니요 | Days without engagement (30-730). (30–730) |
cleanup.subject | string,null | 아니요 | Subject of the cleanup email; merge tags allowed. (max 200 chars) |
cleanup.body | string,null | 아니요 | Body text of the cleanup email. (max 2000 chars) |
cleanup.from | string,null | 아니요 | Sender on a verified domain. Defaults to the last sent broadcast's sender. (max 320 chars) |
test_recipients | string[] | 아니요 | Default addresses for send_broadcast_test (up to 5). (0–5 items) |
{
"name": "update_newsletter_settings",
"arguments": {
"postal_address": "Acme Inc., 1 Main St, Springfield",
"design": {
"accentColor": "#0a7d4f"
}
}
}get_campaign_overviewGet 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
days | integer | 아니요 | Window in days, 7 to 365. Defaults to 30. (7–365) |
{
"name": "get_campaign_overview",
"arguments": {
"days": 30
}
}list_uploaded_imagesList 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_uploaded_images",
"arguments": {}
}Automations, events, and sending limits
track_eventRecord 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
email | string | 예 | The contact's email address. (max 320 chars) |
event | string | 예 | What they did: a lowercase letter, then a-z, 0-9, and _ (e.g. checkout_started). Names starting email. are reserved. (max 64 chars) |
properties | object | 아니요 | 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_at | string | 아니요 | 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_key | string | 아니요 | 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) |
contact | object | 아니요 | Changes to the contact, applied with the event. |
contact.name | string | 아니요 | Display name. (max 200 chars) |
contact.fields | object | 아니요 | Custom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field. |
contact.timezone | string | 아니요 | IANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars) |
contact.locale | string | 아니요 | Language tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars) |
contact.consent_basis | string | 아니요 | 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) |
{
"name": "track_event",
"arguments": {
"email": "ada@example.net",
"event": "checkout_started",
"properties": {
"plan": "pro"
},
"dedupe_key": "checkout_8f3a"
}
}list_automationsList 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
domain | string | 아니요 | 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) |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_automations",
"arguments": {
"domain": "example.com"
}
}get_automationGet 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
{
"name": "get_automation",
"arguments": {
"automation_key": "checkout-recovery"
}
}create_automationCreate 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
key | string | 예 | Address of the automation: 1-63 characters of a-z, 0-9, and - (e.g. checkout-recovery). (max 63 chars) |
name | string | 예 | Name shown in the dashboard. (max 200 chars) |
audience_label | string | 아니요 | Who this is for, in plain words, e.g. Started checkout and left. (max 200 chars) |
goal_label | string | 아니요 | What converting means, in a word or two, e.g. paid. (max 80 chars) |
entry | object | 아니요 | 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.type | string | 예 | Entry type. (one of event, bucket, date_field, manual) |
entry.event | string | 아니요 | Event name for an event entry, e.g. checkout_started. |
entry.segment_id | string | 아니요 | Segment ID (seg_…) for a bucket entry. (max 128 chars) |
entry.field | string | 아니요 | Contact field key for a date_field entry. (max 40 chars) |
entry.reentry | string | 아니요 | Whether someone who finished may enter again. (one of never, after_end) |
exit_rules | object | 아니요 | 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_event | string,null | 아니요 | Event that counts as converting, e.g. payment_completed. |
exit_rules.no_goal | boolean | 아니요 | True when this automation deliberately has no goal. |
exit_rules.stop_events | string[] | 아니요 | Events that take a person out, e.g. ["account_closed"]. (0–20 items) |
exit_rules.attribution_days | integer | 아니요 | Days before the goal within which an email earns the conversion. Default 14. (1–90) |
settings | object | 아니요 | Per-automation settings. Omitted keys keep their value. |
settings.exempt_from_hold | boolean | 아니요 | 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_cap | integer,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_cap | integer,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_pct | number | 아니요 | Percent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100) |
settings.stale_days | integer | 아니요 | An email more than this many days overdue is skipped instead of sent late. Default 4. (1–365) |
settings.resume_after_days | integer | 아니요 | How long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365) |
position | integer | 아니요 | 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_name | string | 아니요 | Sender display name, e.g. Acme. (max 120 chars) |
from_address | string | 아니요 | Sender address on a verified workspace domain (see list_sending_identities). (max 320 chars) |
reply_to | string | 아니요 | Reply-To address. (max 320 chars) |
steps | object[] | 아니요 | The emails, in order. position defaults to the place in this list. (0–50 items) |
steps[].position | integer | 아니요 | Position of the email in the automation, 1 to 50. (1–50) |
steps[].subject | string | 아니요 | Subject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars) |
steps[].preheader | string | 아니요 | Inbox preview line. (max 300 chars) |
steps[].content | object | 아니요 | 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[].html | string | 아니요 | HTML body. The unsubscribe footer is added automatically. |
steps[].text | string | 아니요 | 일반 텍스트 본문. |
steps[].editor | string | 아니요 | 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_seconds | integer | 아니요 | 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_empty | string[] | 아니요 | 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_window | boolean | 아니요 | Send as soon as it is due, outside the workspace's sending hours too. The per-person limits still apply. |
{
"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>"
}
]
}
}update_automationEdit 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
name | string | 아니요 | Name shown in the dashboard. (max 200 chars) |
audience_label | string | 아니요 | Who this is for, in plain words, e.g. Started checkout and left. (max 200 chars) |
goal_label | string | 아니요 | What converting means, in a word or two, e.g. paid. (max 80 chars) |
entry | object | 아니요 | 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.type | string | 예 | Entry type. (one of event, bucket, date_field, manual) |
entry.event | string | 아니요 | Event name for an event entry, e.g. checkout_started. |
entry.segment_id | string | 아니요 | Segment ID (seg_…) for a bucket entry. (max 128 chars) |
entry.field | string | 아니요 | Contact field key for a date_field entry. (max 40 chars) |
entry.reentry | string | 아니요 | Whether someone who finished may enter again. (one of never, after_end) |
exit_rules | object | 아니요 | 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_event | string,null | 아니요 | Event that counts as converting, e.g. payment_completed. |
exit_rules.no_goal | boolean | 아니요 | True when this automation deliberately has no goal. |
exit_rules.stop_events | string[] | 아니요 | Events that take a person out, e.g. ["account_closed"]. (0–20 items) |
exit_rules.attribution_days | integer | 아니요 | Days before the goal within which an email earns the conversion. Default 14. (1–90) |
settings | object | 아니요 | Per-automation settings. Omitted keys keep their value. |
settings.exempt_from_hold | boolean | 아니요 | 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_cap | integer,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_cap | integer,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_pct | number | 아니요 | Percent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100) |
settings.stale_days | integer | 아니요 | An email more than this many days overdue is skipped instead of sent late. Default 4. (1–365) |
settings.resume_after_days | integer | 아니요 | How long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365) |
position | integer | 아니요 | 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_name | string | 아니요 | Sender display name, e.g. Acme. (max 120 chars) |
from_address | string | 아니요 | Sender address on a verified workspace domain (see list_sending_identities). (max 320 chars) |
reply_to | string | 아니요 | Reply-To address. (max 320 chars) |
{
"name": "update_automation",
"arguments": {
"automation_key": "checkout-recovery",
"name": "Checkout recovery",
"settings": {
"holdout_pct": 10
}
}
}delete_automationDelete 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
{
"name": "delete_automation",
"arguments": {
"automation_key": "checkout-recovery"
}
}set_automation_stepCreate 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
position | integer | 예 | Position of the email in the automation, 1 to 50. (1–50) |
template | string | 아니요 | 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) |
subject | string | 아니요 | Subject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars) |
preheader | string | 아니요 | Inbox preview line. (max 300 chars) |
content | object | 아니요 | 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. |
html | string | 아니요 | HTML body. The unsubscribe footer is added automatically. |
text | string | 아니요 | 일반 텍스트 본문. |
editor | string | 아니요 | 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_seconds | integer | 아니요 | 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_empty | string[] | 아니요 | 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_window | boolean | 아니요 | Send as soon as it is due, outside the workspace's sending hours too. The per-person limits still apply. |
{
"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>"
}
}delete_automation_stepRemove 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
position | integer | 예 | Position of the email in the automation, 1 to 50. (1–50) |
{
"name": "delete_automation_step",
"arguments": {
"automation_key": "checkout-recovery",
"position": 3
}
}set_automation_step_variantCreate 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
position | integer | 예 | Position of the email in the automation, 1 to 50. (1–50) |
locale | string | 예 | Language tag of the version, e.g. fr or pt-br. (max 35 chars) |
subject | string | 아니요 | Subject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars) |
preheader | string | 아니요 | Inbox preview line. (max 300 chars) |
content | object | 아니요 | 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. |
html | string | 아니요 | HTML body. The unsubscribe footer is added automatically. |
text | string | 아니요 | 일반 텍스트 본문. |
{
"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>"
}
}set_automation_statusTurn 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
status | string | 예 | on to start sending, off to stop. (one of on, off) |
{
"name": "set_automation_status",
"arguments": {
"automation_key": "checkout-recovery",
"status": "off"
}
}send_automation_test_emailSend 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
position | integer | 예 | Position of the email in the automation, 1 to 50. (1–50) |
locale | string | 아니요 | 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) |
sample | object | 아니요 | 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_run | boolean | 아니요 | Send nothing; return the email as the test would deliver it. |
{
"name": "send_automation_test_email",
"arguments": {
"automation_key": "checkout-recovery",
"position": 1
}
}send_automation_testSend 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
locale | string | 아니요 | 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) |
sample | object | 아니요 | 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. |
{
"name": "send_automation_test",
"arguments": {
"automation_key": "checkout-recovery"
}
}enroll_contactAdd 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
email | string | 예 | Email address of an existing contact. (max 320 chars) |
properties | object | 아니요 | 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_at | string | 아니요 | 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) |
{
"name": "enroll_contact",
"arguments": {
"automation_key": "checkout-recovery",
"email": "ada@example.net",
"properties": {
"plan": "pro"
}
}
}exit_contactTake 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
email | string | 예 | Email address of the contact. (max 320 chars) |
reason | string | 아니요 | Why, for the record (max 200 chars). Defaults to manual. (max 200 chars) |
{
"name": "exit_contact",
"arguments": {
"automation_key": "checkout-recovery",
"email": "ada@example.net",
"reason": "Asked support to stop"
}
}preview_automationPreview 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "preview_automation",
"arguments": {
"automation_key": "checkout-recovery"
}
}get_automations_overviewGet 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
from | string | 아니요 | First day of the report as a UTC date (YYYY-MM-DD), inclusive. |
to | string | 아니요 | Last day of the report as a UTC date (YYYY-MM-DD), inclusive. |
domain | string | 아니요 | 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) |
{
"name": "get_automations_overview",
"arguments": {
"from": "2026-10-20",
"to": "2026-11-18"
}
}get_automation_reportGet 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
from | string | 아니요 | First day of the report as a UTC date (YYYY-MM-DD), inclusive. |
to | string | 아니요 | Last day of the report as a UTC date (YYYY-MM-DD), inclusive. |
{
"name": "get_automation_report",
"arguments": {
"automation_key": "checkout-recovery"
}
}list_automation_peopleList 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
did | string | 아니요 | What the people did. Defaults to entered. (one of entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, waiting) |
step | integer | 아니요 | Only this email of the automation, by its position. (1–50) |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_automation_people",
"arguments": {
"automation_key": "checkout-recovery",
"did": "clicked"
}
}get_automation_personGet 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_key | string | 예 | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
contact_id | string | 예 | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "get_automation_person",
"arguments": {
"automation_key": "checkout-recovery",
"contact_id": "ct_123"
}
}get_sending_limitsGet 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.
매개변수 없음.
{
"name": "get_sending_limits",
"arguments": {}
}update_sending_limitsUpdate 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_emails | integer | 아니요 | Most automation emails one person may get in period_days. Default 2. (1–50) |
period_days | integer | 아니요 | The period max_emails applies to, in days. Default 7. (1–90) |
min_gap_hours | integer | 아니요 | Least time between two automation emails to one person, in hours. Default 44. (0–720) |
window_start | integer | 아니요 | First hour of the day emails may go out, local time (0-23). Default 9. (0–23) |
window_end | integer | 아니요 | Hour sending stops, local time (1-24); must be later than window_start. Default 18. (1–24) |
weekdays | integer[] | 아니요 | Days emails may go out: 0 = Sunday to 6 = Saturday. Default [1, 2, 3, 4, 5]. (1–7 items) |
default_timezone | string | 아니요 | IANA time zone used for contacts that have none, e.g. Europe/London. (max 64 chars) |
product_name | string | 아니요 | Your product's name, for {{ product_name }}. (max 120 chars) |
sender_name | string | 아니요 | Who the emails are from, for {{ sender_name }}. (max 120 chars) |
{
"name": "update_sending_limits",
"arguments": {
"max_emails": 3,
"min_gap_hours": 24,
"default_timezone": "Europe/London"
}
}list_automation_templatesList 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_automation_templates",
"arguments": {}
}get_automation_templateGet 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_id | string | 예 | 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) |
{
"name": "get_automation_template",
"arguments": {
"template_id": "welcome-note"
}
}use_automation_templateCreate 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_id | string | 예 | 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) |
key | string | 아니요 | 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) |
name | string | 아니요 | Name shown in the dashboard. Defaults to the template's own name. (max 200 chars) |
from_name | string | 아니요 | Sender display name, e.g. Acme. (max 120 chars) |
from_address | string | 아니요 | Sender address on a verified workspace domain (see list_sending_identities). (max 320 chars) |
reply_to | string | 아니요 | Reply-To address. (max 320 chars) |
{
"name": "use_automation_template",
"arguments": {
"template_id": "welcome-note",
"name": "Welcome",
"from_name": "Dana from Acme",
"from_address": "dana@example.com"
}
}list_eventsList 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
contact | string | 아니요 | Only this contact: a contact ID or an email address. (max 320 chars) |
name | string | 아니요 | Only this event, e.g. checkout_started. See list_event_names. (max 64 chars) |
from | string | 아니요 | Events from this UTC date (YYYY-MM-DD) or ISO 8601 date-time on. (max 40 chars) |
to | string | 아니요 | Events up to this UTC date (the whole day) or ISO 8601 date-time. (max 40 chars) |
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_events",
"arguments": {
"name": "checkout_started",
"from": "2026-11-01"
}
}list_event_namesList 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_event_names",
"arguments": {}
}list_connectionsList 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_connections",
"arguments": {}
}get_connectionGet 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_id | string | 예 | Connection ID, as returned by list_connections (e.g. acn_…). (max 128 chars) |
{
"name": "get_connection",
"arguments": {
"connection_id": "acn_123"
}
}create_connectionCreate 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.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | What to call it, e.g. Stripe. (max 80 chars) |
kind | string | 예 | stripe, dodo, or generic. (one of generic, stripe, dodo) |
consent_basis | string | 예 | 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_prefix | string | 아니요 | Put in front of every event name, e.g. stripe_. (max 32 chars) |
enabled | boolean | 아니요 | Defaults to true. Pass false to create it switched off. |
mapping | object | 아니요 | 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.email | string | 아니요 | Where the contact's email address is. (max 120 chars) |
mapping.event | string | 아니요 | Where the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars) |
mapping.event_name | string | 아니요 | One fixed event name, instead of event. (max 64 chars) |
mapping.time | string | 아니요 | Where the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars) |
mapping.id | string | 아니요 | Where a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars) |
mapping.keep | string[] | 아니요 | The fields to keep as event properties. Defaults to the top-level text, number, and boolean fields. (0–50 items) |
{
"name": "create_connection",
"arguments": {
"name": "Stripe",
"kind": "stripe",
"consent_basis": "Bought a plan on acme.com and accepted product emails"
}
}update_connectionChange 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_id | string | 예 | Connection ID, as returned by list_connections (e.g. acn_…). (max 128 chars) |
name | string | 아니요 | A new name. (max 80 chars) |
enabled | boolean | 아니요 | true: record what arrives. false: answer 404 and record nothing. |
consent_basis | string | 아니요 | 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_prefix | string | 아니요 | Put in front of every event name, e.g. stripe_. (max 32 chars) |
mapping | object | 아니요 | 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.email | string | 아니요 | Where the contact's email address is. (max 120 chars) |
mapping.event | string | 아니요 | Where the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars) |
mapping.event_name | string | 아니요 | One fixed event name, instead of event. (max 64 chars) |
mapping.time | string | 아니요 | Where the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars) |
mapping.id | string | 아니요 | Where a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars) |
mapping.keep | string[] | 아니요 | The fields to keep as event properties. Defaults to the top-level text, number, and boolean fields. (0–50 items) |
{
"name": "update_connection",
"arguments": {
"connection_id": "acn_123",
"enabled": false
}
}delete_connectionDelete 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_id | string | 예 | Connection ID, as returned by list_connections (e.g. acn_…). (max 128 chars) |
{
"name": "delete_connection",
"arguments": {
"connection_id": "acn_123"
}
}계정, 사용량, 분석, 키
get_account계정, 사용량, 결제 정보 조회
계정 소유자 이메일, 요금제/액세스 등급, 현재 기간의 수신자 전달 수(사용량 대비 할당량), 도메인 사용량 대비 한도, 첨부 파일 전송량, 평판 요약, 구독 상태, 공개된 요금제, 워크스페이스 수. 남은 할당량이나 체험판이 전달할 수 있는 대상(계정 이메일)을 확인할 때 사용하세요.
매개변수 없음.
{
"name": "get_account",
"arguments": {}
}get_account_diagnosticsDiagnose 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.
매개변수 없음.
{
"name": "get_account_diagnostics",
"arguments": {}
}get_analytics발송 분석 조회
최근 7일, 30일 또는 90일의 대시보드 분석: 발송/수신/전달/반송/차단/열람/클릭/스팸 신고 합계, 일별 타임라인, 상위 발신 도메인, 상위 제목.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
days | integer | 아니요 | 일 단위 기간: 7, 30(기본값) 또는 90. (다음 중 하나: 7, 30, 90) |
{
"name": "get_analytics",
"arguments": {
"days": 30
}
}list_api_keysAPI 키 메타데이터 목록 조회
API 키 이름, 비밀이 아닌 접두사, 마지막 사용 시각을 나열합니다. 읽기 전용입니다. 이 MCP 서버는 키를 만들거나 교체하거나 폐기할 수 없으며, 이는 사람이 대시보드에서 수행합니다. 페이지네이션: 결과에 pagination {offset, limit, returned, total?, has_more, next_offset}이 포함됩니다.
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
limit | integer | 아니요 | 페이지 크기. 기본값은 50입니다. (기본값 50; 1–200) |
offset | integer | 아니요 | 건너뛸 레코드 수. 이전 페이지의 pagination.next_offset을 사용하세요. (기본값 0; 0–…) |
{
"name": "list_api_keys",
"arguments": {}
}get_service_healthSendHQ 서비스 상태 확인
SendHQ API가 작동 중인지, 어떤 메일 제공업체가 활성화되어 있는지 확인합니다. 유효한 API 키가 필요하지 않습니다.
매개변수 없음.
{
"name": "get_service_health",
"arguments": {}
}API 지원 범위 목록
공개 API의 모든 작업과 이를 지원하는 도구입니다. 대시보드에서 사용자가 할 수 있고 API가 있는 모든 작업은 지원됩니다. 아래의 제외 항목은 의도적인 것입니다.
| 엔드포인트 | 도구 | 비고 |
|---|---|---|
| POST /emails | send_email | 이메일 한 통 발송 |
| POST /emails/batch | send_batch | 개별화된 메시지를 최대 100건까지 발송 |
| GET /emails | list_emails | 발신 및 수신 이메일 목록 조회 |
| GET /emails/:id | get_email | 이메일과 첨부 파일 조회 |
| PATCH /emails/:id | mark_email | 읽음, 보관, 스팸, 카테고리, 중요도 업데이트 |
| POST /emails/:id/labels | label_email | 이메일에 라벨 추가 또는 제거 |
| DELETE /emails/:id | delete_email | 보관 중인 이메일 삭제 |
| GET /emails/:id/events | list_email_events | 이메일의 전송 이벤트 목록 조회 |
| GET /threads/:id | get_thread | 대화를 시간순으로 조회 |
| GET /labels | list_labels | 메시지 수와 분류 규칙이 포함된 라벨 목록 조회 |
| POST /labels | create_label | 라벨 생성(자동 분류 규칙 선택 지정 가능) |
| GET /labels/:id | get_label | ID 또는 이름으로 라벨 조회 |
| PATCH /labels/:id | update_label | 라벨 이름 변경, 색상 변경 또는 버킷으로 전환 |
| DELETE /labels/:id | delete_label | 이메일은 삭제하지 않고 라벨만 삭제 |
| POST /labels/:id/rules | create_label_rule | 라벨에 자동 분류 규칙 추가 |
| DELETE /labels/:id/rules/:rule_id | delete_label_rule | 자동 분류 규칙 삭제 |
| POST /drafts | create_draft | 작성 화면 초안 생성 |
| GET /drafts | list_drafts | 작성 화면 초안 목록 조회 |
| GET /drafts/:id | get_draft | 초안과 첨부 파일 조회 |
| PUT /drafts/:id | update_draft | 초안 내용 교체 |
| DELETE /drafts/:id | delete_draft | 초안 폐기 |
| POST /drafts/:id/attachments | upload_attachment | 초안에 첨부 파일 업로드 |
| GET /attachments/:id | download_attachment | 비공개 첨부 파일 다운로드 |
| DELETE /attachments/:id | delete_attachment | 비공개 첨부 파일 삭제 |
| GET /sending-identities | list_sending_identities | 검증된 발신 ID 목록 조회 |
| GET /templates | list_templates | 호스팅 템플릿 목록 조회 |
| POST /templates | create_template | 호스팅 템플릿 생성 |
| GET /templates/:id | get_template | 초안, 릴리스, 사용 현황 조회 |
| PUT /templates/:id/draft | update_template_draft | 템플릿 초안 자동 저장 |
| POST /templates/:id/draft | create_template_draft | 게시된 릴리스에서 새 초안 생성 |
| POST /templates/:id/render | render_template | 서버가 실제로 출력하는 결과 렌더링 |
| POST /templates/:id/test | send_template_test | 테스트 스냅샷 발송 |
| POST /templates/:id/publish | publish_template | 변경 불가능한 템플릿 릴리스 게시 |
| POST /templates/:id/archive | archive_template | 템플릿 보관 처리 |
| POST /templates/:id/restore | restore_template | 보관된 템플릿 복원 |
| POST /domains | add_domain | 발신 도메인 추가 |
| GET /domains | list_domains | 도메인과 캐시된 DNS 상태 조회 |
| GET /domains/:id | get_domain | 도메인 설정 세부 정보 조회 |
| POST /domains/:id/verify | verify_domain | Refresh domain and DNS verification |
| POST /domains/:id/inbound/setup | setup_inbound | Provision inbound receiving |
| POST /domains/:id/inbound/verify | verify_inbound | 수신 MX 라우팅 검증 |
| DELETE /domains/:id | delete_domain | 도메인 삭제 |
| GET /dns/provider | get_dns_provider | 권한 있는 DNS 제공업체와 상대 레코드 호스트 감지 |
| GET /dns/domain-connect/connect | get_domain_connect_link | 원클릭 DNS 설정을 위한 Domain Connect 동의 링크 생성 |
| POST /inboxes | create_inbox | 수신 주소 생성 |
| GET /inboxes | list_inboxes | 수신 주소 목록 조회 |
| GET /inboxes/:id | get_inbox | 수신 주소 조회 |
| PATCH /inboxes/:id | update_inbox | 수신함 이름 변경, 활성화 또는 비활성화 |
| PUT /inboxes/:id/forwarding | set_inbox_forwarding | 수신함이 받은 메일을 다른 주소로 전달 |
| DELETE /inboxes/:id | delete_inbox | 메시지는 보관한 채 수신함 삭제 |
| GET /deliverability/stats | deliverability_stats | 최근 30일 전송 통계 조회 |
| GET /deliverability/reputation | list_sender_reputation | 정확한 발신 ID별 평판 상태 조회 |
| GET /deliverability/account | deliverability_account | Account delivery rates, daily ladder, and bounce trend |
| GET /deliverability/domains | deliverability_domains | Per-domain sent, delivered, hard and soft bounces, complaints, and failures |
| GET /deliverability/senders | deliverability_senders | Per-From-address delivery rates |
| POST /deliverability/score | score_email | Score an email's content before it is sent |
| GET /emails/:id/delivery | email_delivery | Delivery timeline for one email, with bounce and complaint reasons |
| GET /threads/:id/delivery | thread_delivery | Per-thread delivery counts and per-message failure reasons |
| GET /suppressions | list_suppressions | 워크스페이스의 발송 제외 목록 조회 |
| DELETE /suppressions/:email | remove_suppression | 해제 가능한 반송 발송 제외 항목 삭제 |
| GET /blocked-recipients | list_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 /contacts | list_contacts | List contacts |
| POST /contacts | create_contact | Add a contact with its consent basis |
| PUT /contacts | upsert_contact | Create or update a contact by email |
| POST /contacts/bulk | bulk_update_contacts | Tag, 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/:id | get_contact | Retrieve a contact by ID or email |
| PATCH /contacts/:id | update_contact | Update a contact's name, fields, or tags, or unsubscribe it |
| DELETE /contacts/:id | delete_contact | Delete a contact and its list memberships |
| POST /contact-imports | import_contacts | Import contacts from CSV |
| GET /contact-imports | list_contact_imports | List recent contact imports |
| GET /tags | list_tags | List contact tags with how many contacts carry each |
| GET /contact-fields | list_contact_fields | List custom contact field definitions |
| PUT /contact-fields/:key | set_contact_field | Define or change a custom contact field |
| DELETE /contact-fields/:key | delete_contact_field | Delete a custom field definition |
| GET /segments | list_segments | List saved segments with live counts |
| POST /segments | create_segment | Save a segment |
| POST /segments/preview | preview_segment | Count and sample the contacts that match unsaved conditions |
| GET /segments/:id | get_segment | Retrieve a segment and its live count |
| PATCH /segments/:id | update_segment | Rename a segment or change its conditions |
| DELETE /segments/:id | delete_segment | Delete a segment |
| GET /lists | list_lists | List contact lists with member counts |
| POST /lists | create_list | Create a list with an optional signup form, welcome email, and newsletter site |
| GET /lists/:id | get_list | Retrieve a list |
| PATCH /lists/:id | update_list | Rename a list or change its signup form, welcome email, or site |
| DELETE /lists/:id | delete_list | Delete a list without deleting its contacts |
| POST /lists/:id/contacts | add_list_contacts | Add existing contacts to a list |
| DELETE /lists/:id/contacts/:contact_id | remove_list_contact | Remove a contact from a list |
| GET /broadcasts | list_broadcasts | List broadcasts |
| POST /broadcasts | create_broadcast | Create a broadcast draft |
| GET /broadcasts/:id | get_broadcast | Retrieve a broadcast and its delivery totals |
| PATCH /broadcasts/:id | update_broadcast | Edit a draft broadcast |
| DELETE /broadcasts/:id | delete_broadcast | Delete a draft broadcast |
| GET /broadcasts/:id/checks | check_broadcast | Run the pre-send checks for a broadcast |
| POST /broadcasts/:id/test | send_broadcast_test | Send a test copy of a draft |
| POST /broadcasts/:id/schedule | schedule_broadcast | Schedule a draft to send later |
| POST /broadcasts/:id/unschedule | unschedule_broadcast | Unschedule a draft |
| POST /broadcasts/:id/duplicate | duplicate_broadcast | Copy a broadcast into a new draft |
| POST /broadcasts/:id/send | send_broadcast | Send a broadcast to its audience |
| POST /broadcasts/:id/send-more | send_broadcast_to_more | Send a sent broadcast to more of its audience |
| POST /broadcasts/:id/cancel | cancel_broadcast | Cancel a draft or sending broadcast |
| GET /broadcasts/:id/recipients | list_broadcast_recipients | List a broadcast's recipients, outcomes, and engagement |
| GET /broadcasts/:id/report | get_broadcast_report | Retrieve a broadcast's engagement report |
| GET /campaigns/overview | get_campaign_overview | Retrieve subscriber growth and recent broadcast performance |
| GET /newsletter-settings | get_newsletter_settings | Retrieve newsletter settings |
| PATCH /newsletter-settings | update_newsletter_settings | Change 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/images | list_uploaded_images | List recently uploaded images |
| POST /events | track_event | Record 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 /automations | list_automations | List automations with their 30-day totals |
| POST /automations | create_automation | Create an automation as a draft |
| GET /automations/:key | get_automation | Retrieve an automation with its emails |
| PATCH /automations/:key | update_automation | Edit an automation |
| DELETE /automations/:key | delete_automation | Delete an automation and its history |
| PUT /automations/:key/steps/:position | set_automation_step | Create or change one email of an automation |
| DELETE /automations/:key/steps/:position | delete_automation_step | Remove one email from an automation |
| PUT /automations/:key/steps/:position/variants/:locale | set_automation_step_variant | Create or change a language version of an email |
| POST /automations/:key/steps/:position/test | send_automation_test_email | Send one email of an automation to yourself as a test |
| POST /automations/:key/test | send_automation_test | Send every email of an automation to yourself as tests |
| POST /automations/:key/status | set_automation_status | Turn an automation on or off |
| POST /automations/:key/enroll | enroll_contact | Add a contact to an automation |
| POST /automations/:key/exit | exit_contact | Take a contact out of an automation |
| GET /automations/:key/preview | preview_automation | Dry run: what each person in an automation would get now |
| GET /automations/overview | get_automations_overview | Totals and a daily series across every automation |
| GET /automations/:key/report | get_automation_report | Results of one automation, with one row per email |
| GET /automations/:key/people | list_automation_people | List the people in an automation by what they did |
| GET /automations/:key/people/:contact_id | get_automation_person | One 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-settings | get_sending_limits | Retrieve the workspace's sending limits for automations |
| PUT /automation-settings | update_sending_limits | Change the workspace's sending limits for automations |
| GET /automation-library | list_automation_templates | List the template library: ready-made lifecycle emails |
| GET /automation-library/:id | get_automation_template | Read one template or set, with the email as it will look |
| POST /automation-library/:id/use | use_automation_template | Create a draft automation from a template or set |
| GET /events | list_events | List what contacts did, newest first |
| GET /events/names | list_event_names | List 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 /connections | list_connections | List the workspace's connections (incoming webhooks) |
| POST /connections | create_connection | Create 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/:id | get_connection | Retrieve a connection with its last deliveries |
| PATCH /connections/:id | update_connection | Change a connection or switch it on or off |
| DELETE /connections/:id | delete_connection | Delete 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 /account | get_account | API 키로 계정, 사용량, 결제 상태, 워크스페이스 수 조회 |
| GET /account/diagnostics | get_account_diagnostics | Diagnose sending and receiving problems in the workspace |
| GET /analytics | get_analytics | 7일, 30일 또는 90일 기간의 대시보드 발송 분석 조회 |
| GET /profile | get_account | GET /account의 세션 전용 대응 항목입니다. MCP 서버는 API 키 경로를 읽습니다. |
| POST /billing/checkout | 노출되지 않음 | 결제 변경은 설계상 세션 전용이며 대시보드에서 계정 소유자가 직접 수행해야 합니다. 결제 상태는 get_account로 읽을 수 있습니다. |
| POST /billing/cancel | 노출되지 않음 | 결제 변경은 설계상 세션 전용이며 대시보드에서 계정 소유자가 직접 수행해야 합니다. 결제 상태는 get_account로 읽을 수 있습니다. |
| POST /keys | 노출되지 않음 | 의도적으로 제외됨: 에이전트가 자격 증명을 발급하거나 파기해서는 안 됩니다. 키는 사람이 대시보드에서 관리합니다. |
| GET /keys | list_api_keys | API 키 메타데이터 목록 조회 |
| 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 deliveries | GET /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/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. |
| Upload editor images and export contacts as CSV | POST /uploads/images, 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). |
| Import an automation's send history and record events in bulk | POST /automations/:key/import-history, 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. |
| Move SendHQ's own win-back emails onto automations (backfill and comparison) | POST /automations/platform-backfill, GET /automations/platform-compare | Internal 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 address | 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. |
| Dry runs for a sample payload and for a set of events | POST /connections/test, 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. |
기계가 읽을 수 있는 카탈로그: /docs/mcp/tools.json(스키마, 어노테이션, 엔드포인트 매핑, 제외 항목). 이 페이지의 Markdown 버전: /docs/mcp.md. CLI가 설치되어 있으면 sendhq commands --format json이 같은 카탈로그를 출력합니다.