برای ایجنت‌های هوش مصنوعی

سرور MCP ‏SendHQ

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

142 toolsstdio transport, one command0 key-management tools
نصب و اتصال (Claude Code)
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

این سرور چیست

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

این یک سرور محلی stdio است که در فایل اجرایی CLI ‏sendhq تعبیه شده است. کلاینت MCP شما sendhq mcp را به‌عنوان یک پردازه فرزند اجرا می‌کند و از طریق stdin/stdout با JSON-RPC ارتباط برقرار می‌کند. هر فراخوانی ابزار به یک درخواست مستند به REST API ‏SendHQ در https://sendhq.cc/api/v1 تبدیل می‌شود که با کلید API فضای کاری شما احراز هویت شده است؛ بنابراین سرور MCP دقیقاً مجوزهای همان کلید را دارد و نه بیشتر.

  • 142 tools in 10 groups, generated from one catalog that is also published as tools.json.
  • JSON Schemaهای سخت‌گیرانه: آرگومان‌های ناشناخته، نوع‌های اشتباه و فیلدهای الزامی جاافتاده پیش از رسیدن هر چیزی به SendHQ، به‌صورت محلی رد می‌شوند.
  • خطاهای ساختاریافته با یک code پایدار، status ‏HTTP، یک explanation، یک remedy مشخص و اینکه آیا تلاش مجدد کمکی می‌کند یا نه.
  • هر ابزاری که ایمیل واقعی ارسال می‌کند یا داده‌ای را از بین می‌برد، این موضوع را در نخستین کلمات توضیح خود اعلام می‌کند و annotationهای ایمنی MCP دارد.
  • حالت --read-only همه ابزارهای ارسال و تغییردهنده را پنهان می‌کند.
  • هیچ چیزی لاگ نمی‌شود. stdout فقط پیام‌های پروتکل را حمل می‌کند؛ کلید API و محتوای پیام هرگز به هیچ لاگی نمی‌رسند.
این endpoint مستندات MCP نیست.SendHQ یک endpoint کوچک و فقط‌خواندنی MCP برای مستندات نیز در https://sendhq.cc/api/mcp میزبانی می‌کند (جستجوی قیمت‌ها و مستندات، بدون دسترسی به حساب). سروری که در این صفحه معرفی می‌شود، نسخه کامل و محدود به حساب است؛ به‌صورت محلی یا به‌عنوان connector میزبانی‌شده زیر اجرا می‌شود.

Use SendHQ in Claude, ChatGPT and Grok

بدون نیاز به نصب: SendHQ این سرور را با همان ابزارها به‌عنوان یک connector میزبانی‌شده در https://mcp.sendhq.cc/mcp نیز اجرا می‌کند. به‌جای چسباندن کلید، با حساب SendHQ خود وارد می‌شوید.

Claude

  1. Settings → Connectors را باز کنید و SendHQ را در فهرست پیدا کنید، یا Add custom connector را انتخاب کنید و https://mcp.sendhq.cc/mcp را بچسبانید.
  2. روی Connect کلیک کنید، وارد SendHQ شوید، دسترسی‌ها را بازبینی کنید و روی Allow کلیک کنید.
  3. از Claude بخواهید صندوق ورودی شما را بررسی کند، از دامنه تأییدشده‌تان ایمیل بفرستد یا یک برگشت ایمیل را توضیح دهد.

ChatGPT

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

Grok

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

Muse by Meta

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

تأیید و قطع اتصال

  • The request_feature tool sends a feature request to the SendHQ team with your account details, so we can follow up by email.
  • ابزارهایی که ایمیل واقعی ارسال می‌کنند یا داده حذف می‌کنند به همین صورت برچسب خورده‌اند. اینکه دستیار پیش از اجرا از شما بپرسد یا نه، برای هر ابزار در خود دستیار تنظیم می‌شود: در Claude، برای این ابزارها در Settings → Connectors → SendHQ گزینه Needs approval را انتخاب کنید.
  • connector کلید API مخصوص خود را دریافت می‌کند که به نام دستیار نام‌گذاری می‌شود (برای مثال “Claude (AI connector)”). برای قطع فوری اتصال، آن را در بخش API Keys حذف کنید.
  • این connector نمی‌تواند کلید API بسازد یا باطل کند یا صورتحساب را تغییر دهد. پیوست‌ها به‌صورت base64 ارسال و بازگردانده می‌شوند؛ هیچ دسترسی‌ای به فایل‌های محلی وجود ندارد.
  • Sending requires an active subscription. There is no free allowance, including mail to the account owner.

پرسش‌ها: postmaster@sendhq.cc. حریم خصوصی: sendhq.cc/privacy.

نصب

فایل اجرایی sendhq را نصب کنید (Linux، macOS و Windows روی x86-64 و arm64). نصب‌کننده checksum نسخه را بررسی می‌کند و فایل اجرایی را به‌طور پیش‌فرض در ~/.local/bin قرار می‌دهد.

macOS و Linux
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
Windows PowerShell
irm https://downloads.sendhq.cc/install.ps1 | iex
بررسی نصب
sendhq version
SENDHQ_API_KEY=re_your_key sendhq doctor

یک کلید API در داشبورد به نشانی https://sendhq.cc/app#/keys بسازید. سرور MCP نمی‌تواند کلید بسازد. تنها دستوری که سرور را اجرا می‌کند این است:

اجرای سرور stdio
SENDHQ_API_KEY=re_your_key sendhq mcp

معمولاً هرگز لازم نیست آن را دستی اجرا کنید: کلاینت MCP آن را راه‌اندازی می‌کند. اگر در ترمینال اجرا شود، منتظر JSON-RPC روی stdin می‌ماند.

پیکربندی کلاینت

Claude Code

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

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

برای در دسترس بودن در همه پروژه‌ها --scope user را اضافه کنید، یا --scope project را اضافه کنید تا در .mcp.json پروژه نوشته شود. برای یک .mcp.json مشترک، به‌جای commit کردن کلید، از متغیر محیطی به آن ارجاع دهید؛ Claude Code عبارت ${VAR} را در .mcp.json جایگذاری می‌کند.

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

OpenAI Codex

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

یا از خط فرمان: codex mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp.

Claude Desktop

فایل claude_desktop_config.json را ویرایش کنید (macOS: ~/Library/Application Support/Claude/، Windows: %APPDATA%\Claude\) و برنامه را دوباره راه‌اندازی کنید. برنامه‌های دسکتاپ PATH شل شما را به ارث نمی‌برند، پس از مسیر مطلق فایل اجرایی (which sendhq) استفاده کنید.

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

هر کلاینت MCP دیگر

یک سرور stdio با دستور sendhq، آرگومان‌های ["mcp"] (و به‌صورت اختیاری "--read-only") و متغیرهای محیطی زیر پیکربندی کنید. سرور از نسخه‌های پروتکل MCP ‏2024-11-05، 2025-03-26، 2025-06-18 و 2025-11-25 پشتیبانی می‌کند و initialize، ping، tools/list و tools/call را پیاده‌سازی می‌کند. نتایج ابزارها هم یک بلوک متنی JSON و هم structuredContent دارند.

smoke test خام stdio (با pipe به sendhq mcp)
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_service_health","arguments":{}}}

برای سرور محدود به حساب، انتقال HTTP میزبانی‌شده وجود ندارد. یک endpoint راه دور MCP با قابلیت نوشتن به OAuth برای هر کاربر نیاز دارد که SendHQ ارائه نمی‌کند؛ فایل اجرایی محلی کلید را روی همان ماشینی نگه می‌دارد که از قبل آن را در اختیار دارد.

متغیرهای محیطی و flagها

متغیر یا flagالزامیمعنا
SENDHQ_API_KEYبلهکلید API فضای کاری (re_…). همه ابزارها به‌جز get_service_health به آن نیاز دارند. بدون آن سرور همچنان اجرا می‌شود و هر فراخوانی یک auth_error ساختاریافته برمی‌گرداند که روش رفع مشکل را توضیح می‌دهد.
SENDHQ_API_BASE_URLخیرURL پایه API. پیش‌فرض https://sendhq.cc/api/v1. فقط برای استقرار محلی یا staging از آن استفاده کنید. SENDHQ_BASE_URL به‌عنوان نام مستعار قدیمی‌تر پذیرفته می‌شود.
SENDHQ_MCP_READ_ONLYخیر1، true یا yes مانند --read-only عمل می‌کند.
--read-onlyخیرفقط ابزارهایی را در اختیار بگذارید که نه ایمیل ارسال می‌کنند و نه وضعیت را تغییر می‌دهند. ابزارهای پنهان اگر با نام فراخوانی شوند نیز رد می‌شوند.
SENDHQ_PROFILE / --profileخیربه‌جای SENDHQ_API_KEY از کلیدی استفاده کنید که sendhq auth login در keyring سیستم‌عامل ذخیره کرده است. اگر هر دو وجود داشته باشند، متغیر محیطی اولویت دارد.

کلید فقط به‌صورت هدر Authorization: Bearer به URL پایه پیکربندی‌شده ارسال می‌شود. هرگز چاپ، لاگ، در خطاها تکرار یا در نتایج ابزارها گنجانده نمی‌شود.

مدل ایمنی برای ایجنت‌ها

  • Sends real email. send_email, send_batch, send_template_test, send_broadcast, send_broadcast_test, schedule_broadcast (at the scheduled time), and send_broadcast_to_more deliver mail to real people and consume delivery credits. Their descriptions start with SENDS REAL EMAIL. Call them only when the user explicitly asked for that specific message to be sent, with the recipients, sender, and content confirmed.
  • Destructive. delete_email, delete_draft, delete_attachment, delete_domain, delete_inbox, remove_suppression, the campaign deletes (delete_contact, delete_list, remove_list_contact, delete_broadcast, cancel_broadcast, delete_segment, delete_contact_field), and bulk_update_contacts are marked destructiveHint: true and their descriptions start with DESTRUCTIVE. Confirm with the user first. remove_suppression weakens a safety block and is appropriate only when a human confirms the address works again.
  • تغییر وضعیت می‌دهد. ساخت یا به‌روزرسانی پیش‌نویس‌ها، قالب‌ها، دامنه‌ها و صندوق‌های ورودی، انتشار قالب‌ها و آغاز تأیید، فضای کاری را تغییر می‌دهند اما ایمیلی ارسال نمی‌کنند.
  • فقط‌خواندنی. همه موارد دیگر readOnlyHint: true هستند و فراخوانی آزادانه آن‌ها امن است.
  • این سرور هرگز DNS را تغییر نمی‌دهد. add_domain رکوردهایی را برمی‌گرداند که یک انسان باید منتشر کند؛ get_domain_connect_link یک URL رضایت برمی‌گرداند که یک شخص باید آن را باز کند و نزد ارائه‌دهنده DNS خود تأیید کند.
  • این سرور هرگز صورتحساب را تغییر نمی‌دهد. get_account فقط پلن، میزان مصرف و وضعیت اشتراک را می‌خواند.
  • Sending requires an active subscription. There is no free allowance. Every send, including a test and a send to the account owner's own address, returns subscription_required (402) until a plan is active. Lapsed, cancelled, and past-due subscriptions are refused the same way. The owner chooses a plan in the dashboard (Profile & Billing) or at https://sendhq.cc/pricing. Unpaid workspaces can still verify domains, create keys, and read the workspace.
  • Accepted is not delivered. A successful send returns an ID; delivery, bounce, and complaint evidence arrives later in list_email_events. Never claim inbox placement or that a person read a message. Broadcast opens are estimates: privacy proxies and security scanners load images on their own, and requests that look automated are counted apart (machine in get_broadcast_report).
  • برای دور زدن توقف 423 به نشانی From دیگری تغییر ندهید و هرگز گیرندگانی را که لغو اشتراک کرده یا گزارش اسپم داده‌اند دوباره اضافه نکنید.

کلیدهای API خارج از محدوده‌اند

طبق طراحی، هیچ ابزاری برای ساخت، تغییر، چرخش، ابطال یا حذف کلیدهای API وجود ندارد. ایجنت نباید اعتبارنامه بسازد یا از بین ببرد. list_api_keys فقط نام‌ها، پیشوندهای غیرمحرمانه و زمان آخرین استفاده را برمی‌گرداند. مدیریت کلیدها در داشبورد و توسط انسانی که وارد شده باقی می‌ماند.

گردش‌کارها

1. اولین ارسال

  1. get_service_health در دسترس بودن API را تأیید می‌کند (بدون کلید هم کار می‌کند).
  2. get_account shows the plan (access.tier) and remaining quota. If there is no active plan, do not send: the call returns subscription_required.
  3. list_sending_identities نشانی‌های From قابل‌استفاده را فهرست می‌کند. اگر خالی بود، ابتدا گردش‌کار دامنه را انجام دهید.
  4. فرستنده، گیرنده، موضوع و متن را با کاربر تأیید کنید، سپس send_email را با یک idempotency_key فراخوانی کنید.
  5. list_email_events با id برگشتی، پس از گزارش ارائه‌دهنده (معمولاً چند ثانیه تا چند دقیقه) delivery، bounce، complaint یا reject را نشان می‌دهد.
اولین ارسال
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "SendHQ is connected",
    "text": "It works.",
    "idempotency_key": "first-send-2026-09-26"
  }
}

2. تأیید دامنه از ابتدا تا انتها

  1. add_domain with name: "example.com". The result includes the DNS records (DKIM CNAMEs, domain verification, SPF, recommended DMARC).
  2. get_dns_provider با domain_id ارائه‌دهنده DNS معتبر (authoritative) را تشخیص می‌دهد و host نسبی دقیقی را که باید برای هر رکورد نزد آن ارائه‌دهنده وارد شود برمی‌گرداند.
  3. If providers.domainConnect.available is true, get_domain_connect_link returns a consent URL. Give it to the human; nothing changes until they approve at the provider. Otherwise, give the human the records to publish. Never publish a second SPF record: merge SendHQ's SPF include (include:amazonses.com) into the existing v=spf1 value.
  4. verify_domain rechecks DNS and DKIM verification. Status moves through pending, checking, and propagating to verified. Poll verify_domain or get_domain every 30–60 seconds; DNS can take minutes to hours.
  5. وقتی status برابر verified شد، نشانی‌های دامنه در list_sending_identities ظاهر می‌شوند.

3. برگشت‌ها، گزارش‌های اسپم و فهرست توقف ارسال

  1. list_blocked_recipients همه نشانی‌های مسدودشده را همراه با دلیل (bounce، complaint، unsubscribe) و یک شمارش خلاصه برمی‌گرداند.
  2. list_suppressions موارد توقف ارسال ناشی از برگشت دائمی و گزارش اسپم را برمی‌گرداند؛ deliverability_stats نرخ‌های 30 روزه تحویل، برگشت و گزارش اسپم را می‌دهد؛ list_sender_reputation نشان می‌دهد کدام نشانی‌های From محدود یا متوقف شده‌اند.
  3. ارسالی که شامل گیرنده‌ای در فهرست توقف ارسال باشد با 422 recipient_suppressed شکست می‌خورد. آن گیرنده را حذف کنید و دوباره ارسال کنید.
  4. فقط وقتی انسانی تأیید کند که صندوق ایمیلی که برگشت خورده اکنون کار می‌کند، remove_suppression را فراخوانی کنید. موارد توقف ارسال ناشی از گزارش اسپم دائمی‌اند (409 complaint_suppression_locked).

4. دریافت ایمیل ورودی

  1. دامنه (اغلب یک زیردامنه مانند inbound.example.com) باید تأیید شده باشد.
  2. setup_inbound دریافت را راه‌اندازی می‌کند و یک رکورد MX برمی‌گرداند. یک انسان آن را منتشر می‌کند.
  3. verify_inbound را تا زمانی که status برابر ready شود فراخوانی کنید.
  4. create_inbox با domain_id و local_part (برای مثال support) نشانی support@inbound.example.com را می‌سازد.
  5. list_emails را با direction: "in" و unread: true (و به‌صورت اختیاری inbox_id) به‌طور دوره‌ای فراخوانی کنید. پیام را با get_email، مکالمه آن را با get_thread و پیوست‌ها را با download_attachment بخوانید و با mark_email (read: true) آن را رسیدگی‌شده علامت بزنید.
  6. با 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. عیب‌یابی شکست تحویل

  1. پیام را پیدا کنید: list_emails با direction: "out" و to یا query، یا get_email اگر شناسه را دارید. status: failed یعنی SendHQ یا ارائه‌دهنده آن را هنگام ارسال رد کرده است؛ خطای ثبت‌شده در ایمیل دلیل آن را توضیح می‌دهد.
  2. list_email_events: bounce (دائمی یا گذرا، همراه با پیام تشخیصی ارائه‌دهنده)، complaint، reject یا delivery. نبود رویداد یعنی ارائه‌دهنده هنوز گزارشی نداده است؛ صبر کنید و دوباره بررسی کنید.
  3. If the send call itself failed, read the error code: subscription_required → the owner activates a plan; sender_domain_unverified → finish domain verification; recipient_suppressed → the address hard-bounced or complained before; sender_paused → inspect list_sender_reputation; account_paused → the workspace is paused for review, read the rates; daily_limit_reached → wait until midnight UTC; quota_exhausted → get_account usage.
  4. get_domain بررسی می‌کند که DKIM، SPF و DMARC همچنان منتشر شده باشند؛ deliverability_stats نشان می‌دهد مشکل مربوط به یک پیام است یا یک روند.
  5. آنچه را شواهد نشان می‌دهند گزارش کنید. رویداد delivery یعنی سرور گیرنده پیام را پذیرفته است، نه اینکه به صندوق ورودی رسیده یا خوانده شده است.

7. مالکیت یک bucket کاری (برچسب‌ها)

  1. create_label را با name (برای مثال Agent/Orders) و skip_inbox: true فراخوانی کنید. این کار برچسب را به یک bucket تبدیل می‌کند: ایمیل دریافتی‌ای که این برچسب را بگیرد بایگانی می‌شود، پس فقط در آن برچسب نمایش داده می‌شود و هرگز در صندوق ورودی انسان نمی‌آید.
  2. ایمیل‌های کاری را با send_email (یا send_batch) و labels: ["Agent/Orders"] ارسال کنید. پاسخ‌ها به آن مکالمه به‌طور خودکار برچسب را به ارث می‌برند و از صندوق ورودی عبور نمی‌کنند.
  3. برای ایمیل‌هایی که خارج از مکالمه‌های شما آغاز می‌شوند، یک قانون بایگانی اضافه کنید: create_label_rule با inbox_id (یک نشانی اختصاصی مانند orders@…)، from، to یا subject. برای بایگانی ایمیل‌هایی که قبلاً دریافت شده‌اند، apply_to_existing: true را ارسال کنید.
  4. کار با bucket: list_emails با label: "Agent/Orders"، direction: "in" و unread: true؛ با get_email یا get_thread بخوانید، با send_email و reply_to_email_id پاسخ دهید و پس از رسیدگی mark_email را با read: true فراخوانی کنید.
  5. یک پیام سرگردان را با label_email (add / remove) وارد یا خارج کنید. افزودن برچسب bucket به یک پیام دریافتی، آن را بایگانی هم می‌کند.
  6. به‌صورت اختیاری، set_inbox_forwarding یک نسخه از هر چیزی را که یک نشانی دریافت می‌کند به صندوق ایمیل دیگری می‌فرستد (مقصد ابتدا از طریق ایمیل تأیید می‌کند).
ارسال در یک bucket
{
  "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. پیوست‌ها و قالب‌ها

در یک پلن پولی، حداکثر 10 فایل را با attachments در send_email پیوست کنید (هر کدام به content_base64 یا یک file_path محلی نیاز دارد؛ filename به‌طور پیش‌فرض نام پایه فایل است). برای قالب‌های میزبانی‌شده: create_template → update_template_draft → render_template برای پیش‌نمایش با داده نمونه ← send_template_test (یک ایمیل آزمایشی واقعی می‌فرستد) ← publish_template، سپس با send_email یا send_batch و با استفاده از template: {key, data} و دقیقاً یک گیرنده to ارسال کنید.

9. Send a newsletter

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

10. Run an automation

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

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

11. See what came in, and connect another system

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

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

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

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

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

نتایج، صفحه‌بندی و خطاها

فراخوانی موفق، شیء JSON پاسخ API را به‌صورت 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 (فهرست موارد نقض schema برای invalid_arguments) و idempotent_replayed (بخش idempotency را ببینید).

idempotency

send_email و send_batch پارامتر idempotency_key (حداکثر 200 کاراکتر) را می‌پذیرند که به‌صورت هدر Idempotency-Key ارسال می‌شود. برای هر پیام منطقی یک کلید پایدار بسازید، برای مثال invoice-4812-receipt.

  • تلاش مجدد باید از همان کلید و بدنه درخواست کاملاً یکسان استفاده کند. همان کلید با هر تغییری (گیرنده، موضوع، متن، هدر، داده قالب، حتی مقادیر آرگومان‌ها) 409 idempotency_conflict برمی‌گرداند.
  • همان کلید، همان بدنه و درخواست اصلی تمام‌شده: SendHQ نتیجه ذخیره‌شده را بدون ارسال مجدد برمی‌گرداند. این روش امن تلاش مجدد پس از timeout یا network_error است.
  • همان کلید در حالی که درخواست اصلی هنوز در حال اجراست: 409 idempotency_in_progress که پس از کمی صبر قابل تلاش مجدد است.
  • یک پیام منطقی جدید به کلید جدید نیاز دارد.
  • شکست‌های ذخیره‌شده نیز بازپخش می‌شوند. اگر تلاش اول شکست خورده باشد، تلاش مجدد با همان کلید همان شکست را با idempotent_replayed: true و retryable: false برمی‌گرداند. با list_emails (direction: out) مطمئن شوید چیزی ارسال نشده، علت را برطرف کنید و سپس با یک کلید جدید ارسال کنید.
  • سرور هرگز به‌طور خودکار یک POST را دوباره تلاش نمی‌کند. فقط فراخوانی‌های فقط‌خواندنی GET به‌طور خودکار دوباره تلاش می‌شوند (حداکثر 3 تلاش در خطاهای شبکه، 429 و 5xx).
  • send_email با attachments درون‌خطی نمی‌تواند idempotency_key بگیرد، چون چند درخواست را اجرا می‌کند. برای ارسال پیوست به‌صورت امن برای تلاش مجدد: create_draft → upload_attachment → send_email با draft_id و idempotency_key.
ارسال امن برای تلاش مجدد (در صورت timeout دقیقاً تکرار کنید)
{
  "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 یک تحویل حساب می‌شود. get_account → usage.recipientDeliveries را در برابر usage.emailQuotaMonth ببینید.
  • تعداد گیرندگان روزانه برای هر نشانی From مشخص که وضعیت اعتبار آن فرستنده تعیین می‌کند (list_sender_reputation → dailyLimit، به‌طور پیش‌فرض 2,000 در پلن‌های پولی).
  • Subscription: sending is refused with subscription_required until a paid plan is active. There is no free or trial allowance.
  • Workspace daily ladder on paid plans: 1,000 recipients on day one, then 2,000, 3,000, 5,000, 8,000, 12,000, 18,000, 25,000, 35,000, 45,000, and 50,000. A step is gained after a UTC day that used at least half the cap with healthy 7-day feedback. A high rate demotes once per incident, not every day the rate stays high. See get_account → sendingLimit. Over the cap: daily_limit_reached, not queued, retry after resets_at (midnight UTC), not on a short backoff.
  • Hourly pace: about one tenth of the day's cap each UTC hour (100 on day one). hourly_limit_reached waits until the next UTC hour.
  • New domains: a sending domain less than 30 days old may send at most 500 Gmail recipients a day (gmail_recipient_limit), on any ladder rung. gmail_rate_limited means Gmail returned 4.7.28; wait until resets_at and keep sending to other providers.
  • پیوست‌ها: حداکثر 10 فایل و 10 MB برای هر پیام؛ در پلن‌های پولی 10 GB انتقال پیوست وزن‌دهی‌شده بر اساس گیرنده در ماه.
  • برای هر درخواست: To + Cc + Bcc حداکثر 100 نشانی؛ send_batch حداکثر 100 پیام.
  • قطع‌کننده مدار اعتبار: در یک بازه متحرک 7 روزه، برگشت‌ها یا گزارش‌های اسپم بیش از آستانه، یک نشانی From را محدود یا متوقف می‌کنند (423 sender_paused). پس از کاهش نرخ‌ها، به‌طور خودکار بازیابی می‌شود.

quota_exhausted تا زمان بازنشانی دوره یا تغییر پلن قابل تلاش مجدد نیست. rate_limited پس از retry_after_seconds قابل تلاش مجدد است؛ برای ارسال‌ها با همان idempotency_key و بدنه یکسان دوباره تلاش کنید.

فهرست خطاها

code پایدار است؛ منطق برنامه را بر اساس آن بنویسید، نه بر اساس message.

codeHTTPتلاش مجدد؟معنا و اقدام لازم
invalid_arguments—خیرآرگومان‌ها به‌صورت محلی از JSON Schema ابزار عبور نکردند؛ چیزی به SendHQ نرسید. فیلدهای فهرست‌شده در problems را اصلاح کنید.
auth_error401خیرکلید API وجود ندارد، باطل شده یا اشتباه است. SENDHQ_API_KEY را برای پردازه سرور تنظیم کنید؛ کلیدها را یک انسان در داشبورد می‌سازد.
subscription_required402خیرNo active subscription. Nothing is sent, including to the account owner. The owner chooses a plan. Do not retry until then.
payment_required402خیراین قابلیت به پلن پولی نیاز دارد (برای مثال پیوست‌ها). بدون آن ارسال کنید یا پلن را ارتقا دهید.
sender_domain_not_owned403خیردامنه From در این فضای کاری نیست. از list_sending_identities یا add_domain استفاده کنید.
sender_domain_unverified403خیردامنه From هنوز تأیید نشده است. get_domain، انتشار رکوردهای جاافتاده، verify_domain.
domain_limit_reached403خیربه سقف تعداد دامنه پلن رسیده‌اید. یک دامنه بلااستفاده را (با تأیید) حذف کنید یا پلن را ارتقا دهید.
marketing_not_enabled403خیرکلاس marketing برای این دامنه یا پلن فعال نیست. فقط در صورتی از transactional استفاده کنید که پیام واقعاً تراکنشی باشد.
forbidden403خیرسیاست‌ها اجازه این عملیات را نمی‌دهند. درخواست را اصلاح کنید.
not_found404خیراین شناسه در این فضای کاری نیست. منبع را فهرست کنید تا شناسه درست را پیدا کنید؛ قالب‌های بایگانی‌شده را ابتدا بازیابی کنید.
idempotency_conflict409خیرکلید با بدنه متفاوتی دوباره استفاده شده است. دقیقاً درخواست اصلی را دوباره ارسال کنید یا برای پیام جدید از کلید جدید استفاده کنید.
idempotency_in_progress409بلهدرخواست اصلی هنوز در حال اجراست. صبر کنید، سپس با همان کلید و بدنه دوباره تلاش کنید.
revision_conflict409خیرپیش‌نویس قالب از زمانی که آن را خواندید تغییر کرده است. get_template، ادغام، ذخیره دوباره.
complaint_suppression_locked409خیرگیرنده گزارش اسپم داده است. هرگز دوباره به او ایمیل نزنید.
inbound_not_ready409خیردریافت ایمیل ورودی آماده نیست. setup_inbound، انتشار MX، verify_inbound.
conflict409خیرمنبع از قبل وجود دارد یا در وضعیت نادرستی است. آن را بخوانید و اصلاح کنید.
attachments_too_large413خیربیش از 10 فایل یا 10 MB. پیوست‌ها را حذف یا کوچک کنید.
recipient_suppressed422خیریک گیرنده پیش‌تر برگشت دائمی خورده یا گزارش اسپم داده است. او را حذف کنید؛ list_blocked_recipients را ببینید.
recipient_unsubscribed422خیریک گیرنده اشتراک ایمیل‌های بازاریابی را لغو کرده است. او را برای همیشه حذف کنید.
validation_failed422خیرمحتوا رد شد، برای مثال داده قالبی که قرارداد متغیرها را نقض می‌کند. ورودی را اصلاح کنید.
sender_paused423خیراین نشانی From توسط قطع‌کننده مدار 7 روزه برگشت/گزارش اسپم متوقف شده است. ارسال را متوقف کنید، فهرست را اصلاح کنید و منتظر بازیابی خودکار بمانید.
account_paused423خیرWorkspace paused for a deliverability review. The body has the measured rate and the limit when the pause was for bounces or complaints. Do not send until it is restored.
quota_exhausted429خیرMonthly allowance, per-sender daily limit, or attachment transfer. Not the workspace daily ladder. Check get_account; wait for that limit to reset or upgrade.
daily_limit_reached429after resetWorkspace daily ladder. Not a short backoff. Wait until resets_at (midnight UTC). The message was not queued.
hourly_limit_reached429after resetHourly pace (about a tenth of the day's cap). Wait until the next UTC hour. Not a short backoff.
gmail_recipient_limit429after reset500 Gmail recipients a day for a sending domain under 30 days old, on any ladder rung. Wait until midnight UTC. Not queued.
gmail_rate_limited429after resetGmail returned 4.7.28 for this domain. Wait until resets_at. Other providers keep sending.
rate_limited429بلهSlow down; wait retry_after_seconds. This is not a daily, hourly, or Gmail cap.
server_error5xxبلهخطای موقت SendHQ یا ارائه‌دهنده. با backoff دوباره تلاش کنید؛ ارسال‌ها با همان کلید و بدنه. اگر idempotent_replayed برابر true است، پس از اطمینان از اینکه چیزی ارسال نشده، از کلید جدید استفاده کنید.
network_error—بلهدرخواست یا پاسخ از دست رفت. دوباره تلاش کنید؛ برای ارسال‌ها، همان idempotency_key این کار را امن می‌کند.
invalid_request400خیردرخواست نادرست است. message را بخوانید و آن را اصلاح کنید.
tool_error—خیرخطای محلی درون سرور MCP (برای مثال یک file_path غیرقابل‌خواندن). message را بخوانید.

مرجع ابزارها

هر ابزار همراه با کلاس ایمنی، endpoint ‏REST که فراخوانی می‌کند، پارامترها، ساختار خروجی و یک شیء params نمونه برای tools/call. پارامترها دقیق‌اند: سرور هر چیزی را که فهرست نشده باشد رد می‌کند.

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

ایمیل‌ها و رشته‌های گفتگو

ارسال ایمیل واقعیsend_email
POST /emails

ارسال یک ایمیل

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.

پارامترنوعالزامیتوضیح
fromstringبلهفرستنده، مثلاً Acme <hello@example.com>. دامنه باید در این فضای کاری تأیید شده باشد (list_sending_identities را ببینید). (حداکثر 998 کاراکتر)
tostring[]بلهگیرندگان. هر مورد یک نشانی است، به‌صورت اختیاری همراه با نام نمایشی. مجموع to+cc+bcc حداکثر 100 است؛ هر مقصد یک اعتبار تحویل مصرف می‌کند. (1 تا 100 مورد)
ccstring[]خیرگیرندگان رونوشت (Cc). (0 تا 100 مورد)
bccstring[]خیرگیرندگان رونوشت مخفی (Bcc). (0 تا 100 مورد)
subjectstringخیرموضوع ایمیل. هنگام ارسال با قالب آن را حذف کنید. (حداکثر 998 کاراکتر)
textstringخیرمتن ساده. text، html یا template را ارائه دهید.
htmlstringخیربدنه HTML. SendHQ آن را پاک‌سازی می‌کند و وقتی text حذف شده باشد، متن را از آن استخراج می‌کند.
reply_tostringخیرنشانی Reply-To.
headersobjectخیرهدرهای سفارشی امن اضافی (با مقادیر رشته‌ای)، مثلاً {"X-Entity-Ref-ID": "123"}. هدرهای مسیریابی مانند From/To/Message-ID را SendHQ کنترل می‌کند.
message_classstringخیرtransactional (پیش‌فرض) یا marketing. marketing به پلن یا دامنه‌ای با قابلیت بازاریابی نیاز دارد و مدیریت لغو اشتراک را اضافه می‌کند. (یکی از transactional، marketing)
reply_to_email_idstringخیرپاسخ درون یک مکالمه موجود: شناسه em_… پیامی که به آن پاسخ داده می‌شود. SendHQ هدرهای In-Reply-To/References و رشته گفتگو را تنظیم می‌کند.
thread_idstringخیرشناسه صریح رشته گفتگویی که پیام باید زیر آن ثبت شود.
draft_idstringخیرپیوست‌های یک پیش‌نویس ذخیره‌شده (dr_…) را همراه این پیام ارسال کنید. پیش‌نویس پس از ارسال موفق حذف می‌شود.
templateobjectخیربه‌جای html/text خام، یک قالب میزبانی‌شده منتشرشده ارسال کنید. دقیقاً به یک گیرنده to و بدون cc/bcc نیاز دارد؛ موضوع را قالب تعیین می‌کند. دست‌کم یکی از این موارد را ارائه دهید: id، key.
template.idstringخیرشناسه قالب (tmpl_…). id یا key را ارائه دهید.
template.keystringخیرکلید قالب مانند account-welcome. id یا key را ارائه دهید.
template.version_idstringخیرشناسه اختیاری نسخه منتشرشده (tmplv_…). پیش‌فرض، نسخه منتشرشده فعلی است.
template.dataobjectخیرمقادیر متغیرهای نوع‌دار قالب.
labelsstring[]خیرنام برچسب‌ها یا شناسه‌های lbl_… که این پیام باید زیر آن‌ها بایگانی شود. نام‌های ناشناخته ایجاد می‌شوند. پاسخ‌های درون مکالمه برچسب‌ها را به ارث می‌برند و برچسب bucket ‏(skip_inbox) این پاسخ‌ها را از صندوق ورودی دور نگه می‌دارد. حداکثر 10. (0 تا 10 مورد)
idempotency_keystringخیرهدر Idempotency-Key (حداکثر 200 کاراکتر). فقط برای تلاش مجدد همین درخواست دقیق دوباره از آن استفاده کنید. (حداکثر 200 کاراکتر)
attachmentsobject[]خیرفایل‌هایی که باید پیوست شوند (حداکثر 10 فایل، مجموعاً 10 MB). هر کدام به content_base64 (همراه با filename) یا یک file_path محلی نیاز دارد. (0 تا 10 مورد) دست‌کم یکی از این موارد را ارائه دهید: content_base64، file_path.
attachments[].filenamestringخیرنام فایلی که به گیرنده نمایش داده می‌شود. همراه با content_base64 الزامی است؛ پیش‌فرض آن نام پایه file_path است. (حداکثر 255 کاراکتر)
attachments[].content_typestringخیرنوع MIME، مثلاً application/pdf. پیش‌فرض application/octet-stream است.
attachments[].content_base64stringخیرمحتوای فایل با base64 استاندارد.
attachments[].file_pathstringخیرمسیر مطلق یک فایل محلی که پردازه سرور MCP بتواند آن را بخواند.
خروجی{id: em_…, providerMessageId, threadId, templateId, templateVersionId, isTest}. پذیرش به معنای تحویل نیست: با list_email_events پیگیری کنید.
نمونه params برای tools/call
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "Your export is ready",
    "text": "Download it from your dashboard.",
    "idempotency_key": "export-ready-42"
  }
}
ارسال ایمیل واقعیsend_batch
POST /emails/batch

ارسال دسته‌ای ایمیل‌های شخصی‌سازی‌شده

SENDS REAL EMAIL (ایمیل واقعی ارسال می‌کند). 1 تا 100 پیام مستقل را در یک درخواست ارسال کنید (برای شخصی‌سازی قالب به‌ازای هر گیرنده از این استفاده کنید). هر مورد همان ساختار send_email را دارد (بدون attachments/idempotency_key). موارد به‌صورت جداگانه موفق یا ناموفق می‌شوند: HTTP 207 یعنی موفقیت جزئی؛ هر data[i].ok و data[i].error را بررسی کنید. یک idempotency_key کل بدنه دسته را پوشش می‌دهد.

پارامترنوعالزامیتوضیح
emailsobject[]بلهپیام‌هایی که باید ارسال شوند. (1 تا 100 مورد) دست‌کم یکی از این موارد را ارائه دهید: html، text، template.
idempotency_keystringخیرIdempotency-Key برای کل دسته (حداکثر 200 کاراکتر). (حداکثر 200 کاراکتر)
خروجی{data: [{index, ok, id?, error?: {message, status}}], count, successful, failed}.
نمونه params برای tools/call
{
  "name": "send_batch",
  "arguments": {
    "emails": [
      {
        "from": "Acme <hello@example.com>",
        "to": [
          "owner@example.com"
        ],
        "template": {
          "key": "account-welcome",
          "data": {
            "first_name": "Asha"
          }
        }
      }
    ],
    "idempotency_key": "welcome-batch-2026-09-26"
  }
}
فقط‌خواندنیlist_emails
GET /emails

فهرست و جستجوی ایمیل‌ها

ایمیل‌های ارسالی (direction: out) و دریافتی (direction: in) را از جدیدترین به قدیمی‌ترین همراه با فیلترها فهرست کنید. ایمیل‌های دریافتی دسته‌بندی می‌شوند: صندوق ورودی انسان را با direction: in، archived: false، category: primary بخوانید؛ با important: true اولویت‌بندی کنید؛ اسپم پنهان است مگر با category: spam یا include_spam: true. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
directionstringخیرin برای دریافتی، out برای ارسالی. (یکی از in، out)
statusstringخیرفیلتر وضعیت، مثلاً queued، sent، delivered، bounced، complained، failed.
domainstringخیرفقط پیام‌های این دامنه، یا فهرستی از دامنه‌ها که با کاما جدا شده‌اند (تطابق با هر کدام).
inbox_idstringخیرفقط پیام‌هایی که این صندوق ورودی (inb_…) دریافت کرده است.
labelstringخیرفقط پیام‌هایی که این برچسب را دارند: شناسه برچسب lbl_… یا نام دقیق آن، یا فهرستی جداشده با کاما (تطابق با هر کدام). برای دیدن پوشه‌ها از list_labels استفاده کنید.
archivedbooleanخیرfalse = نمای صندوق ورودی (ایمیل‌های دریافتی بایگانی‌نشده)، true = فقط بایگانی‌شده‌ها. برای همه ایمیل‌ها آن را حذف کنید.
categorystringخیرprimary (افراد)، updates (خبرنامه‌ها، انبوه، خودکار) یا spam؛ یا فهرستی جداشده با کاما. اسپم پنهان است مگر اینکه درخواست شود.
importantbooleanخیرtrue = فقط پیام‌هایی که مهم علامت خورده‌اند (پاسخ به مکالمه‌هایی که شما آغاز کرده‌اید و فرستندگانی که مهم علامت خورده‌اند).
include_spambooleanخیراسپم را در نتایج بگنجانید (برای جستجو در همه پوشه‌ها).
fromstringخیرنشانی فرستنده شامل این مقدار باشد.
tostringخیرنشانی گیرنده شامل این مقدار باشد.
unreadbooleanخیرtrue = فقط خوانده‌نشده‌ها، false = فقط خوانده‌شده‌ها.
afterstringخیرمهر زمانی ISO-8601؛ فقط پیام‌هایی که پس از آن ایجاد شده‌اند. (date-time)
beforestringخیرمهر زمانی ISO-8601؛ فقط پیام‌هایی که پیش از آن ایجاد شده‌اند. (date-time)
querystringخیرجستجوی متن آزاد در موضوع‌ها، متن ایمیل‌ها، نشانی‌های فرستنده/گیرنده و نام فایل پیوست‌ها. (حداکثر 200 کاراکتر)
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [email summaries], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_emails",
  "arguments": {
    "direction": "in",
    "unread": true,
    "limit": 25
  }
}
فقط‌خواندنیget_email
GET /emails/:email_id

دریافت یک ایمیل

یک پیام را همراه با هدرها، بدنه html/text، وضعیت، فراداده رشته گفتگو و فراداده پیوست‌ها دریافت کنید (بایت‌های پیوست را با download_attachment دانلود کنید).

پارامترنوعالزامیتوضیح
email_idstringبلهشناسه ایمیل (با em_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجیشیء ایمیل: {id, direction, status, from, to, cc, bcc, subject, html, text, threadId, messageId, providerMessageId, readAt, createdAt, attachments: [{id, filename, contentType, sizeBytes, available}]}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_email",
  "arguments": {
    "email_id": "em_123"
  }
}
تغییر وضعیتmark_email
PATCH /emails/:email_id

علامت‌گذاری به‌عنوان خوانده‌شده، بایگانی‌شده، اسپم یا مهم

یک پیام را به‌روز کنید: read، archived، category (primary، updates، spam؛ فقط ایمیل‌های دریافتی) و important. گزارش اسپم یا علامت‌گذاری به‌عنوان مهم، به SendHQ درباره آن فرستنده برای ایمیل‌های آینده آموزش می‌دهد؛ برای تغییر فقط همین پیام learn: false را ارسال کنید. دست‌کم یک فیلد ارسال کنید.

پارامترنوعالزامیتوضیح
email_idstringبلهشناسه ایمیل (با em_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
readbooleanخیرtrue = خوانده‌شده، false = خوانده‌نشده.
archivedbooleanخیرtrue = بایگانی (خارج از صندوق ورودی)، false = بازگرداندن به صندوق ورودی.
categorystringخیریک پیام دریافتی را به primary، updates یا spam منتقل کنید. (یکی از primary، updates، spam)
importantbooleanخیرعلامت مهم را روی پیام بگذارید یا بردارید.
learnbooleanخیرfalse = این تصمیم برای فرستنده به خاطر سپرده نشود (پیش‌فرض true).
خروجیشیء ایمیل به‌روزشده.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "mark_email",
  "arguments": {
    "email_id": "em_123",
    "read": true
  }
}
مخربdelete_email
DELETE /emails/:email_id

حذف یک ایمیل

DESTRUCTIVE (مخرب): یک پیام نگهداری‌شده و پیوست‌های ذخیره‌شده آن را برای همیشه از SendHQ حذف می‌کند. پیامی را که قبلاً تحویل شده بازنمی‌گرداند.

پارامترنوعالزامیتوضیح
email_idstringبلهشناسه ایمیل (با em_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_email",
  "arguments": {
    "email_id": "em_123"
  }
}
فقط‌خواندنیlist_email_events
GET /emails/:email_id/events

فهرست رویدادهای تحویل یک ایمیل

رویدادهای ارائه‌دهنده برای یک پیام ارسالی: delivery، bounce، complaint، reject، open، click. این‌ها شواهدی هستند که نشان می‌دهند پیام تحویل شده یا چرا شکست خورده است. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
email_idstringبلهشناسه ایمیل (با em_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [{event_type, recipient, reason, created_at, …}], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_email_events",
  "arguments": {
    "email_id": "em_123"
  }
}
فقط‌خواندنیget_thread
GET /threads/:thread_id

دریافت یک مکالمه

همه پیام‌های یک مکالمه (ارسالی و دریافتی) را به ترتیب زمانی، هر کدام همراه با فراداده پیوست‌ها، دریافت کنید.

پارامترنوعالزامیتوضیح
thread_idstringبلهشناسه رشته گفتگو (معمولاً شناسه em_… نخستین پیام؛ threadId هر ایمیل را ببینید). (حداکثر 128 کاراکتر)
خروجی{id, subject, data: [emails]}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_thread",
  "arguments": {
    "thread_id": "em_123"
  }
}
Read-onlyemail_delivery
GET /emails/:email_id/delivery

Get an email delivery timeline

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

پارامترنوعالزامیتوضیح
email_idstringبله
limitintegerخیر
offsetintegerخیر
Returns{emailId, status, timeline, count, limit, offset}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "email_delivery",
  "arguments": {
    "email_id": "em_123"
  }
}
Read-onlythread_delivery
GET /threads/:thread_id/delivery

Get a thread delivery summary

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

پارامترنوعالزامیتوضیح
thread_idstringبله
Returns{threadId, delivered, bounced, complained, failed, messages}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "thread_delivery",
  "arguments": {
    "thread_id": "thr_123"
  }
}

برچسب‌ها و قوانین بایگانی خودکار

فقط‌خواندنیlist_labels
GET /labels

فهرست برچسب‌ها

برچسب‌های (پوشه‌های) فضای کاری را همراه با تعداد کل و خوانده‌نشده‌ها و قوانین بایگانی خودکارشان فهرست کنید. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [{id, name, color, totalCount, unreadCount, rules: [...]}], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_labels",
  "arguments": {}
}
فقط‌خواندنیget_label
GET /labels/:label_id

دریافت یک برچسب

یک برچسب را همراه با شمارش‌ها و قوانین بایگانی خودکار دریافت کنید.

پارامترنوعالزامیتوضیح
label_idstringبلهشناسه برچسب (با lbl_ شروع می‌شود) یا نام دقیق برچسب. (حداکثر 128 کاراکتر)
خروجیشیء برچسب.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_label",
  "arguments": {
    "label_id": "Billing"
  }
}
تغییر وضعیتcreate_label
POST /labels

ساخت برچسب

یک برچسب از نوع پوشه بسازید. skip_inbox: true را تنظیم کنید تا به bucketی تبدیل شود که ایجنت مالک آن است: با labels: [name] ارسال کنید تا پاسخ‌ها در آن برچسب بایگانی شوند و از صندوق ورودی دور بمانند. قوانین اختیاری بایگانی خودکار، ایمیل‌های ارسالی/دریافتی جدید را بایگانی می‌کنند (همه شرط‌های یک قانون باید برقرار باشند). برای بایگانی ایمیل‌های نگهداری‌شده نیز apply_to_existing را تنظیم کنید.

پارامترنوعالزامیتوضیح
namestringبلهنام برچسب، مثلاً Billing یا Clients/Acme. در هر فضای کاری یکتاست (بدون حساسیت به حروف بزرگ و کوچک). (حداکثر 64 کاراکتر)
colorstringخیررنگ hex مانند #1a73e8. اختیاری.
skip_inboxbooleanخیرحالت bucket: ایمیل دریافتی‌ای که این برچسب را می‌گیرد (از طریق قانون، پاسخ به مکالمه‌ای که با این برچسب ارسال شده، یا به‌صورت دستی) بایگانی می‌شود تا فقط در برچسب نمایش داده شود، نه در صندوق ورودی.
rulesobject[]خیرقوانین اختیاری بایگانی خودکار (حداکثر 20). هر کدام دست‌کم به یکی از inbox_id، from، to، subject نیاز دارد. (0 تا 20 مورد)
rules[].directionstringخیرفقط ایمیل‌های in (دریافتی) یا out (ارسالی). برای هر دو آن را حذف کنید. (یکی از in، out)
rules[].inbox_idstringخیرفقط ایمیل‌هایی که این صندوق ورودی (inb_…) دریافت کرده است. هر نشانی دریافت را در پوشه مخصوص خودش بایگانی می‌کند.
rules[].fromstringخیرفرستنده شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک)، مثلاً @stripe.com. (حداکثر 200 کاراکتر)
rules[].tostringخیرTo/Cc شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک). (حداکثر 200 کاراکتر)
rules[].subjectstringخیرموضوع شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک). (حداکثر 200 کاراکتر)
rules[].skip_inboxbooleanخیرایمیل‌های دریافتی منطبق را بایگانی کنید تا فقط در پوشه برچسب نمایش داده شوند، نه در صندوق ورودی.
apply_to_existingbooleanخیرایمیل‌های نگهداری‌شده‌ای را که با قوانین مطابقت دارند نیز بایگانی کنید.
خروجیبرچسب ساخته‌شده همراه با قوانین.
نمونه params برای tools/call
{
  "name": "create_label",
  "arguments": {
    "name": "Agent/Orders",
    "skip_inbox": true,
    "rules": [
      {
        "from": "@stripe.com"
      }
    ]
  }
}
تغییر وضعیتupdate_label
PATCH /labels/:label_id

تغییر نام، تغییر رنگ یا تبدیل برچسب به bucket

نام برچسب را تغییر دهید، رنگش را عوض کنید یا حالت bucket (skip_inbox) را روشن/خاموش کنید. روشن کردن حالت bucket ایمیل‌های دریافتی موجود در برچسب را بایگانی می‌کند.

پارامترنوعالزامیتوضیح
label_idstringبلهشناسه برچسب (با lbl_ شروع می‌شود) یا نام دقیق برچسب. (حداکثر 128 کاراکتر)
namestringخیرنام جدید. (حداکثر 64 کاراکتر)
colorstringخیررنگ hex جدید.
skip_inboxbooleanخیرحالت bucket: ایمیل دریافتی‌ای که این برچسب را می‌گیرد (از طریق قانون، پاسخ به مکالمه‌ای که با این برچسب ارسال شده، یا به‌صورت دستی) بایگانی می‌شود تا فقط در برچسب نمایش داده شود، نه در صندوق ورودی.
خروجیبرچسب به‌روزشده.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "update_label",
  "arguments": {
    "label_id": "lbl_123",
    "name": "Finance/Billing"
  }
}
مخربdelete_label
DELETE /labels/:label_id

حذف برچسب

DESTRUCTIVE (مخرب): یک برچسب و قوانینش را حذف می‌کند. خود ایمیل‌ها حفظ می‌شوند؛ فقط این برچسب را از دست می‌دهند.

پارامترنوعالزامیتوضیح
label_idstringبلهشناسه برچسب (با lbl_ شروع می‌شود) یا نام دقیق برچسب. (حداکثر 128 کاراکتر)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_label",
  "arguments": {
    "label_id": "lbl_123"
  }
}
تغییر وضعیتcreate_label_rule
POST /labels/:label_id/rules

افزودن قانون بایگانی خودکار

یک قانون به برچسب اضافه کنید تا ایمیل‌های جدید منطبق به‌طور خودکار بایگانی شوند. همه شرط‌هایی که تنظیم می‌کنید باید برقرار باشند. از inbox_id استفاده کنید تا یک نشانی دریافت، پوشه مخصوص خودش را داشته باشد؛ skip_inbox را اضافه کنید تا از صندوق ورودی دور بماند.

پارامترنوعالزامیتوضیح
label_idstringبلهشناسه برچسب (با lbl_ شروع می‌شود) یا نام دقیق برچسب. (حداکثر 128 کاراکتر)
directionstringخیرفقط ایمیل‌های in (دریافتی) یا out (ارسالی). برای هر دو آن را حذف کنید. (یکی از in، out)
inbox_idstringخیرفقط ایمیل‌هایی که این صندوق ورودی (inb_…) دریافت کرده است. هر نشانی دریافت را در پوشه مخصوص خودش بایگانی می‌کند.
fromstringخیرفرستنده شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک)، مثلاً @stripe.com. (حداکثر 200 کاراکتر)
tostringخیرTo/Cc شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک). (حداکثر 200 کاراکتر)
subjectstringخیرموضوع شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک). (حداکثر 200 کاراکتر)
skip_inboxbooleanخیرایمیل‌های دریافتی منطبق را بایگانی کنید تا فقط در پوشه برچسب نمایش داده شوند، نه در صندوق ورودی.
apply_to_existingbooleanخیرایمیل‌های نگهداری‌شده منطبق را نیز بایگانی کنید.
خروجی{id: lrule_…, labelId, direction, inboxId, from, to, subject, skipInbox}.
نمونه params برای tools/call
{
  "name": "create_label_rule",
  "arguments": {
    "label_id": "Billing",
    "inbox_id": "inb_123",
    "skip_inbox": true
  }
}
مخربdelete_label_rule
DELETE /labels/:label_id/rules/:rule_id

حذف یک قانون بایگانی خودکار

DESTRUCTIVE (مخرب): یک قانون بایگانی خودکار را حذف می‌کند. ایمیل‌هایی که قبلاً بایگانی شده‌اند برچسب خود را حفظ می‌کنند.

پارامترنوعالزامیتوضیح
label_idstringبلهشناسه برچسب (با lbl_ شروع می‌شود) یا نام دقیق برچسب. (حداکثر 128 کاراکتر)
rule_idstringبلهشناسه قانون (با lrule_ شروع می‌شود)، از get_label. (حداکثر 128 کاراکتر)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_label_rule",
  "arguments": {
    "label_id": "lbl_123",
    "rule_id": "lrule_123"
  }
}
تغییر وضعیتlabel_email
POST /emails/:email_id/labels

افزودن یا حذف برچسب‌های یک ایمیل

یک پیام را بین پوشه‌ها جابه‌جا کنید: برچسب‌ها را با نام یا شناسه lbl_… اضافه و/یا حذف کنید. نام‌های ناشناخته در add ایجاد می‌شوند، مگر اینکه create برابر false باشد.

پارامترنوعالزامیتوضیح
email_idstringبلهشناسه ایمیل (با em_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
addstring[]خیربرچسب‌هایی که باید اضافه شوند. (0 تا 10 مورد)
removestring[]خیربرچسب‌هایی که باید حذف شوند. (0 تا 10 مورد)
createbooleanخیرایجاد برچسب‌های ناشناخته در add (پیش‌فرض true).
خروجیایمیل به‌روزشده همراه با labels.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "label_email",
  "arguments": {
    "email_id": "em_123",
    "add": [
      "Billing"
    ],
    "remove": [
      "Support"
    ]
  }
}

پیش‌نویس‌ها، پیوست‌ها و هویت‌های فرستنده

فقط‌خواندنیlist_sending_identities
GET /sending-identities

فهرست هویت‌های فرستنده تأییدشده

نشانی‌ها و دامنه‌هایی که این فضای کاری همین حالا می‌تواند از آن‌ها ارسال کند (دامنه‌های تأییدشده، From پیش‌فرض آن‌ها و نشانی‌های صندوق ورودی فعال). پیش از send_email آن را فراخوانی کنید تا یک from معتبر انتخاب کنید.

بدون پارامتر.

خروجی{domains: [verified domain names], addresses: [sender addresses], localParts: [...]}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_sending_identities",
  "arguments": {}
}
تغییر وضعیتcreate_draft
POST /drafts

ساخت پیش‌نویس

یک پیش‌نویس در ویرایشگر ایمیل بسازید. پیش‌نویس‌ها پیوست‌ها را نگه می‌دارند: یک پیش‌نویس بسازید، upload_attachment را اجرا کنید، سپس send_email را با draft_id فراخوانی کنید. چیزی ارسال نمی‌کند.

پارامترنوعالزامیتوضیح
fromstringخیرنشانی فرستنده روی یک دامنه تأییدشده (در حین پیش‌نویس می‌تواند خالی باشد).
tostring[]خیرگیرندگان. (0 تا 100 مورد)
ccstring[]خیرگیرندگان رونوشت (Cc). (0 تا 100 مورد)
bccstring[]خیرگیرندگان رونوشت مخفی (Bcc). (0 تا 100 مورد)
subjectstringخیرموضوع ایمیل. (حداکثر 998 کاراکتر)
htmlstringخیربدنه HTML.
textstringخیرمتن ساده.
reply_to_email_idstringخیرشناسه ایمیلی که این پیش‌نویس به آن پاسخ می‌دهد.
thread_idstringخیرشناسه رشته گفتگویی که این پیش‌نویس به آن تعلق دارد.
خروجیشیء پیش‌نویس {id: dr_…, from, to, cc, bcc, subject, html, text, attachments: []}.
نمونه params برای tools/call
{
  "name": "create_draft",
  "arguments": {
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice"
  }
}
فقط‌خواندنیlist_drafts
GET /drafts

فهرست پیش‌نویس‌ها

پیش‌نویس‌های ویرایشگر را به ترتیب آخرین به‌روزرسانی فهرست کنید. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [drafts], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_drafts",
  "arguments": {}
}
فقط‌خواندنیget_draft
GET /drafts/:draft_id

دریافت یک پیش‌نویس

یک پیش‌نویس را همراه با فراداده پیوست‌هایش دریافت کنید.

پارامترنوعالزامیتوضیح
draft_idstringبلهشناسه پیش‌نویس (با dr_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجیشیء پیش‌نویس همراه با attachments.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
تغییر وضعیتupdate_draft
PUT /drafts/:draft_id

جایگزینی محتوای پیش‌نویس

محتوا و گیرندگان یک پیش‌نویس را جایگزین کنید. این یک جایگزینی کامل است: فیلدهایی که حذف کنید پاک می‌شوند، پس ابتدا get_draft را بخوانید و همه فیلدهایی را که می‌خواهید حفظ شوند ارسال کنید. پیوست‌ها تحت تأثیر قرار نمی‌گیرند.

پارامترنوعالزامیتوضیح
draft_idstringبلهشناسه پیش‌نویس (با dr_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
fromstringخیرنشانی فرستنده روی یک دامنه تأییدشده (در حین پیش‌نویس می‌تواند خالی باشد).
tostring[]خیرگیرندگان. (0 تا 100 مورد)
ccstring[]خیرگیرندگان رونوشت (Cc). (0 تا 100 مورد)
bccstring[]خیرگیرندگان رونوشت مخفی (Bcc). (0 تا 100 مورد)
subjectstringخیرموضوع ایمیل. (حداکثر 998 کاراکتر)
htmlstringخیربدنه HTML.
textstringخیرمتن ساده.
reply_to_email_idstringخیرشناسه ایمیلی که این پیش‌نویس به آن پاسخ می‌دهد.
thread_idstringخیرشناسه رشته گفتگویی که این پیش‌نویس به آن تعلق دارد.
خروجیشیء پیش‌نویس به‌روزشده.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "update_draft",
  "arguments": {
    "draft_id": "dr_123",
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice (updated)",
    "text": "Attached."
  }
}
مخربdelete_draft
DELETE /drafts/:draft_id

دور ریختن پیش‌نویس

DESTRUCTIVE (مخرب): یک پیش‌نویس را دور می‌ریزد و پیوست‌های ذخیره‌شده آن را برای همیشه حذف می‌کند.

پارامترنوعالزامیتوضیح
draft_idstringبلهشناسه پیش‌نویس (با dr_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
تغییر وضعیتupload_attachment
POST /drafts/:draft_id/attachments

بارگذاری پیوست در یک پیش‌نویس

یک فایل را در یک پیش‌نویس بارگذاری کنید (حداکثر 10 فایل و مجموعاً 10 MB برای هر پیام). content_base64 یا یک file_path محلی ارائه دهید. پیوست‌ها هنگام ارسال به پلن پولی نیاز دارند.

دست‌کم یکی از این موارد را ارائه دهید: content_base64، file_path.

پارامترنوعالزامیتوضیح
draft_idstringبلهشناسه پیش‌نویس (با dr_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
filenamestringخیرنام فایلی که به گیرنده نمایش داده می‌شود. پیش‌فرض، نام پایه file_path است. (حداکثر 255 کاراکتر)
content_typestringخیرنوع MIME، مثلاً application/pdf. پیش‌فرض application/octet-stream است.
content_base64stringخیرمحتوای فایل با base64 استاندارد.
file_pathstringخیرمسیر مطلق یک فایل محلی که پردازه سرور MCP بتواند آن را بخواند.
خروجی{id: att_…, filename, contentType, sizeBytes, available}.
نمونه params برای tools/call
{
  "name": "upload_attachment",
  "arguments": {
    "draft_id": "dr_123",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_path": "/tmp/invoice.pdf"
  }
}
فقط‌خواندنیdownload_attachment
GET /attachments/:attachment_id

دانلود پیوست

یک پیوست خصوصی (ارسالی، دریافتی یا پیش‌نویس) را دانلود کنید. محتوای base64 را برمی‌گرداند، یا وقتی save_to_path تنظیم شده باشد فایل را می‌نویسد (بازنویسی نمی‌کند مگر اینکه overwrite برابر true باشد).

پارامترنوعالزامیتوضیح
attachment_idstringبلهشناسه پیوست (با att_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
save_to_pathstringخیرمسیر مطلق محلی اختیاری برای نوشتن فایل به‌جای برگرداندن base64.
overwritebooleanخیراجازه جایگزینی فایل موجود در save_to_path. پیش‌فرض false.
خروجی{attachment_id, filename, content_type, size_bytes, content_base64} or {attachment_id, filename, content_type, size_bytes, saved_to}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "download_attachment",
  "arguments": {
    "attachment_id": "att_123",
    "save_to_path": "/tmp/invoice.pdf"
  }
}
مخربdelete_attachment
DELETE /attachments/:attachment_id

حذف پیوست

DESTRUCTIVE (مخرب): یک پیوست ذخیره‌شده را برای همیشه حذف می‌کند (برای مثال، حذف یک فایل از پیش‌نویس پیش از ارسال).

پارامترنوعالزامیتوضیح
attachment_idstringبلهشناسه پیوست (با att_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_attachment",
  "arguments": {
    "attachment_id": "att_123"
  }
}

قالب‌های میزبانی‌شده

فقط‌خواندنیlist_templates
GET /templates

فهرست قالب‌های میزبانی‌شده

قالب‌های ایمیل میزبانی‌شده را همراه با وضعیت انتشار و میزان استفاده فهرست کنید. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
lifecyclestringخیرactive (پیش‌فرض)، archived یا all. (یکی از active، archived، all)
querystringخیرجستجو بر اساس نام یا کلید. (حداکثر 120 کاراکتر)
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [templates], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_templates",
  "arguments": {
    "lifecycle": "active"
  }
}
تغییر وضعیتcreate_template
POST /templates

ساخت قالب میزبانی‌شده

یک قالب با پیش‌نویس قابل‌ویرایش بسازید، به‌صورت اختیاری از یک محتوای آغازین (welcome، reset، receipt یا blank). پیش از ارسال با کلید، آن را منتشر کنید.

پارامترنوعالزامیتوضیح
namestringبلهنام قابل‌فهم برای انسان. (حداکثر 120 کاراکتر)
keystringخیرکلید پایدار ارسال: حروف کوچک، اعداد و خط تیره؛ با یک حرف شروع می‌شود (2 تا 64 کاراکتر). در صورت حذف، از نام استخراج می‌شود.
starterstringخیرمحتوای آغازین. (یکی از blank، welcome، reset، receipt)
خروجی{template, draft, activeVersion, versions, usage}.
نمونه params برای tools/call
{
  "name": "create_template",
  "arguments": {
    "name": "Account welcome",
    "key": "account-welcome",
    "starter": "welcome"
  }
}
فقط‌خواندنیget_template
GET /templates/:template_id

دریافت یک قالب

پیش‌نویس فعلی قالب (همراه با revision)، نسخه منتشرشده فعال، تاریخچه نسخه‌ها و میزان استفاده را دریافت کنید. شناسه یا کلید را می‌پذیرد.

پارامترنوعالزامیتوضیح
template_idstringبلهشناسه قالب (tmpl_…) یا کلید. (حداکثر 128 کاراکتر)
خروجی{template, draft: {id, revision, subjectTemplate, htmlTemplate, textTemplate, variables, sampleData, …} | null, activeVersion, versions, usage}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
تغییر وضعیتupdate_template_draft
PUT /templates/:template_id/draft

ذخیره پیش‌نویس قالب

پیش‌نویس قابل‌ویرایش قالب را با هم‌زمانی خوش‌بینانه ذخیره کنید: revision فعلی را از get_template ارسال کنید (409 یعنی شخص دیگری زودتر ذخیره کرده است؛ دوباره بخوانید و تلاش کنید). این یک جایگزینی کامل محتوای پیش‌نویس است: فیلدهای حذف‌شده پاک می‌شوند، پس همه فیلدهایی را که می‌خواهید حفظ شوند ارسال کنید. از placeholderهای {{variable}} استفاده کنید.

پارامترنوعالزامیتوضیح
template_idstringبلهشناسه یا کلید قالب. (حداکثر 128 کاراکتر)
revisionintegerبلهrevision فعلی پیش‌نویس از get_template. (1 تا …)
namestringخیرنام قالب. (حداکثر 120 کاراکتر)
subject_templatestringخیرموضوع همراه با placeholderها. (حداکثر 998 کاراکتر)
preheader_templatestringخیرمتن پیش‌نمایش. (حداکثر 240 کاراکتر)
html_templatestringخیربدنه HTML همراه با placeholderها.
text_templatestringخیرمتن ساده همراه با placeholderها.
fromstringخیرفرستنده پیش‌فرض برای ارسال‌های این قالب.
reply_tostringخیرReply-To پیش‌فرض.
variablesobject[]خیرقرارداد متغیرهای نوع‌دار. هر مورد: {key (حروف کوچک/زیرخط), label, type: text|number|url|boolean, required (پیش‌فرض true), fallback, description}.
variables[].keystringبله
variables[].labelstringخیر
variables[].typestringخیر(یکی از text، number، url، boolean)
variables[].requiredbooleanخیر
variables[].fallbackanyخیر
variables[].descriptionstringخیر
sample_dataobjectخیرمقادیر نمونه برای پیش‌نمایش‌ها و آزمایش‌ها.
خروجی{template, draft: {revision: next}, validation: {valid, findings}}.
نمونه params برای tools/call
{
  "name": "update_template_draft",
  "arguments": {
    "template_id": "account-welcome",
    "revision": 3,
    "name": "Account welcome",
    "subject_template": "Welcome, {{first_name}}",
    "text_template": "Hi {{first_name}}",
    "variables": [
      {
        "key": "first_name",
        "type": "text",
        "required": true
      }
    ],
    "sample_data": {
      "first_name": "Asha"
    }
  }
}
تغییر وضعیتcreate_template_draft
POST /templates/:template_id/draft

شروع پیش‌نویس جدید از نسخه منتشرشده

یک پیش‌نویس قابل‌ویرایش جدید با کپی از نسخه منتشرشده فعلی بسازید (اگر پیش‌نویسی از قبل وجود داشته باشد یا چیزی منتشر نشده باشد، 409).

پارامترنوعالزامیتوضیح
template_idstringبلهشناسه یا کلید قالب. (حداکثر 128 کاراکتر)
خروجی{draft}.
نمونه params برای tools/call
{
  "name": "create_template_draft",
  "arguments": {
    "template_id": "account-welcome"
  }
}
فقط‌خواندنیrender_template
POST /templates/:template_id/render

رندر پیش‌نمایش قالب

خروجی دقیق سرور (subject، html، text) را برای پیش‌نویس، نسخه منتشرشده یا یک نسخه مشخص با داده داده‌شده رندر کنید. چیزی ارسال نمی‌کند. وقتی داده قرارداد متغیرها را نقض کند، 422 همراه با findings برمی‌گرداند.

پارامترنوعالزامیتوضیح
template_idstringبلهشناسه یا کلید قالب. (حداکثر 128 کاراکتر)
version_idstringخیرشناسه اختیاری نسخه؛ پیش‌فرض پیش‌نویس است و سپس نسخه منتشرشده.
dataobjectخیرمقادیر متغیرها؛ پیش‌فرض داده نمونه همان نسخه است.
خروجی{subject, html, text, preheader, versionId, versionNumber, isDraft, findings}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "render_template",
  "arguments": {
    "template_id": "account-welcome",
    "data": {
      "first_name": "Asha"
    }
  }
}
ارسال ایمیل واقعیsend_template_test
POST /templates/:template_id/test

ارسال ایمیل آزمایشی قالب

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

پارامترنوعالزامیتوضیح
template_idstringبلهشناسه یا کلید قالب. (حداکثر 128 کاراکتر)
tostring[]بلهگیرندگان آزمایشی. (1 تا 100 مورد)
fromstringخیرفرستنده روی یک دامنه تأییدشده؛ پیش‌فرض From قالب است.
version_idstringخیرشناسه اختیاری نسخه.
dataobjectخیرمقادیر متغیرها؛ پیش‌فرض داده نمونه است.
خروجی{id: em_…, providerMessageId, threadId, isTest: true}.
نمونه params برای tools/call
{
  "name": "send_template_test",
  "arguments": {
    "template_id": "account-welcome",
    "to": [
      "owner@example.com"
    ]
  }
}
تغییر وضعیتpublish_template
POST /templates/:template_id/publish

انتشار نسخه قالب

پیش‌نویس فعلی را به‌عنوان یک نسخه تغییرناپذیر منتشر کنید که send_email با template.key از آن استفاده خواهد کرد. در صورت خطای اعتبارسنجی با 422 و findings شکست می‌خورد، یا اگر قرارداد متغیرهای فعال قالبی را که در محیط عملیاتی استفاده می‌شود بشکند، با 409.

پارامترنوعالزامیتوضیح
template_idstringبلهشناسه یا کلید قالب. (حداکثر 128 کاراکتر)
خروجی{template, published}.
نمونه params برای tools/call
{
  "name": "publish_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
تغییر وضعیتarchive_template
POST /templates/:template_id/archive

بایگانی قالب

ارسال‌های جدید با این قالب را متوقف می‌کند (تاریخچه حفظ می‌شود؛ با restore_template قابل بازگشت است). هر یکپارچه‌سازی‌ای که با این کلید ارسال می‌کند با 404 شکست خواهد خورد.

پارامترنوعالزامیتوضیح
template_idstringبلهشناسه یا کلید قالب. (حداکثر 128 کاراکتر)
خروجی{template}.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "archive_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
تغییر وضعیتrestore_template
POST /templates/:template_id/restore

بازیابی قالب بایگانی‌شده

یک قالب بایگانی‌شده را دوباره فعال کنید.

پارامترنوعالزامیتوضیح
template_idstringبلهشناسه یا کلید قالب. (حداکثر 128 کاراکتر)
خروجی{template}.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "restore_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

دامنه‌ها و DNS

فقط‌خواندنیlist_domains
GET /domains

فهرست دامنه‌ها

دامنه‌های ارسال را همراه با setup_status تجمیعی (verified | checking | pending)، وضعیت DNS هر رکورد و وضعیت ورودی فهرست کنید. ممکن است کند باشد: دامنه‌های تأییدنشده به‌صورت زنده دوباره بررسی می‌شوند. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [domains with records], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_domains",
  "arguments": {}
}
فقط‌خواندنیget_domain
GET /domains/:domain_id

دریافت جزئیات راه‌اندازی دامنه

یک دامنه را همراه با رکوردهای دقیق DNS برای انتشار (type، name، value)، وضعیت زنده هر رکورد از دو resolver عمومی، dns_issues همراه با راه‌حل‌ها و وضعیت ورودی دریافت کنید.

پارامترنوعالزامیتوضیح
domain_idstringبلهشناسه دامنه (با dom_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجی{id, name, status, setup_status, dns_propagating, records: [{type, name, value, verified, dns_state}], dns_issues: [{code, message, …}], inbound_domain, inbound_status}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
تغییر وضعیتadd_domain
POST /domains

افزودن دامنه ارسال

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

پارامترنوعالزامیتوضیح
namestringبلهنام دامنه بدون پیشوند، مثلاً example.com یا mail.example.com. (حداکثر 253 کاراکتر)
default_fromstringخیرنشانی فرستنده پیش‌فرض اختیاری روی این دامنه.
خروجی{id: dom_…, name, status: pending, records: [...], ses: {configured}}.
نمونه params برای tools/call
{
  "name": "add_domain",
  "arguments": {
    "name": "example.com"
  }
}
تغییر وضعیتverify_domain
POST /domains/:domain_id/verify

تأیید دامنه

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

پارامترنوعالزامیتوضیح
domain_idstringبلهشناسه دامنه (با dom_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجی{domain, checks: {ses, dkim, dkim_status}, status: verified|pending}.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "verify_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
مخربdelete_domain
DELETE /domains/:domain_id

حذف دامنه

DESTRUCTIVE (مخرب): دامنه را همراه با مسیر دریافت ایمیل ورودی آن از فضای کاری حذف می‌کند. ارسال از آن بلافاصله پس از این کار شکست می‌خورد. رکوردهای DNS را نزد ارائه‌دهنده DNS شما حذف نمی‌کند.

پارامترنوعالزامیتوضیح
domain_idstringبلهشناسه دامنه (با dom_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
فقط‌خواندنیget_dns_provider
GET /dns/provider

تشخیص ارائه‌دهنده DNS و hostهای رکوردها

ارائه‌دهنده DNS معتبر (authoritative) دامنه را تشخیص می‌دهد و host نسبی‌ای را که باید برای هر رکورد در آن ارائه‌دهنده وارد شود، رکورد DMARC پیشنهادی، راهنمای MX ورودی و در دسترس بودن راه‌اندازی یک‌کلیکی (Domain Connect) را برمی‌گرداند.

پارامترنوعالزامیتوضیح
domain_idstringبلهشناسه دامنه (با dom_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجی{detectionStatus, detected, zone, nameservers, recordHosts: {recordId: host}, inbound, recommendations, authentication, providers: {domainConnect: {available, providerName}}}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_dns_provider",
  "arguments": {
    "domain_id": "dom_123"
  }
}

ایمیل ورودی

تغییر وضعیتsetup_inbound
POST /domains/:domain_id/inbound/setup

فعال‌سازی دریافت ایمیل ورودی برای یک دامنه

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

پارامترنوعالزامیتوضیح
domain_idstringبلهشناسه دامنه (با dom_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجی{domain: receiving domain, status: dns_pending|ready, record: {type: MX, name, value}}.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "setup_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
تغییر وضعیتverify_inbound
POST /domains/:domain_id/inbound/verify

تأیید MX ورودی

رکورد MX ورودی را دوباره بررسی می‌کند. وقتی هر دو resolver عمومی آن را ببینند، وضعیت ready می‌شود.

پارامترنوعالزامیتوضیح
domain_idstringبلهشناسه دامنه (با dom_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجی{domain, status: ready|dns_pending|propagating|checking, record}.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "verify_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
فقط‌خواندنیlist_inboxes
GET /inboxes

فهرست نشانی‌های ورودی

نشانی‌های دریافت را، به‌صورت اختیاری برای یک دامنه، فهرست کنید. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
domain_idstringخیرفیلتر اختیاری شناسه دامنه.
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [{id, address, name, status, domainId}], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_inboxes",
  "arguments": {
    "domain_id": "dom_123"
  }
}
فقط‌خواندنیget_inbox
GET /inboxes/:inbox_id

دریافت یک صندوق ورودی

یک نشانی ورودی را دریافت کنید.

پارامترنوعالزامیتوضیح
inbox_idstringبلهشناسه صندوق ورودی (با inb_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجیشیء صندوق ورودی.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}
تغییر وضعیتcreate_inbox
POST /inboxes

ساخت نشانی ورودی

نشانی‌ای مانند support@<receiving domain> را روی دامنه‌ای بسازید که وضعیت ورودی آن ready است (ابتدا setup_inbound و verify_inbound را اجرا کنید). ایمیل‌های دریافتی در list_emails با direction برابر in نمایش داده می‌شوند.

پارامترنوعالزامیتوضیح
domain_idstringبلهشناسه دامنه (با dom_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
local_partstringبلهبخش پیش از @، مثلاً support. (حداکثر 64 کاراکتر)
namestringخیرنام نمایشی اختیاری.
خروجی{id: inb_…, address, name, status: active}.
نمونه params برای tools/call
{
  "name": "create_inbox",
  "arguments": {
    "domain_id": "dom_123",
    "local_part": "support",
    "name": "Support"
  }
}
تغییر وضعیتupdate_inbox
PATCH /inboxes/:inbox_id

تغییر نام، فعال یا غیرفعال کردن صندوق ورودی

نام یک صندوق ورودی را تغییر دهید یا وضعیت آن را روی active / disabled تنظیم کنید.

پارامترنوعالزامیتوضیح
inbox_idstringبلهشناسه صندوق ورودی (با inb_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
namestringخیرنام نمایشی جدید.
statusstringخیروضعیت جدید. (یکی از active، disabled)
خروجیصندوق ورودی به‌روزشده.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "update_inbox",
  "arguments": {
    "inbox_id": "inb_123",
    "status": "disabled"
  }
}
ارسال ایمیل واقعیset_inbox_forwarding
PUT /inboxes/:inbox_id/forwarding

فوروارد صندوق ورودی به نشانی دیگر

SENDS REAL EMAIL (ایمیل واقعی ارسال می‌کند) وقتی به کسی جز مالک حساب فوروارد شود: مقصد فوروارد ایمیل‌های دریافتی یک صندوق ورودی را تنظیم می‌کند. نشانی خود مالک بلافاصله فعال می‌شود؛ هر نشانی دیگری یک ایمیل تأیید دریافت می‌کند و فوروارد تا زمانی که کسی در آنجا تأیید کند در وضعیت pending می‌ماند. برای خاموش کردن فوروارد، forward_to: null را ارسال کنید. نسخه‌های فورواردشده از نشانی صندوق ورودی و با فرستنده اصلی به‌عنوان Reply-To ارسال می‌شوند.

پارامترنوعالزامیتوضیح
inbox_idstringبلهشناسه صندوق ورودی (با inb_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
forward_tostring,nullبلهنشانی ایمیل مقصد فوروارد، یا null برای خاموش کردن فوروارد. (حداکثر 254 کاراکتر)
خروجیصندوق ورودی همراه با forwardTo و forwardStatus (off، pending یا active).
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "set_inbox_forwarding",
  "arguments": {
    "inbox_id": "inb_123",
    "forward_to": "team@example.net"
  }
}
مخربdelete_inbox
DELETE /inboxes/:inbox_id

حذف صندوق ورودی

DESTRUCTIVE (مخرب): یک نشانی ورودی را حذف می‌کند. ایمیل‌هایی که قبلاً دریافت شده‌اند نگه داشته می‌شوند؛ ایمیل‌های جدید به این نشانی دیگر در آن ثبت نمی‌شوند.

پارامترنوعالزامیتوضیح
inbox_idstringبلهشناسه صندوق ورودی (با inb_ شروع می‌شود)، همان‌طور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

تحویل‌پذیری، برگشت‌ها و فهرست توقف ارسال

فقط‌خواندنیdeliverability_stats
GET /deliverability/stats

دریافت آمار تحویل 30 روزه

مجموع‌های 30 روزه در سطح فضای کاری: sent، delivery، bounce، complaint، reject، open، click و deliveryRate (%).

بدون پارامتر.

خروجی{window: 30d, sent, delivery, bounce, complaint, reject, open, click, deliveryRate}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "deliverability_stats",
  "arguments": {}
}
Read-onlydeliverability_account
GET /deliverability/account

Get account delivery rates

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

پارامترنوعالزامیتوضیح
daysintegerخیر(one of 7, 30, 90)
Returns{days, trend, rolling7d, thresholds, ladder}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "deliverability_account",
  "arguments": {
    "days": 30
  }
}
Read-onlydeliverability_domains
GET /deliverability/domains

Get domain delivery rates

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

پارامترنوعالزامیتوضیح
daysintegerخیر
domainstringخیر
limitintegerخیر
offsetintegerخیر
Returns{days, data, count, limit, offset}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "deliverability_domains",
  "arguments": {
    "days": 30
  }
}
Read-onlydeliverability_senders
GET /deliverability/senders

Get sender delivery rates

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

پارامترنوعالزامیتوضیح
daysintegerخیر
domainstringخیر
limitintegerخیر
offsetintegerخیر
Returns{days, data, count, limit, offset}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "deliverability_senders",
  "arguments": {
    "days": 30
  }
}
Read-onlyscore_email
POST /deliverability/score

Score an email's content

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

پارامترنوعالزامیتوضیح
subjectstringخیرThe subject line.
htmlstringخیرThe HTML as written, before SendHQ adds its footer or tracking. (max 2000000 chars)
textstringخیرThe plain-text part. Compared with the HTML when both are given; scored on its own when there is no HTML. (max 2000000 chars)
fromstringخیرThe sender: an email address or a domain such as example.com. Without it, links to other sites are not judged. (max 320 chars)
Returns{score (0 to 100), deductions: [{id, points, count, suggestion}], warnings: [{id, message}]}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "score_email",
  "arguments": {
    "from": "hello@example.com",
    "subject": "Your cart is still here",
    "html": "<p>Pick up where you left off.</p><p><a href=\"https://bit.ly/3xyz\">Finish checkout</a></p>"
  }
}
فقط‌خواندنیlist_sender_reputation
GET /deliverability/reputation

فهرست اعتبار فرستنده

وضعیت اعتبار برای هر نشانی From مشخص: active، throttled (محدودیت روزانه کمتر) یا paused (ارسال‌ها 423 برمی‌گردانند)، همراه با دلیل و محدودیت روزانه. وقتی ارسال‌ها با 423 یا 429 شکست می‌خورند این را بررسی کنید. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [{sender, status, dailyLimit, reason, cleanSince, warnedAt, pausedAt, evaluatedAt}], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_sender_reputation",
  "arguments": {}
}
فقط‌خواندنیlist_suppressions
GET /suppressions

فهرست موارد توقف ارسال

فهرست توقف ارسال فضای کاری: گیرندگانی که پس از برگشت دائمی یا گزارش اسپم مسدود شده‌اند. ارسال به آن‌ها با 422 شکست می‌خورد. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [{email, reason, detail, created_at}], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_suppressions",
  "arguments": {}
}
مخربremove_suppression
DELETE /suppressions/:email

حذف مورد توقف ارسال ناشی از برگشت ایمیل

DESTRUCTIVE (مخرب؛ یک مانع ایمنی را تضعیف می‌کند): یک مورد توقف ارسال ناشی از برگشت را حذف می‌کند تا بتوان دوباره به آن نشانی ایمیل فرستاد. فقط وقتی این کار را انجام دهید که انسان تأیید کند نشانی اکنون معتبر است. موارد ناشی از گزارش اسپم قابل حذف نیستند (409).

پارامترنوعالزامیتوضیح
emailstringبلهنشانی گیرنده موجود در فهرست توقف ارسال. (حداکثر 320 کاراکتر)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "remove_suppression",
  "arguments": {
    "email": "fixed-mailbox@example.net"
  }
}
فقط‌خواندنیlist_blocked_recipients
GET /blocked-recipients

فهرست گیرندگان مسدودشده

همه گیرندگانی که SendHQ از ارسال به آن‌ها خودداری می‌کند: برگشت‌ها، گزارش‌های اسپم و لغو اشتراک‌های بازاریابی در سطح دامنه، همراه با خلاصه‌ای به تفکیک نوع. حداکثر 500 مورد جدیدتر را می‌خواند. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [{email, domain, kind: bounce|complaint|unsubscribe, reason, detail, source, status, created_at}], count, summary: {total, bounce, complaint, unsubscribe}, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_blocked_recipients",
  "arguments": {}
}

Campaigns

Read-onlylist_contacts
GET /contacts

List contacts

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

پارامترنوعالزامیتوضیح
list_idstringخیرOnly members of this list (lst_…).
statusstringخیرOnly contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant)
querystringخیرEmail or name contains this text; * is a wildcard on the email. (max 200 chars)
tagstringخیرOnly contacts with this tag. (max 60 chars)
sourcestringخیرHow the contact was added. (one of form, api, import)
afterstringخیرSigned up at or after this time. ISO 8601 date or date-time. (max 40 chars)
beforestringخیرSigned up before this time. ISO 8601 date or date-time. (max 40 chars)
segment_idstringخیرOnly contacts matching this saved segment (seg_…).
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [contacts with tags, engagement, dormant, country], count, total, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_contacts",
  "arguments": {
    "status": "subscribed"
  }
}
Changes statecreate_contact
POST /contacts

Add a contact

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

پارامترنوعالزامیتوضیح
emailstringبلهEmail address. (max 320 chars)
namestringخیرDisplay name; the first word is {{first_name}}. (max 200 chars)
fieldsobjectخیرCustom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field.
tagsstring[]خیرTags to attach, e.g. ["VIP"]. Up to 50. (0–50 items)
list_idsstring[]خیرLists to add the contact to (lst_…). (0–100 items)
statusstringخیرsubscribed (default, requires consent_basis) or unsubscribed. (one of subscribed, unsubscribed)
consent_basisstringخیرHow these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars)
ReturnsThe contact.
نمونه params برای tools/call
{
  "name": "create_contact",
  "arguments": {
    "email": "ada@example.net",
    "name": "Ada Lovelace",
    "consent_basis": "Ticked the newsletter box at checkout on acme.com"
  }
}
Changes stateupsert_contact
PUT /contacts

Create or update a contact by email

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

پارامترنوعالزامیتوضیح
emailstringبلهEmail address. (max 320 chars)
namestringخیرDisplay name; the first word is {{first_name}}. (max 200 chars)
fieldsobjectخیرCustom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
tagsstring[]خیرTags to add, e.g. ["VIP"]. Existing tags are kept. (0–50 items)
timezonestringخیرIANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
localestringخیرLanguage tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
consent_basisstringخیرHow this person agreed to receive your email, e.g. Created an account on acme.com and accepted product emails. Required when the email is not a contact yet. 10-500 characters. (max 500 chars)
ReturnsThe contact, plus timezone, locale, and created (true when it did not exist before).
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "upsert_contact",
  "arguments": {
    "email": "ada@example.net",
    "name": "Ada Lovelace",
    "fields": {
      "plan": "pro"
    },
    "timezone": "Europe/London",
    "consent_basis": "Created an account on acme.com and accepted product emails"
  }
}
Read-onlyget_contact
GET /contacts/:contact_id

Get a contact

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

پارامترنوعالزامیتوضیح
contact_idstringبلهContact ID (starts with ct_) or the contact's email address. (max 320 chars)
ReturnsThe contact.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_contact",
  "arguments": {
    "contact_id": "ct_123"
  }
}
Changes stateupdate_contact
PATCH /contacts/:contact_id

Update, tag, or unsubscribe a contact

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

پارامترنوعالزامیتوضیح
contact_idstringبلهContact ID (starts with ct_) or the contact's email address. (max 320 chars)
namestringخیرNew display name. (max 200 chars)
fieldsobjectخیرCustom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field.
tagsstring[]خیرReplace all of the contact's tags with these. (0–50 items)
add_tagsstring[]خیرTags to add. (0–50 items)
remove_tagsstring[]خیرTags to remove. (0–50 items)
statusstringخیرOnly unsubscribed is accepted. (one of unsubscribed)
ReturnsThe updated contact.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "update_contact",
  "arguments": {
    "contact_id": "ct_123",
    "fields": {
      "plan": "team"
    }
  }
}
Destructivedelete_contact
DELETE /contacts/:contact_id

Delete a contact

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

پارامترنوعالزامیتوضیح
contact_idstringبلهContact ID (starts with ct_) or the contact's email address. (max 320 chars)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_contact",
  "arguments": {
    "contact_id": "ct_123"
  }
}
Changes stateimport_contacts
POST /contact-imports

Import contacts from CSV

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

پارامترنوعالزامیتوضیح
csvstringبلهThe CSV file content, header row first. (max 5242880 chars)
list_idstringخیرAdd every accepted row to this list (lst_…).
consent_basisstringبلهHow these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars)
tagsstring[]خیرTags to add to every accepted row, e.g. ["imported-2026-11"]. (0–50 items)
update_existingbooleanخیرMerge names and fields into contacts that already exist. Their status never changes.
Returns{id, accepted, created, existing, skipped, invalid, errors: [{line, reason}], tags}.
نمونه params برای tools/call
{
  "name": "import_contacts",
  "arguments": {
    "csv": "email,name\nada@example.net,Ada Lovelace\n",
    "consent_basis": "Newsletter signups exported from Mailchimp (double opt-in)"
  }
}
Read-onlylist_contact_imports
GET /contact-imports

List contact imports

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

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [imports], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_contact_imports",
  "arguments": {}
}
Destructivebulk_update_contacts
POST /contacts/bulk

Bulk update contacts

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

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

List contact tags

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

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [{tag, count}], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_tags",
  "arguments": {}
}
Read-onlylist_contact_fields
GET /contact-fields

List custom contact fields

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

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [{key, label, type, createdAt}], count, types, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_contact_fields",
  "arguments": {}
}
Changes stateset_contact_field
PUT /contact-fields/:field_key

Define a custom contact field

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

پارامترنوعالزامیتوضیح
field_keystringبلهField key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars)
labelstringخیرLabel shown in the dashboard. Defaults to the key. (max 80 chars)
typestringخیرtext (default), number, or date. (one of text, number, date)
Returns{key, label, type, createdAt}.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "set_contact_field",
  "arguments": {
    "field_key": "plan",
    "label": "Plan",
    "type": "text"
  }
}
Destructivedelete_contact_field
DELETE /contact-fields/:field_key

Delete a custom field definition

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

پارامترنوعالزامیتوضیح
field_keystringبلهField key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_contact_field",
  "arguments": {
    "field_key": "plan"
  }
}
Read-onlylist_segments
GET /segments

List segments

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

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [{id, name, match, conditions, count}], count, fields, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_segments",
  "arguments": {}
}
Read-onlyget_segment
GET /segments/:segment_id

Get a segment

Campaigns: One segment with its conditions and live count.

پارامترنوعالزامیتوضیح
segment_idstringبلهSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
Returns{id, name, match, conditions, count}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_segment",
  "arguments": {
    "segment_id": "seg_123"
  }
}
Read-onlypreview_segment
POST /segments/preview

Preview segment conditions

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

پارامترنوعالزامیتوضیح
matchstringخیرall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]خیرUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringبلهtag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystringخیرCustom field key when field is field. (max 40 chars)
conditions[].opstringبلهtag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,numberخیرRequired except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
Returns{count, sample: [contacts]}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "preview_segment",
  "arguments": {
    "match": "all",
    "conditions": [
      {
        "field": "tag",
        "op": "has",
        "value": "VIP"
      },
      {
        "field": "opened",
        "op": "in_last_days",
        "value": 90
      }
    ]
  }
}
Changes statecreate_segment
POST /segments

Create a segment

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

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

Update a segment

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

پارامترنوعالزامیتوضیح
segment_idstringبلهSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
namestringخیرSegment name. (max 120 chars)
matchstringخیرall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]خیرUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringبلهtag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystringخیرCustom field key when field is field. (max 40 chars)
conditions[].opstringبلهtag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,numberخیرRequired except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
ReturnsThe updated segment with its count.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "update_segment",
  "arguments": {
    "segment_id": "seg_123",
    "name": "Pro customers"
  }
}
Destructivedelete_segment
DELETE /segments/:segment_id

Delete a segment

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

پارامترنوعالزامیتوضیح
segment_idstringبلهSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_segment",
  "arguments": {
    "segment_id": "seg_123"
  }
}
Read-onlylist_lists
GET /lists

List contact lists

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

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [lists], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_lists",
  "arguments": {}
}
Changes statecreate_list
POST /lists

Create a list

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

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

Get a list

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

پارامترنوعالزامیتوضیح
list_idstringبلهList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
ReturnsThe list.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_list",
  "arguments": {
    "list_id": "lst_123"
  }
}
Changes stateupdate_list
PATCH /lists/:list_id

Update a list

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

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

Delete a list

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

پارامترنوعالزامیتوضیح
list_idstringبلهList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_list",
  "arguments": {
    "list_id": "lst_123"
  }
}
Changes stateadd_list_contacts
POST /lists/:list_id/contacts

Add contacts to a list

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

پارامترنوعالزامیتوضیح
list_idstringبلهList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idsstring[]خیرContact IDs (ct_…). (0–500 items)
emailsstring[]خیرContact email addresses. (0–500 items)
Returns{listId, added, notFound, list}.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "add_list_contacts",
  "arguments": {
    "list_id": "lst_123",
    "emails": [
      "ada@example.net"
    ]
  }
}
Destructiveremove_list_contact
DELETE /lists/:list_id/contacts/:contact_id

Remove a contact from a list

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

پارامترنوعالزامیتوضیح
list_idstringبلهList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idstringبلهContact ID (starts with ct_) or the contact's email address. (max 320 chars)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "remove_list_contact",
  "arguments": {
    "list_id": "lst_123",
    "contact_id": "ct_123"
  }
}
Read-onlylist_broadcasts
GET /broadcasts

List broadcasts

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

پارامترنوعالزامیتوضیح
statusstringخیرOnly broadcasts with this status. (one of draft, sending, sent, cancelled, failed)
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [broadcasts], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_broadcasts",
  "arguments": {}
}
Changes statecreate_broadcast
POST /broadcasts

Create a broadcast draft

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

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

Get a broadcast

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe broadcast.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Changes stateupdate_broadcast
PATCH /broadcasts/:broadcast_id

Edit a draft broadcast

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

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

Delete a draft broadcast

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast
POST /broadcasts/:broadcast_id/send

Send a broadcast

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
idempotency_keystringخیرهدر Idempotency-Key (حداکثر 200 کاراکتر). فقط برای تلاش مجدد همین درخواست دقیق دوباره از آن استفاده کنید. (حداکثر 200 کاراکتر)
ReturnsThe broadcast with status sending and totals.
نمونه params برای tools/call
{
  "name": "send_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "idempotency_key": "october-update"
  }
}
Destructivecancel_broadcast
POST /broadcasts/:broadcast_id/cancel

Cancel a broadcast

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe cancelled broadcast with totals.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "cancel_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Read-onlylist_broadcast_recipients
GET /broadcasts/:broadcast_id/recipients

List broadcast recipients

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
statusstringخیرOnly recipients with this outcome. (one of queued, sending, sent, held, skipped, failed)
activitystringخیرOnly recipients who did this. (one of opened, clicked, not_opened, not_delivered, bounced, complained, unsubscribed)
querystringخیرRecipient email contains this text. (max 200 chars)
includestringخیرlinks adds the links each recipient clicked (implied by activity: clicked). (one of links)
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [{contactId, email, status, skipReason, emailId, error, provider, deliveredAt, openedAt, clickedAt, opens, clicks, bouncedAt, complainedAt, unsubscribedAt, links?}], count, totals, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_broadcast_recipients",
  "arguments": {
    "broadcast_id": "bc_123",
    "status": "failed"
  }
}
Read-onlycheck_broadcast
GET /broadcasts/:broadcast_id/checks

Run a broadcast's pre-send checks

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Returns{ready, checks: [{id, level: ok|warn|block, label, detail}], audience: {total, matching}}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "check_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast_test
POST /broadcasts/:broadcast_id/test

Send a broadcast test

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
tostring[]خیرTest recipients (up to 5). (1–5 items)
contact_idstringخیرFill merge tags from this contact (ct_…). (max 320 chars)
rememberbooleanخیرSave to as the default test recipients.
Returns{data: [{to, id, status: sent|failed, error?}]}.
نمونه params برای tools/call
{
  "name": "send_broadcast_test",
  "arguments": {
    "broadcast_id": "bc_123",
    "to": [
      "owner@example.com"
    ]
  }
}
Sends real emailschedule_broadcast
POST /broadcasts/:broadcast_id/schedule

Schedule a broadcast

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
scheduled_atstringبلهWhen to send: ISO 8601 date-time with a timezone, at least a minute and at most a year ahead, e.g. 2026-11-10T09:00:00Z. (max 40 chars)
ReturnsThe broadcast with scheduledAt.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "schedule_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "scheduled_at": "2026-11-10T09:00:00Z"
  }
}
Changes stateunschedule_broadcast
POST /broadcasts/:broadcast_id/unschedule

Unschedule a broadcast

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe draft broadcast.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "unschedule_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Changes stateduplicate_broadcast
POST /broadcasts/:broadcast_id/duplicate

Duplicate a broadcast

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe new draft broadcast.
نمونه params برای tools/call
{
  "name": "duplicate_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast_to_more
POST /broadcasts/:broadcast_id/send-more

Send a broadcast to more people

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
limitintegerبلهHow many more people at most. (1–10000000)
idempotency_keystringخیرهدر Idempotency-Key (حداکثر 200 کاراکتر). فقط برای تلاش مجدد همین درخواست دقیق دوباره از آن استفاده کنید. (حداکثر 200 کاراکتر)
Returns{added, broadcast}.
نمونه params برای tools/call
{
  "name": "send_broadcast_to_more",
  "arguments": {
    "broadcast_id": "bc_123",
    "limit": 500,
    "idempotency_key": "october-update-more-1"
  }
}
Read-onlyget_broadcast_report
GET /broadcasts/:broadcast_id/report

Get a broadcast report

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

پارامترنوعالزامیتوضیح
broadcast_idstringبلهBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Returns{stats: {sent, delivered, opened, clicked, bounced, complained, unsubscribed, opens, clicks, rates}, providers, links, timeline, average, machine, tracking, totals, remaining}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_broadcast_report",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Read-onlyget_newsletter_settings
GET /newsletter-settings

Get newsletter settings

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

بدون پارامتر.

Returns{postalAddress, design: {accentColor, font, align}, cleanup: {enabled, afterSends, quietDays, subject, body, from}, testRecipients}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_newsletter_settings",
  "arguments": {}
}
Changes stateupdate_newsletter_settings
PATCH /newsletter-settings

Update newsletter settings

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

پارامترنوعالزامیتوضیح
postal_addressstringخیرSender's postal address for the footer. Empty string removes it. (max 300 chars)
designobjectخیرRendering design for Markdown and block content.
design.accentColorstring,nullخیرHex color like #0a7d4f, or null for the default.
design.fontstringخیرFont family. (one of sans, serif, mono)
design.alignstringخیرText alignment. (one of left, center)
cleanupobjectخیرList cleanup of readers who stopped opening.
cleanup.enabledbooleanخیرTurn list cleanup on or off.
cleanup.afterSendsintegerخیرBroadcasts in a row without an open or click (3-50). (3–50)
cleanup.quietDaysintegerخیرDays without engagement (30-730). (30–730)
cleanup.subjectstring,nullخیرSubject of the cleanup email; merge tags allowed. (max 200 chars)
cleanup.bodystring,nullخیرBody text of the cleanup email. (max 2000 chars)
cleanup.fromstring,nullخیرSender on a verified domain. Defaults to the last sent broadcast's sender. (max 320 chars)
test_recipientsstring[]خیرDefault addresses for send_broadcast_test (up to 5). (0–5 items)
ReturnsThe updated settings.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "update_newsletter_settings",
  "arguments": {
    "postal_address": "Acme Inc., 1 Main St, Springfield",
    "design": {
      "accentColor": "#0a7d4f"
    }
  }
}
Read-onlyget_campaign_overview
GET /campaigns/overview

Get campaign overview

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

پارامترنوعالزامیتوضیح
daysintegerخیرWindow in days, 7 to 365. Defaults to 30. (7–365)
Returns{subscribers: {active, dormant, pending, joined, left}, series: [{day, subscribers, joined, left}], recent: [{id, name, subject, status, startedAt, sent, openRate, clickRate}], averages}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_campaign_overview",
  "arguments": {
    "days": 30
  }
}
Read-onlylist_uploaded_images
GET /uploads/images

List uploaded images

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

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [{id, url, width, height, size, filename, createdAt}], pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_uploaded_images",
  "arguments": {}
}

Automations, events, and sending limits

Sends real emailtrack_event
POST /events

Record something a contact did

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

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

List automations

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

پارامترنوعالزامیتوضیح
domainstringخیرOnly the automations that send from this domain: the exact domain of their from_address (e.g. example.com), or none for automations with no sender yet. (max 253 chars)
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [{id, key, name, domain, audience_label, goal_label, status, entry, exit_rules, position, settings, from_name, from_address, reply_to, switched_on_at, created_at, updated_at} plus steps_count and totals], count, domains: [{domain, count}], pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_automations",
  "arguments": {
    "domain": "example.com"
  }
}
Read-onlyget_automation
GET /automations/:automation_key

Get an automation

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
ReturnsThe automation (with domain, the domain of its from_address, or null) with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), enrollments {active, waiting}, overlap [{key, name, contacts, position, goes_first}], merge_fields [{key, label}]: the merge tags its emails print, in plain words, and to_fill [{id, position, locale, where, placeholder, key, message}].
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Changes statecreate_automation
POST /automations

Create an automation

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

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

Edit an automation

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

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

Delete an automation

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Changes stateset_automation_step
PUT /automations/:automation_key/steps/:position

Create or change an email of an automation

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

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

Remove an email from an automation

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerبلهPosition of the email in the automation, 1 to 50. (1–50)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_automation_step",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 3
  }
}
Changes stateset_automation_step_variant
PUT /automations/:automation_key/steps/:position/variants/:locale

Create or change a language version of an email

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerبلهPosition of the email in the automation, 1 to 50. (1–50)
localestringبلهLanguage tag of the version, e.g. fr or pt-br. (max 35 chars)
subjectstringخیرSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstringخیرInbox preview line. (max 300 chars)
contentobjectخیرBlock document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html.
htmlstringخیرHTML body. The unsubscribe footer is added automatically.
textstringخیرمتن ساده.
Returns{locale, subject, preheader, content, html, text, updated_at}.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "set_automation_step_variant",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 1,
    "locale": "fr",
    "subject": "Vous hésitez encore ?",
    "html": "<p>Votre panier vous attend.</p>"
  }
}
Sends real emailset_automation_status
POST /automations/:automation_key/status

Turn an automation on or off

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
statusstringبلهon to start sending, off to stop. (one of on, off)
ReturnsThe automation: {id, key, name, domain, audience_label, goal_label, status, entry, exit_rules, position, settings, from_name, from_address, reply_to, switched_on_at, created_at, updated_at}.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "set_automation_status",
  "arguments": {
    "automation_key": "checkout-recovery",
    "status": "off"
  }
}
Sends real emailsend_automation_test_email
POST /automations/:automation_key/steps/:position/test

Send one automation email to yourself as a test

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerبلهPosition of the email in the automation, 1 to 50. (1–50)
localestringخیرSend the language version a contact with this language would get (such as fr or pt-br). Omit for the email as written. (max 35 chars)
sampleobjectخیرValues to print for merge tags, by key, in place of the stand-ins (first_name is Alex, and so on). email, product_name, and sender_name cannot be set.
dry_runbooleanخیرSend nothing; return the email as the test would deliver it.
Returns{to, position, locale, subject, id: em_…, status: sent|held}. With dry_run: {dry_run: true, to, from, position, locale, locales, subject, preheader, html, text, sample: [{key, label, value}]}.
نمونه params برای tools/call
{
  "name": "send_automation_test_email",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 1
  }
}
Sends real emailsend_automation_test
POST /automations/:automation_key/test

Send every email of an automation to yourself as tests

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
localestringخیرSend the language version a contact with this language would get (such as fr or pt-br). Omit for the email as written. (max 35 chars)
sampleobjectخیرValues to print for merge tags, by key, in place of the stand-ins (first_name is Alex, and so on). email, product_name, and sender_name cannot be set.
Returns{to, data: [{position, locale, subject, id: em_…, status: sent|held|failed, error?}], count, sent, failed, not_sent}.
نمونه params برای tools/call
{
  "name": "send_automation_test",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Sends real emailenroll_contact
POST /automations/:automation_key/enroll

Add a contact to an automation

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstringبلهEmail address of an existing contact. (max 320 chars)
propertiesobjectخیرUp to 50 values (string, number, or boolean; strings are cut at 500 characters), e.g. {"plan": "pro"}. Usable in the automation's emails as merge tags such as {{ plan }}. The names email, name, first_name, last_name, and fields are reserved.
anchor_atstringخیرThe moment the emails' offsets count from, ISO 8601 with a time zone. Defaults to now; may lie ahead for emails that lead up to a date. (max 40 chars)
ReturnsThe enrolment: {id, automation_key, contact_id, status, source, is_holdout, anchor_at, entered_at, next_due_at, exit_reason, ended_at, converted_at}.
نمونه params برای tools/call
{
  "name": "enroll_contact",
  "arguments": {
    "automation_key": "checkout-recovery",
    "email": "ada@example.net",
    "properties": {
      "plan": "pro"
    }
  }
}
Changes stateexit_contact
POST /automations/:automation_key/exit

Take a contact out of an automation

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstringبلهEmail address of the contact. (max 320 chars)
reasonstringخیرWhy, for the record (max 200 chars). Defaults to manual. (max 200 chars)
ReturnsThe ended enrolment: {id, automation_key, contact_id, status, source, is_holdout, anchor_at, entered_at, next_due_at, exit_reason, ended_at, converted_at}.
نمونه params برای tools/call
{
  "name": "exit_contact",
  "arguments": {
    "automation_key": "checkout-recovery",
    "email": "ada@example.net",
    "reason": "Asked support to stop"
  }
}
Read-onlypreview_automation
GET /automations/:automation_key/preview

Preview what an automation would send now

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{automation_key, status, evaluated_at, data: [{enrollment_id, contact_id, email, status, next_due_at, outcome, reason, until, step: {position, subject, locale}, behind: {key, name}, superseded}], count, counts, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "preview_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Read-onlyget_automations_overview
GET /automations/overview

Get results across all automations

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

پارامترنوعالزامیتوضیح
fromstringخیرFirst day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostringخیرLast day of the report as a UTC date (YYYY-MM-DD), inclusive.
domainstringخیرOnly the automations that send from this domain: the exact domain of their from_address (e.g. example.com), or none for automations with no sender yet. (max 253 chars)
Returns{from, to, totals: {entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}, series: [{day, entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}]}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_automations_overview",
  "arguments": {
    "from": "2026-10-20",
    "to": "2026-11-18"
  }
}
Read-onlyget_automation_report
GET /automations/:automation_key/report

Get the results of one automation

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
fromstringخیرFirst day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostringخیرLast day of the report as a UTC date (YYYY-MM-DD), inclusive.
Returns{automation: {key, name, status, goal_label}, from, to, totals, series: [{day, ...}], steps: [{step_id, position, subject, offset_seconds, archived, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}]}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_automation_report",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Read-onlylist_automation_people
GET /automations/:automation_key/people

List the people in an automation

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
didstringخیرWhat the people did. Defaults to entered. (one of entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, waiting)
stepintegerخیرOnly this email of the automation, by its position. (1–50)
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{automation_key, did, step, data: [{contact_id, email, name, contact_status, enrollment_id, enrollment_status, at, latest: {did, at, step_position, reason}}], count, next_cursor, counts, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_automation_people",
  "arguments": {
    "automation_key": "checkout-recovery",
    "did": "clicked"
  }
}
Read-onlyget_automation_person
GET /automations/:automation_key/people/:contact_id

Get one person's history in an automation

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

پارامترنوعالزامیتوضیح
automation_keystringبلهAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
contact_idstringبلهContact ID (starts with ct_) or the contact's email address. (max 320 chars)
Returns{automation_key, contact: {id, email, name, status}, enrollments: [{id, status, source, is_holdout, anchor_at, entered_at, next_due_at, last_sent_at, exit_reason, ended_at, converted_at, converted_send_id}], sends: [{id, enrollment_id, step_id, step_position, subject, status, skip_reason, locale, email_id, sent_at, delivered_at, opened_at, clicked_at, bounced_at, complained_at, unsubscribed_at, converted_at, open_count, machine_open_count, click_count, events: [{kind, machine, reason, position, url, country, at}]}], conversion: {enrollment_id, converted_at, goal_event, send_id, step_position}}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_automation_person",
  "arguments": {
    "automation_key": "checkout-recovery",
    "contact_id": "ct_123"
  }
}
Read-onlyget_sending_limits
GET /automation-settings

Get automation sending limits

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

بدون پارامتر.

Returns{max_emails, period_days, min_gap_hours, window_start, window_end, weekdays, default_timezone, product_name, sender_name, updated_at}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_sending_limits",
  "arguments": {}
}
Changes stateupdate_sending_limits
PUT /automation-settings

Update automation sending limits

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

پارامترنوعالزامیتوضیح
max_emailsintegerخیرMost automation emails one person may get in period_days. Default 2. (1–50)
period_daysintegerخیرThe period max_emails applies to, in days. Default 7. (1–90)
min_gap_hoursintegerخیرLeast time between two automation emails to one person, in hours. Default 44. (0–720)
window_startintegerخیرFirst hour of the day emails may go out, local time (0-23). Default 9. (0–23)
window_endintegerخیرHour sending stops, local time (1-24); must be later than window_start. Default 18. (1–24)
weekdaysinteger[]خیرDays emails may go out: 0 = Sunday to 6 = Saturday. Default [1, 2, 3, 4, 5]. (1–7 items)
default_timezonestringخیرIANA time zone used for contacts that have none, e.g. Europe/London. (max 64 chars)
product_namestringخیرYour product's name, for {{ product_name }}. (max 120 chars)
sender_namestringخیرWho the emails are from, for {{ sender_name }}. (max 120 chars)
ReturnsThe updated limits.
AnnotationهاidempotentHint
نمونه params برای tools/call
{
  "name": "update_sending_limits",
  "arguments": {
    "max_emails": 3,
    "min_gap_hours": 24,
    "default_timezone": "Europe/London"
  }
}
Read-onlylist_automation_templates
GET /automation-library

List automation templates

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

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{version, groups, data: [{id, kind, name, purpose, group, set, subject, preview_text, needs_consent, start: {entry, offset_seconds, goal_event, goal_label, skip_if_empty}, merge_keys, fill_in: [{kind, key, placeholder, label, example}]}], sets: [{id, kind, name, purpose, group, needs_consent, emails: [{template, offset_seconds}], start, merge_keys, fill_in}], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_automation_templates",
  "arguments": {}
}
Read-onlyget_automation_template
GET /automation-library/:template_id

Get an automation template

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

پارامترنوعالزامیتوضیح
template_idstringبلهId of a template or a set, as returned by list_automation_templates (e.g. welcome-note, checkout-not-finished, payment-failed-notices). (max 63 chars)
Returns{id, kind (email or set), name, purpose, group, set, needs_consent, start: {entry, goal_event, goal_label}, merge_keys, fill_in: [{kind, key, placeholder, label, example}], emails: [{template, name, offset_seconds, skip_if_empty, subject, preview_text, content, preview: {subject, preheader, text, html}}]}. preview.html is null.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_automation_template",
  "arguments": {
    "template_id": "welcome-note"
  }
}
Changes stateuse_automation_template
POST /automation-library/:template_id/use

Create an automation from a template

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

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

List what contacts did

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

پارامترنوعالزامیتوضیح
contactstringخیرOnly this contact: a contact ID or an email address. (max 320 chars)
namestringخیرOnly this event, e.g. checkout_started. See list_event_names. (max 64 chars)
fromstringخیرEvents from this UTC date (YYYY-MM-DD) or ISO 8601 date-time on. (max 40 chars)
tostringخیرEvents up to this UTC date (the whole day) or ISO 8601 date-time. (max 40 chars)
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [{id, contact: {id, email, name}, event, words, occurred_at, received_at, source: {type, label, connection_id}, properties, effects: [{did, automation_key, automation_name}]}], count, next_cursor, enrollments (with contact), pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_events",
  "arguments": {
    "name": "checkout_started",
    "from": "2026-11-01"
  }
}
Read-onlylist_event_names
GET /events/names

List the kinds of event recorded

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

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [{event, words, count}], count, days, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_event_names",
  "arguments": {}
}
Read-onlylist_connections
GET /connections

List connections

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

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
Returns{data: [{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus last_delivery {id, at, result, reason, recorded, events, text, provider_event, email}], count, limit, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_connections",
  "arguments": {}
}
Read-onlyget_connection
GET /connections/:connection_id

Get a connection and its last deliveries

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

پارامترنوعالزامیتوضیح
connection_idstringبلهConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
Returns{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus last_delivery and deliveries: [{id, at, result, reason, recorded, events, text, provider_event, email}].
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_connection",
  "arguments": {
    "connection_id": "acn_123"
  }
}
Sends real emailcreate_connection
POST /connections

Create a connection

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

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

Change a connection or switch it on or off

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

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

Delete a connection

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

پارامترنوعالزامیتوضیح
connection_idstringبلهConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
خروجی{ok: true}.
AnnotationهاdestructiveHint idempotentHint
نمونه params برای tools/call
{
  "name": "delete_connection",
  "arguments": {
    "connection_id": "acn_123"
  }
}

حساب، میزان مصرف، analytics و کلیدها

فقط‌خواندنیget_account
GET /account

دریافت حساب، میزان مصرف و صورتحساب

ایمیل مالک حساب، پلن/سطح دسترسی، تحویل به گیرندگان مصرف‌شده در دوره جاری در برابر سهمیه، دامنه‌های مصرف‌شده در برابر سقف، انتقال پیوست، خلاصه اعتبار، وضعیت اشتراک، پلن‌های منتشرشده و شمارش‌های فضای کاری. از آن برای بررسی سهمیه باقی‌مانده یا اینکه دوره آزمایشی به چه کسی می‌تواند تحویل دهد (ایمیل حساب) استفاده کنید.

بدون پارامتر.

خروجی{user: {email, …}, usage: {domainsUsed, domainLimit, recipientDeliveries, emailQuotaMonth, attachmentBytes, attachmentByteLimit, periodKey}, access: {tier, planCode}, reputation, infrastructure, billing: {status, subscriptions, …}, plans, workspace: {mailer, stats}}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_account",
  "arguments": {}
}
Read-onlyget_account_diagnostics
GET /account/diagnostics

Diagnose sending and receiving

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

بدون پارامتر.

Returns{generatedAt, windowDays, issues: [{severity, code, message}], plan: {tier, usage, sendingLimit}, domains: [{name, status, dkim: {required, verified, missing}, inbound}], sendingIdentities, inbound, deliverability: {sent, delivered, bounced, complained, rates, senders}, suppressions: {total, byReason, unsubscribes, recent}, failures: {notSent, recentNotSent, recentProviderEvents}, webhooks}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_account_diagnostics",
  "arguments": {}
}
فقط‌خواندنیget_analytics
GET /analytics

دریافت analytics ارسال

analytics داشبورد برای 7، 30 یا 90 روز گذشته: مجموع sent/received/delivered/bounced/blocked/opened/clicked/complaint، یک خط زمانی روزانه، دامنه‌های پرارسال و موضوع‌های پرتکرار.

پارامترنوعالزامیتوضیح
daysintegerخیربازه به روز: 7، 30 (پیش‌فرض) یا 90. (یکی از 7، 30، 90)
خروجی{window, days, metrics, timeline: [{day, sent, received}], domains, topContent}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_analytics",
  "arguments": {
    "days": 30
  }
}
فقط‌خواندنیlist_api_keys
GET /keys

فهرست فراداده کلیدهای API

نام کلیدهای API، پیشوندهای غیرمحرمانه و زمان آخرین استفاده را فهرست می‌کند. فقط‌خواندنی: این سرور MCP نمی‌تواند کلید بسازد، بچرخاند یا باطل کند؛ این کار را انسان در داشبورد انجام می‌دهد. صفحه‌بندی‌شده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.

پارامترنوعالزامیتوضیح
limitintegerخیراندازه صفحه. پیش‌فرض 50. (پیش‌فرض 50؛ 1 تا 200)
offsetintegerخیرتعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیش‌فرض 0؛ 0 تا …)
خروجی{data: [{id, name, prefix, lastUsedAt, createdAt}], count, pagination}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "list_api_keys",
  "arguments": {}
}
فقط‌خواندنیget_service_health
GET /health

بررسی سلامت سرویس SendHQ

بررسی می‌کند که API ‏SendHQ در دسترس است و کدام ارائه‌دهنده ایمیل فعال است. به کلید API معتبر نیاز ندارد.

بدون پارامتر.

خروجی{ok, service, mailer}.
AnnotationهاreadOnlyHint idempotentHint
نمونه params برای tools/call
{
  "name": "get_service_health",
  "arguments": {}
}

فهرست پوشش API

هر عملیات در API عمومی و ابزاری که آن را پوشش می‌دهد. هر کاری که کاربر در داشبورد می‌تواند انجام دهد و API دارد پوشش داده شده است؛ موارد مستثنای زیر عمدی هستند.

Endpointابزاریادداشت‌ها
POST /emailssend_emailارسال یک ایمیل
POST /emails/batchsend_batchارسال حداکثر 100 پیام شخصی‌سازی‌شده
GET /emailslist_emailsفهرست ایمیل‌های ارسالی و دریافتی
GET /emails/:idget_emailدریافت یک ایمیل و پیوست‌های آن
PATCH /emails/:idmark_emailبه‌روزرسانی وضعیت خوانده‌شدن، بایگانی، اسپم، دسته یا اهمیت
POST /emails/:id/labelslabel_emailافزودن یا حذف برچسب‌های یک ایمیل
DELETE /emails/:iddelete_emailحذف یک ایمیل نگهداری‌شده
GET /emails/:id/eventslist_email_eventsفهرست رویدادهای تحویل یک ایمیل
GET /threads/:idget_threadدریافت یک مکالمه به ترتیب زمانی
GET /labelslist_labelsفهرست برچسب‌ها همراه با تعداد پیام‌ها و قوانین بایگانی
POST /labelscreate_labelساخت برچسب، به‌صورت اختیاری همراه با قوانین بایگانی خودکار
GET /labels/:idget_labelدریافت یک برچسب با شناسه یا نام
PATCH /labels/:idupdate_labelتغییر نام، تغییر رنگ یا تبدیل برچسب به bucket
DELETE /labels/:iddelete_labelحذف یک برچسب بدون حذف ایمیل‌های آن
POST /labels/:id/rulescreate_label_ruleافزودن قانون بایگانی خودکار به یک برچسب
DELETE /labels/:id/rules/:rule_iddelete_label_ruleحذف یک قانون بایگانی خودکار
POST /draftscreate_draftساخت پیش‌نویس در ویرایشگر
GET /draftslist_draftsفهرست پیش‌نویس‌های ویرایشگر
GET /drafts/:idget_draftدریافت یک پیش‌نویس و پیوست‌های آن
PUT /drafts/:idupdate_draftجایگزینی محتوای پیش‌نویس
DELETE /drafts/:iddelete_draftدور ریختن پیش‌نویس
POST /drafts/:id/attachmentsupload_attachmentبارگذاری پیوست در یک پیش‌نویس
GET /attachments/:iddownload_attachmentدانلود یک پیوست خصوصی
DELETE /attachments/:iddelete_attachmentحذف یک پیوست خصوصی
GET /sending-identitieslist_sending_identitiesفهرست هویت‌های فرستنده تأییدشده
GET /templateslist_templatesفهرست قالب‌های میزبانی‌شده
POST /templatescreate_templateساخت قالب میزبانی‌شده
GET /templates/:idget_templateدریافت پیش‌نویس‌ها، نسخه‌های منتشرشده و میزان استفاده
PUT /templates/:id/draftupdate_template_draftذخیره خودکار پیش‌نویس قالب
POST /templates/:id/draftcreate_template_draftساخت پیش‌نویس جدید از نسخه منتشرشده
POST /templates/:id/renderrender_templateرندر خروجی دقیق سرور
POST /templates/:id/testsend_template_testارسال یک snapshot آزمایشی
POST /templates/:id/publishpublish_templateانتشار یک نسخه تغییرناپذیر از قالب
POST /templates/:id/archivearchive_templateبایگانی قالب
POST /templates/:id/restorerestore_templateبازیابی قالب بایگانی‌شده
POST /domainsadd_domainافزودن دامنه ارسال
GET /domainslist_domainsفهرست دامنه‌ها و وضعیت ذخیره‌شده DNS
GET /domains/:idget_domainدریافت جزئیات راه‌اندازی دامنه
POST /domains/:id/verifyverify_domainRefresh domain and DNS verification
POST /domains/:id/inbound/setupsetup_inboundProvision inbound receiving
POST /domains/:id/inbound/verifyverify_inboundتأیید مسیریابی MX ورودی
DELETE /domains/:iddelete_domainحذف دامنه
GET /dns/providerget_dns_providerتشخیص ارائه‌دهنده DNS معتبر (authoritative) و hostهای نسبی رکوردها
GET /dns/domain-connect/connectget_domain_connect_linkساخت لینک رضایت Domain Connect برای راه‌اندازی یک‌کلیکی DNS
POST /inboxescreate_inboxساخت نشانی ورودی
GET /inboxeslist_inboxesفهرست نشانی‌های ورودی
GET /inboxes/:idget_inboxدریافت یک نشانی ورودی
PATCH /inboxes/:idupdate_inboxتغییر نام، فعال یا غیرفعال کردن صندوق ورودی
PUT /inboxes/:id/forwardingset_inbox_forwardingفوروارد ایمیل‌های دریافتی یک صندوق ورودی به نشانی دیگر
DELETE /inboxes/:iddelete_inboxحذف صندوق ورودی با حفظ پیام‌ها
GET /deliverability/statsdeliverability_statsدریافت آمار تحویل 30 روز اخیر
GET /deliverability/reputationlist_sender_reputationفهرست وضعیت اعتبار به تفکیک دقیق هویت فرستنده
GET /deliverability/accountdeliverability_accountAccount delivery rates, daily ladder, and bounce trend
GET /deliverability/domainsdeliverability_domainsPer-domain sent, delivered, hard and soft bounces, complaints, and failures
GET /deliverability/sendersdeliverability_sendersPer-From-address delivery rates
POST /deliverability/scorescore_emailScore an email's content before it is sent
GET /emails/:id/deliveryemail_deliveryDelivery timeline for one email, with bounce and complaint reasons
GET /threads/:id/deliverythread_deliveryPer-thread delivery counts and per-message failure reasons
GET /suppressionslist_suppressionsفهرست موارد توقف ارسال فضای کاری
DELETE /suppressions/:emailremove_suppressionحذف یک مورد توقف ارسال ناشی از برگشت ایمیل که واجد شرایط حذف است
GET /blocked-recipientslist_blocked_recipientsفهرست برگشت‌ها، گزارش‌های اسپم و لغو اشتراک‌ها
GET /webhooksدر دسترس نیستWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooksدر دسترس نیستWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:idدر دسترس نیستWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
PATCH /webhooks/:idدر دسترس نیستWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
DELETE /webhooks/:idدر دسترس نیستWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/rotate-secretدر دسترس نیستWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/testدر دسترس نیستWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:id/deliveriesدر دسترس نیستWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:id/deliveries/:deliveryIdدر دسترس نیستWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/deliveries/:deliveryId/retryدر دسترس نیستWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /contactslist_contactsList contacts
POST /contactscreate_contactAdd a contact with its consent basis
PUT /contactsupsert_contactCreate or update a contact by email
POST /contacts/bulkbulk_update_contactsTag, move, unsubscribe, or delete many contacts at once
GET /contacts/exportدر دسترس نیستImage uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
GET /contacts/:idget_contactRetrieve a contact by ID or email
PATCH /contacts/:idupdate_contactUpdate a contact's name, fields, or tags, or unsubscribe it
DELETE /contacts/:iddelete_contactDelete a contact and its list memberships
POST /contact-importsimport_contactsImport contacts from CSV
GET /contact-importslist_contact_importsList recent contact imports
GET /tagslist_tagsList contact tags with how many contacts carry each
GET /contact-fieldslist_contact_fieldsList custom contact field definitions
PUT /contact-fields/:keyset_contact_fieldDefine or change a custom contact field
DELETE /contact-fields/:keydelete_contact_fieldDelete a custom field definition
GET /segmentslist_segmentsList saved segments with live counts
POST /segmentscreate_segmentSave a segment
POST /segments/previewpreview_segmentCount and sample the contacts that match unsaved conditions
GET /segments/:idget_segmentRetrieve a segment and its live count
PATCH /segments/:idupdate_segmentRename a segment or change its conditions
DELETE /segments/:iddelete_segmentDelete a segment
GET /listslist_listsList contact lists with member counts
POST /listscreate_listCreate a list with an optional signup form, welcome email, and newsletter site
GET /lists/:idget_listRetrieve a list
PATCH /lists/:idupdate_listRename a list or change its signup form, welcome email, or site
DELETE /lists/:iddelete_listDelete a list without deleting its contacts
POST /lists/:id/contactsadd_list_contactsAdd existing contacts to a list
DELETE /lists/:id/contacts/:contact_idremove_list_contactRemove a contact from a list
GET /broadcastslist_broadcastsList broadcasts
POST /broadcastscreate_broadcastCreate a broadcast draft
GET /broadcasts/:idget_broadcastRetrieve a broadcast and its delivery totals
PATCH /broadcasts/:idupdate_broadcastEdit a draft broadcast
DELETE /broadcasts/:iddelete_broadcastDelete a draft broadcast
GET /broadcasts/:id/checkscheck_broadcastRun the pre-send checks for a broadcast
POST /broadcasts/:id/testsend_broadcast_testSend a test copy of a draft
POST /broadcasts/:id/scheduleschedule_broadcastSchedule a draft to send later
POST /broadcasts/:id/unscheduleunschedule_broadcastUnschedule a draft
POST /broadcasts/:id/duplicateduplicate_broadcastCopy a broadcast into a new draft
POST /broadcasts/:id/sendsend_broadcastSend a broadcast to its audience
POST /broadcasts/:id/send-moresend_broadcast_to_moreSend a sent broadcast to more of its audience
POST /broadcasts/:id/cancelcancel_broadcastCancel a draft or sending broadcast
GET /broadcasts/:id/recipientslist_broadcast_recipientsList a broadcast's recipients, outcomes, and engagement
GET /broadcasts/:id/reportget_broadcast_reportRetrieve a broadcast's engagement report
GET /campaigns/overviewget_campaign_overviewRetrieve subscriber growth and recent broadcast performance
GET /newsletter-settingsget_newsletter_settingsRetrieve newsletter settings
PATCH /newsletter-settingsupdate_newsletter_settingsChange newsletter settings
POST /uploads/imagesدر دسترس نیستImage uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
GET /uploads/imageslist_uploaded_imagesList recently uploaded images
POST /eventstrack_eventRecord something a contact did
POST /events/batchدر دسترس نیستHistory import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
GET /automationslist_automationsList automations with their 30-day totals
POST /automationscreate_automationCreate an automation as a draft
GET /automations/:keyget_automationRetrieve an automation with its emails
PATCH /automations/:keyupdate_automationEdit an automation
DELETE /automations/:keydelete_automationDelete an automation and its history
PUT /automations/:key/steps/:positionset_automation_stepCreate or change one email of an automation
DELETE /automations/:key/steps/:positiondelete_automation_stepRemove one email from an automation
PUT /automations/:key/steps/:position/variants/:localeset_automation_step_variantCreate or change a language version of an email
POST /automations/:key/steps/:position/testsend_automation_test_emailSend one email of an automation to yourself as a test
POST /automations/:key/testsend_automation_testSend every email of an automation to yourself as tests
POST /automations/:key/statusset_automation_statusTurn an automation on or off
POST /automations/:key/enrollenroll_contactAdd a contact to an automation
POST /automations/:key/exitexit_contactTake a contact out of an automation
GET /automations/:key/previewpreview_automationDry run: what each person in an automation would get now
GET /automations/overviewget_automations_overviewTotals and a daily series across every automation
GET /automations/:key/reportget_automation_reportResults of one automation, with one row per email
GET /automations/:key/peoplelist_automation_peopleList the people in an automation by what they did
GET /automations/:key/people/:contact_idget_automation_personOne person's history in an automation
POST /automations/:key/import-historyدر دسترس نیستHistory import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
GET /automation-settingsget_sending_limitsRetrieve the workspace's sending limits for automations
PUT /automation-settingsupdate_sending_limitsChange the workspace's sending limits for automations
GET /automation-librarylist_automation_templatesList the template library: ready-made lifecycle emails
GET /automation-library/:idget_automation_templateRead one template or set, with the email as it will look
POST /automation-library/:id/useuse_automation_templateCreate a draft automation from a template or set
GET /eventslist_eventsList what contacts did, newest first
GET /events/nameslist_event_namesList the kinds of event recorded in the last 30 days
POST /events/previewدر دسترس نیستThese answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.
GET /connectionslist_connectionsList the workspace's connections (incoming webhooks)
POST /connectionscreate_connectionCreate a connection and get its address
POST /connections/testدر دسترس نیستThese answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.
GET /connections/:idget_connectionRetrieve a connection with its last deliveries
PATCH /connections/:idupdate_connectionChange a connection or switch it on or off
DELETE /connections/:iddelete_connectionDelete a connection
POST /connections/:id/addressدر دسترس نیستThe address is a credential: whoever holds it can record events for the workspace. Replacing it cuts off the system that uses the old one, so a person does it in the dashboard, next to that system's own settings.
GET /accountget_accountدریافت حساب، میزان مصرف، وضعیت صورتحساب و شمارش‌های فضای کاری با کلید API
GET /account/diagnosticsget_account_diagnosticsDiagnose sending and receiving problems in the workspace
GET /analyticsget_analyticsدریافت analytics ارسال داشبورد برای 7، 30 یا 90 روز
GET /profileget_accountنسخه مبتنی بر نشست (session) از GET /account؛ سرور MCP مسیر مبتنی بر کلید API را می‌خواند.
POST /billing/checkoutدر دسترس نیستتغییرات صورتحساب طبق طراحی فقط از طریق نشست انجام می‌شوند و به حضور مالک حساب در داشبورد نیاز دارند. وضعیت صورتحساب با get_account قابل‌خواندن است.
POST /billing/cancelدر دسترس نیستتغییرات صورتحساب طبق طراحی فقط از طریق نشست انجام می‌شوند و به حضور مالک حساب در داشبورد نیاز دارند. وضعیت صورتحساب با get_account قابل‌خواندن است.
POST /keysدر دسترس نیستعمداً مستثنا شده است: ایجنت نباید اعتبارنامه بسازد یا از بین ببرد. کلیدها را انسان در داشبورد مدیریت می‌کند.
GET /keyslist_api_keysفهرست فراداده کلیدهای API
DELETE /keys/:idدر دسترس نیستعمداً مستثنا شده است: ایجنت نباید اعتبارنامه بسازد یا از بین ببرد. کلیدها را انسان در داشبورد مدیریت می‌کند.

عمداً در دسترس نیست

قابلیتendpointهادلیل
ساخت، چرخش، ابطال یا حذف کلیدهای APIPOST /keys, DELETE /keys/:idعمداً مستثنا شده است: ایجنت نباید اعتبارنامه بسازد یا از بین ببرد. کلیدها را انسان در داشبورد مدیریت می‌کند.
شروع پرداخت (checkout) یا لغو اشتراکPOST /billing/checkout, POST /billing/cancelتغییرات صورتحساب طبق طراحی فقط از طریق نشست انجام می‌شوند و به حضور مالک حساب در داشبورد نیاز دارند. وضعیت صورتحساب با get_account قابل‌خواندن است.
DNS یک‌کلیکی Cloudflare ‏(OAuth)GET /api/dns/cloudflare/connectبه یک نشست تعاملی مرورگر و رضایت OAuth در Cloudflare نیاز دارد. به‌جای آن از رکوردهای get_domain، hostهای get_dns_provider یا get_domain_connect_link استفاده کنید.
ثبت‌نام، ورود، خروج، اتصال حساب Google/api/auth/*احراز هویت انسانی در مرورگر؛ سرور MCP با کلید API احراز هویت می‌کند.
فرم تماس با پشتیبانیPOST /api/contactفرم عمومی وب‌سایت برای انسان‌ها، نه یک عملیات فضای کاری.
Webhook endpoints and deliveriesGET /webhooks, POST /webhooks, GET /webhooks/:id, PATCH /webhooks/:id, DELETE /webhooks/:id, POST /webhooks/:id/rotate-secret, POST /webhooks/:id/test, GET /webhooks/:id/deliveries, GET /webhooks/:id/deliveries/:deliveryId, POST /webhooks/:id/deliveries/:deliveryId/retryWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
Upload editor images and export contacts as CSVPOST /uploads/images, GET /contacts/exportImage uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
Import an automation's send history and record events in bulkPOST /automations/:key/import-history, POST /events/batchHistory import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
Move SendHQ's own win-back emails onto automations (backfill and comparison)POST /automations/platform-backfill, GET /automations/platform-compareInternal cutover tools for SendHQ's own workspace only: they answer nobody else, need its owner's dashboard session, and are not part of the public API or of /api/v1. The backfill enrols SendHQ's own accounts, so it is run by a person, one page at a time, after reading the dry run.
Replace a connection's secret addressPOST /connections/:id/addressThe address is a credential: whoever holds it can record events for the workspace. Replacing it cuts off the system that uses the old one, so a person does it in the dashboard, next to that system's own settings.
Dry runs for a sample payload and for a set of eventsPOST /connections/test, POST /events/previewThese answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.

کاتالوگ قابل‌خواندن برای ماشین: /docs/mcp/tools.json (schemaها، annotationها، نگاشت endpointها، موارد مستثنا). نسخه Markdown این صفحه: /docs/mcp.md. با نصب CLI، دستور sendhq commands --format json همین کاتالوگ را چاپ می‌کند.