برای ایجنتهای هوش مصنوعی
سرور 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 109 strictly typed tools. Written for agents first; humans welcome.
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcpاین سرور چیست
The SendHQ MCP server lets an AI agent operate one SendHQ workspace through the Model Context Protocol: send email (single, batch, templated, replies, attachments, idempotent retries), read and search sent and received mail (subjects, bodies, and attachment names) and its delivery events, organize mail into labels with auto-filing rules, manage drafts and private attachments, author and publish hosted templates, add and verify domains and their DNS, set up inbound receiving and inbound addresses, inspect deliverability, bounces, complaints, and suppressions, run newsletters (consented contacts with tags and custom fields, segments, lists with signup forms, welcome emails, and newsletter sites, and broadcasts with pre-send checks, test sends, scheduling, and bot-filtered open and click reports), and read account usage, billing state, analytics, and API-key metadata.
این یک سرور محلی stdio است که در فایل اجرایی CLI sendhq تعبیه شده است. کلاینت MCP شما sendhq mcp را بهعنوان یک پردازه فرزند اجرا میکند و از طریق stdin/stdout با JSON-RPC ارتباط برقرار میکند. هر فراخوانی ابزار به یک درخواست مستند به REST API SendHQ در https://sendhq.cc/api/v1 تبدیل میشود که با کلید API فضای کاری شما احراز هویت شده است؛ بنابراین سرور MCP دقیقاً مجوزهای همان کلید را دارد و نه بیشتر.
- 109 tools in 9 groups, generated from one catalog that is also published as tools.json.
- JSON Schemaهای سختگیرانه: آرگومانهای ناشناخته، نوعهای اشتباه و فیلدهای الزامی جاافتاده پیش از رسیدن هر چیزی به SendHQ، بهصورت محلی رد میشوند.
- خطاهای ساختاریافته با یک
codeپایدار،statusHTTP، یکexplanation، یکremedyمشخص و اینکه آیا تلاش مجدد کمکی میکند یا نه. - هر ابزاری که ایمیل واقعی ارسال میکند یا دادهای را از بین میبرد، این موضوع را در نخستین کلمات توضیح خود اعلام میکند و annotationهای ایمنی MCP دارد.
- حالت
--read-onlyهمه ابزارهای ارسال و تغییردهنده را پنهان میکند. - هیچ چیزی لاگ نمیشود. stdout فقط پیامهای پروتکل را حمل میکند؛ کلید API و محتوای پیام هرگز به هیچ لاگی نمیرسند.
https://sendhq.cc/api/mcp میزبانی میکند (جستجوی قیمتها و مستندات، بدون دسترسی به حساب). سروری که در این صفحه معرفی میشود، نسخه کامل و محدود به حساب است؛ بهصورت محلی یا بهعنوان connector میزبانیشده زیر اجرا میشود.Use SendHQ in Claude, ChatGPT and Grok
بدون نیاز به نصب: SendHQ این سرور را با همان ابزارها بهعنوان یک connector میزبانیشده در https://mcp.sendhq.cc/mcp نیز اجرا میکند. بهجای چسباندن کلید، با حساب SendHQ خود وارد میشوید.
Claude
- Settings → Connectors را باز کنید و SendHQ را در فهرست پیدا کنید، یا Add custom connector را انتخاب کنید و
https://mcp.sendhq.cc/mcpرا بچسبانید. - روی Connect کلیک کنید، وارد SendHQ شوید، دسترسیها را بازبینی کنید و روی Allow کلیک کنید.
- از Claude بخواهید صندوق ورودی شما را بررسی کند، از دامنه تأییدشدهتان ایمیل بفرستد یا یک برگشت ایمیل را توضیح دهد.
ChatGPT
- Open Settings → Security and login and turn on Developer mode.
- Go to chatgpt.com/plugins, click Create MCP app, name it SendHQ and enter
https://mcp.sendhq.cc/mcp. - Sign in to SendHQ and click Allow, then pick SendHQ from the tools menu in a new chat.
Grok
- Go to grok.com/connectors, click New Connector, then Custom.
- Enter
https://mcp.sendhq.cc/mcp, sign in to SendHQ and click Allow.
Muse by Meta
In Muse, open Connectors and search for SendHQ. Click Connect, sign in to SendHQ and click Allow.
تأیید و قطع اتصال
- The
request_featuretool sends a feature request to the SendHQ team with your account details, so we can follow up by email. - ابزارهایی که ایمیل واقعی ارسال میکنند یا داده حذف میکنند به همین صورت برچسب خوردهاند. اینکه دستیار پیش از اجرا از شما بپرسد یا نه، برای هر ابزار در خود دستیار تنظیم میشود: در Claude، برای این ابزارها در Settings → Connectors → SendHQ گزینه Needs approval را انتخاب کنید.
- 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 قرار میدهد.
curl -fsSL https://downloads.sendhq.cc/install.sh | shirm https://downloads.sendhq.cc/install.ps1 | iexsendhq version
SENDHQ_API_KEY=re_your_key sendhq doctorیک کلید API در داشبورد به نشانی https://sendhq.cc/app#/keys بسازید. سرور MCP نمیتواند کلید بسازد. تنها دستوری که سرور را اجرا میکند این است:
SENDHQ_API_KEY=re_your_key sendhq mcpمعمولاً هرگز لازم نیست آن را دستی اجرا کنید: کلاینت MCP آن را راهاندازی میکند. اگر در ترمینال اجرا شود، منتظر JSON-RPC روی stdin میماند.
پیکربندی کلاینت
Claude Code
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp
# read-only variant
claude mcp add sendhq-readonly --env SENDHQ_API_KEY=re_your_key -- sendhq mcp --read-onlyبرای در دسترس بودن در همه پروژهها --scope user را اضافه کنید، یا --scope project را اضافه کنید تا در .mcp.json پروژه نوشته شود. برای یک .mcp.json مشترک، بهجای commit کردن کلید، از متغیر محیطی به آن ارجاع دهید؛ Claude Code عبارت ${VAR} را در .mcp.json جایگذاری میکند.
{
"mcpServers": {
"sendhq": {
"command": "sendhq",
"args": [
"mcp"
],
"env": {
"SENDHQ_API_KEY": "${SENDHQ_API_KEY}"
}
}
}
}OpenAI Codex
[mcp_servers.sendhq]
command = "sendhq"
args = ["mcp"]
env = { SENDHQ_API_KEY = "re_your_key" }یا از خط فرمان: codex mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp.
Claude Desktop
فایل claude_desktop_config.json را ویرایش کنید (macOS: ~/Library/Application Support/Claude/، Windows: %APPDATA%\Claude\) و برنامه را دوباره راهاندازی کنید. برنامههای دسکتاپ PATH شل شما را به ارث نمیبرند، پس از مسیر مطلق فایل اجرایی (which sendhq) استفاده کنید.
{
"mcpServers": {
"sendhq": {
"command": "/Users/you/.local/bin/sendhq",
"args": [
"mcp"
],
"env": {
"SENDHQ_API_KEY": "re_your_key"
}
}
}
}هر کلاینت MCP دیگر
یک سرور 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 دارند.
{"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), andsend_broadcast_to_moredeliver mail to real people and consume delivery credits. Their descriptions start withSENDS REAL EMAIL. Call them only when the user explicitly asked for that specific message to be sent, with the recipients, sender, and content confirmed. - Destructive.
delete_email,delete_draft,delete_attachment,delete_domain,delete_inbox,remove_suppression, the campaign deletes (delete_contact,delete_list,remove_list_contact,delete_broadcast,cancel_broadcast,delete_segment,delete_contact_field), andbulk_update_contactsare markeddestructiveHint: trueand their descriptions start withDESTRUCTIVE. Confirm with the user first.remove_suppressionweakens a safety block and is appropriate only when a human confirms the address works again. - تغییر وضعیت میدهد. ساخت یا بهروزرسانی پیشنویسها، قالبها، دامنهها و صندوقهای ورودی، انتشار قالبها و آغاز تأیید، فضای کاری را تغییر میدهند اما ایمیلی ارسال نمیکنند.
- فقطخواندنی. همه موارد دیگر
readOnlyHint: trueهستند و فراخوانی آزادانه آنها امن است. - این سرور هرگز DNS را تغییر نمیدهد.
add_domainرکوردهایی را برمیگرداند که یک انسان باید منتشر کند؛get_domain_connect_linkیک 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 (machineinget_broadcast_report). - برای دور زدن توقف
423به نشانی From دیگری تغییر ندهید و هرگز گیرندگانی را که لغو اشتراک کرده یا گزارش اسپم دادهاند دوباره اضافه نکنید.
کلیدهای API خارج از محدودهاند
طبق طراحی، هیچ ابزاری برای ساخت، تغییر، چرخش، ابطال یا حذف کلیدهای API وجود ندارد. ایجنت نباید اعتبارنامه بسازد یا از بین ببرد. list_api_keys فقط نامها، پیشوندهای غیرمحرمانه و زمان آخرین استفاده را برمیگرداند. مدیریت کلیدها در داشبورد و توسط انسانی که وارد شده باقی میماند.
گردشکارها
1. اولین ارسال
get_service_healthدر دسترس بودن API را تأیید میکند (بدون کلید هم کار میکند).get_accountshows the plan (access.tier) and remaining quota. If there is no active plan, do not send: the call returnssubscription_required.list_sending_identitiesنشانیهای From قابلاستفاده را فهرست میکند. اگر خالی بود، ابتدا گردشکار دامنه را انجام دهید.- فرستنده، گیرنده، موضوع و متن را با کاربر تأیید کنید، سپس
send_emailرا با یکidempotency_keyفراخوانی کنید. 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. تأیید دامنه از ابتدا تا انتها
add_domainwithname: "example.com". The result includes the DNS records (DKIM CNAMEs, domain verification, SPF, recommended DMARC).get_dns_providerباdomain_idارائهدهنده DNS معتبر (authoritative) را تشخیص میدهد و host نسبی دقیقی را که باید برای هر رکورد نزد آن ارائهدهنده وارد شود برمیگرداند.- If
providers.domainConnect.availableis true,get_domain_connect_linkreturns a consent URL. Give it to the human; nothing changes until they approve at the provider. Otherwise, give the human the records to publish. Never publish a second SPF record: merge SendHQ's SPF include (include:amazonses.com) into the existingv=spf1value. verify_domainrechecks DNS and DKIM verification. Status moves throughpending,checking, andpropagatingtoverified. Pollverify_domainorget_domainevery 30–60 seconds; DNS can take minutes to hours.- وقتی
statusبرابرverifiedشد، نشانیهای دامنه درlist_sending_identitiesظاهر میشوند.
3. برگشتها، گزارشهای اسپم و فهرست توقف ارسال
list_blocked_recipientsهمه نشانیهای مسدودشده را همراه با دلیل (bounce،complaint،unsubscribe) و یک شمارش خلاصه برمیگرداند.list_suppressionsموارد توقف ارسال ناشی از برگشت دائمی و گزارش اسپم را برمیگرداند؛deliverability_statsنرخهای 30 روزه تحویل، برگشت و گزارش اسپم را میدهد؛list_sender_reputationنشان میدهد کدام نشانیهای From محدود یا متوقف شدهاند.- ارسالی که شامل گیرندهای در فهرست توقف ارسال باشد با
422 recipient_suppressedشکست میخورد. آن گیرنده را حذف کنید و دوباره ارسال کنید. - فقط وقتی انسانی تأیید کند که صندوق ایمیلی که برگشت خورده اکنون کار میکند،
remove_suppressionرا فراخوانی کنید. موارد توقف ارسال ناشی از گزارش اسپم دائمیاند (409 complaint_suppression_locked).
4. دریافت ایمیل ورودی
- دامنه (اغلب یک زیردامنه مانند
inbound.example.com) باید تأیید شده باشد. setup_inboundدریافت را راهاندازی میکند و یک رکورد MX برمیگرداند. یک انسان آن را منتشر میکند.verify_inboundرا تا زمانی کهstatusبرابرreadyشود فراخوانی کنید.create_inboxباdomain_idوlocal_part(برای مثالsupport) نشانیsupport@inbound.example.comرا میسازد.list_emailsرا باdirection: "in"وunread: true(و بهصورت اختیاریinbox_id) بهطور دورهای فراخوانی کنید. پیام را باget_email، مکالمه آن را باget_threadو پیوستها را باdownload_attachmentبخوانید و باmark_email(read: true) آن را رسیدگیشده علامت بزنید.- با
send_emailوreply_to_email_idدر همان رشته گفتگو پاسخ دهید؛ SendHQ هدرهای In-Reply-To و References و رشته گفتگو را تنظیم میکند.
5. وبهوکها و اعلان رویدادها
Webhooks push signed email events (email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.failed, email.received) to an endpoint a human configures in the dashboard or with the REST API (see /docs/webhooks). 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. عیبیابی شکست تحویل
- پیام را پیدا کنید:
list_emailsباdirection: "out"وtoیاquery، یاget_emailاگر شناسه را دارید.status: failedیعنی SendHQ یا ارائهدهنده آن را هنگام ارسال رد کرده است؛ خطای ثبتشده در ایمیل دلیل آن را توضیح میدهد. list_email_events:bounce(دائمی یا گذرا، همراه با پیام تشخیصی ارائهدهنده)،complaint،rejectیاdelivery. نبود رویداد یعنی ارائهدهنده هنوز گزارشی نداده است؛ صبر کنید و دوباره بررسی کنید.- If the send call itself failed, read the error
code:subscription_required→ the owner activates a plan;sender_domain_unverified→ finish domain verification;recipient_suppressed→ the address hard-bounced or complained before;sender_paused→ inspectlist_sender_reputation;account_paused→ the workspace is paused for review, read the rates;daily_limit_reached→ wait until midnight UTC;quota_exhausted→get_accountusage. get_domainبررسی میکند که DKIM، SPF و DMARC همچنان منتشر شده باشند؛deliverability_statsنشان میدهد مشکل مربوط به یک پیام است یا یک روند.- آنچه را شواهد نشان میدهند گزارش کنید. رویداد
deliveryیعنی سرور گیرنده پیام را پذیرفته است، نه اینکه به صندوق ورودی رسیده یا خوانده شده است.
7. مالکیت یک bucket کاری (برچسبها)
create_labelرا باname(برای مثالAgent/Orders) وskip_inbox: trueفراخوانی کنید. این کار برچسب را به یک bucket تبدیل میکند: ایمیل دریافتیای که این برچسب را بگیرد بایگانی میشود، پس فقط در آن برچسب نمایش داده میشود و هرگز در صندوق ورودی انسان نمیآید.- ایمیلهای کاری را با
send_email(یاsend_batch) وlabels: ["Agent/Orders"]ارسال کنید. پاسخها به آن مکالمه بهطور خودکار برچسب را به ارث میبرند و از صندوق ورودی عبور نمیکنند. - برای ایمیلهایی که خارج از مکالمههای شما آغاز میشوند، یک قانون بایگانی اضافه کنید:
create_label_ruleباinbox_id(یک نشانی اختصاصی مانندorders@…)،from،toیاsubject. برای بایگانی ایمیلهایی که قبلاً دریافت شدهاند،apply_to_existing: trueرا ارسال کنید. - کار با bucket:
list_emailsباlabel: "Agent/Orders"،direction: "in"وunread: true؛ باget_emailیاget_threadبخوانید، باsend_emailوreply_to_email_idپاسخ دهید و پس از رسیدگیmark_emailرا باread: trueفراخوانی کنید. - یک پیام سرگردان را با
label_email(add/remove) وارد یا خارج کنید. افزودن برچسب bucket به یک پیام دریافتی، آن را بایگانی هم میکند. - بهصورت اختیاری،
set_inbox_forwardingیک نسخه از هر چیزی را که یک نشانی دریافت میکند به صندوق ایمیل دیگری میفرستد (مقصد ابتدا از طریق ایمیل تأیید میکند).
{
"name": "send_email",
"arguments": {
"from": "Orders <orders@example.com>",
"to": [
"customer@example.net"
],
"subject": "Order 1042: confirm delivery window",
"text": "Reply with a time that works.",
"labels": [
"Agent/Orders"
],
"idempotency_key": "order-1042-window"
}
}8. پیوستها و قالبها
در یک پلن پولی، حداکثر 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
- Audience:
list_lists(orcreate_listwith a signup form), and optionallypreview_segmentthencreate_segmentto narrow it, for example to contacts taggedVIPwho opened in the last 90 days. Add only people who asked for your email: every subscribed contact needs aconsent_basis. get_newsletter_settings: ifpostalAddressis empty, ask the user for one and set it withupdate_newsletter_settings(marketing email needs it).create_broadcastwithlist_id, a verifiedfrom,subject,preview_text, content (markdownis simplest), and optionallyaudience(segment_id,limit,order: engaged).check_broadcast: fix everyblockitem and tell the user aboutwarnitems. Thensend_broadcast_testto the user's own address so they can look at it.- Only when the user says to send:
send_broadcastnow (with anidempotency_key), orschedule_broadcastwithscheduled_at(unschedule_broadcastto change it). - Follow up with
get_broadcast(delivery totals),get_broadcast_report(opens, clicks, links, inbox providers, against your average), andlist_broadcast_recipientswithactivity. Report opens as estimates. With a limited audience,send_broadcast_to_moresends to the next people.
{
"name": "create_broadcast",
"arguments": {
"list_id": "lst_…",
"from": "Acme <news@example.com>",
"subject": "What shipped in October",
"preview_text": "Three new features",
"markdown": "Hi {{first_name | there}},\n\nHere is what shipped this month.",
"audience": {
"segment_id": "seg_…"
}
}
}نتایج، صفحهبندی و خطاها
فراخوانی موفق، شیء 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.
{
"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_requireduntil a paid plan is active. There is no free or trial allowance. - Workspace daily ladder on paid plans: 1,000 recipients on day one, then 2,000, 3,000, 5,000, 8,000, 12,000, 18,000, 25,000, 35,000, 45,000, and 50,000. A step is gained after a UTC day that used at least half the cap with healthy 7-day feedback. A high rate demotes once per incident, not every day the rate stays high. See
get_account→sendingLimit. Over the cap:daily_limit_reached, not queued, retry afterresets_at(midnight UTC), not on a short backoff. - Hourly pace: about one tenth of the day's cap each UTC hour (100 on day one).
hourly_limit_reachedwaits until the next UTC hour. - New domains: a sending domain less than 30 days old may send at most 500 Gmail recipients a day (
gmail_recipient_limit), on any ladder rung.gmail_rate_limitedmeans Gmail returned 4.7.28; wait untilresets_atand keep sending to other providers. - پیوستها: حداکثر 10 فایل و 10 MB برای هر پیام؛ در پلنهای پولی 10 GB انتقال پیوست وزندهیشده بر اساس گیرنده در ماه.
- برای هر درخواست: To + Cc + Bcc حداکثر 100 نشانی؛
send_batchحداکثر 100 پیام. - قطعکننده مدار اعتبار: در یک بازه متحرک 7 روزه، برگشتها یا گزارشهای اسپم بیش از آستانه، یک نشانی From را محدود یا متوقف میکنند (
423 sender_paused). پس از کاهش نرخها، بهطور خودکار بازیابی میشود.
quota_exhausted تا زمان بازنشانی دوره یا تغییر پلن قابل تلاش مجدد نیست. rate_limited پس از retry_after_seconds قابل تلاش مجدد است؛ برای ارسالها با همان idempotency_key و بدنه یکسان دوباره تلاش کنید.
فهرست خطاها
code پایدار است؛ منطق برنامه را بر اساس آن بنویسید، نه بر اساس message.
| code | HTTP | تلاش مجدد؟ | معنا و اقدام لازم |
|---|---|---|---|
invalid_arguments | — | خیر | آرگومانها بهصورت محلی از JSON Schema ابزار عبور نکردند؛ چیزی به SendHQ نرسید. فیلدهای فهرستشده در problems را اصلاح کنید. |
auth_error | 401 | خیر | کلید API وجود ندارد، باطل شده یا اشتباه است. SENDHQ_API_KEY را برای پردازه سرور تنظیم کنید؛ کلیدها را یک انسان در داشبورد میسازد. |
subscription_required | 402 | خیر | No active subscription. Nothing is sent, including to the account owner. The owner chooses a plan. Do not retry until then. |
payment_required | 402 | خیر | این قابلیت به پلن پولی نیاز دارد (برای مثال پیوستها). بدون آن ارسال کنید یا پلن را ارتقا دهید. |
sender_domain_not_owned | 403 | خیر | دامنه From در این فضای کاری نیست. از list_sending_identities یا add_domain استفاده کنید. |
sender_domain_unverified | 403 | خیر | دامنه From هنوز تأیید نشده است. get_domain، انتشار رکوردهای جاافتاده، verify_domain. |
domain_limit_reached | 403 | خیر | به سقف تعداد دامنه پلن رسیدهاید. یک دامنه بلااستفاده را (با تأیید) حذف کنید یا پلن را ارتقا دهید. |
marketing_not_enabled | 403 | خیر | کلاس marketing برای این دامنه یا پلن فعال نیست. فقط در صورتی از transactional استفاده کنید که پیام واقعاً تراکنشی باشد. |
forbidden | 403 | خیر | سیاستها اجازه این عملیات را نمیدهند. درخواست را اصلاح کنید. |
not_found | 404 | خیر | این شناسه در این فضای کاری نیست. منبع را فهرست کنید تا شناسه درست را پیدا کنید؛ قالبهای بایگانیشده را ابتدا بازیابی کنید. |
idempotency_conflict | 409 | خیر | کلید با بدنه متفاوتی دوباره استفاده شده است. دقیقاً درخواست اصلی را دوباره ارسال کنید یا برای پیام جدید از کلید جدید استفاده کنید. |
idempotency_in_progress | 409 | بله | درخواست اصلی هنوز در حال اجراست. صبر کنید، سپس با همان کلید و بدنه دوباره تلاش کنید. |
revision_conflict | 409 | خیر | پیشنویس قالب از زمانی که آن را خواندید تغییر کرده است. get_template، ادغام، ذخیره دوباره. |
complaint_suppression_locked | 409 | خیر | گیرنده گزارش اسپم داده است. هرگز دوباره به او ایمیل نزنید. |
inbound_not_ready | 409 | خیر | دریافت ایمیل ورودی آماده نیست. setup_inbound، انتشار MX، verify_inbound. |
conflict | 409 | خیر | منبع از قبل وجود دارد یا در وضعیت نادرستی است. آن را بخوانید و اصلاح کنید. |
attachments_too_large | 413 | خیر | بیش از 10 فایل یا 10 MB. پیوستها را حذف یا کوچک کنید. |
recipient_suppressed | 422 | خیر | یک گیرنده پیشتر برگشت دائمی خورده یا گزارش اسپم داده است. او را حذف کنید؛ list_blocked_recipients را ببینید. |
recipient_unsubscribed | 422 | خیر | یک گیرنده اشتراک ایمیلهای بازاریابی را لغو کرده است. او را برای همیشه حذف کنید. |
validation_failed | 422 | خیر | محتوا رد شد، برای مثال داده قالبی که قرارداد متغیرها را نقض میکند. ورودی را اصلاح کنید. |
sender_paused | 423 | خیر | این نشانی From توسط قطعکننده مدار 7 روزه برگشت/گزارش اسپم متوقف شده است. ارسال را متوقف کنید، فهرست را اصلاح کنید و منتظر بازیابی خودکار بمانید. |
account_paused | 423 | خیر | Workspace paused for a deliverability review. The body has the measured rate and the limit when the pause was for bounces or complaints. Do not send until it is restored. |
quota_exhausted | 429 | خیر | Monthly allowance, per-sender daily limit, or attachment transfer. Not the workspace daily ladder. Check get_account; wait for that limit to reset or upgrade. |
daily_limit_reached | 429 | after reset | Workspace daily ladder. Not a short backoff. Wait until resets_at (midnight UTC). The message was not queued. |
hourly_limit_reached | 429 | after reset | Hourly pace (about a tenth of the day's cap). Wait until the next UTC hour. Not a short backoff. |
gmail_recipient_limit | 429 | after reset | 500 Gmail recipients a day for a sending domain under 30 days old, on any ladder rung. Wait until midnight UTC. Not queued. |
gmail_rate_limited | 429 | after reset | Gmail returned 4.7.28 for this domain. Wait until resets_at. Other providers keep sending. |
rate_limited | 429 | بله | Slow down; wait retry_after_seconds. This is not a daily, hourly, or Gmail cap. |
server_error | 5xx | بله | خطای موقت SendHQ یا ارائهدهنده. با backoff دوباره تلاش کنید؛ ارسالها با همان کلید و بدنه. اگر idempotent_replayed برابر true است، پس از اطمینان از اینکه چیزی ارسال نشده، از کلید جدید استفاده کنید. |
network_error | — | بله | درخواست یا پاسخ از دست رفت. دوباره تلاش کنید؛ برای ارسالها، همان idempotency_key این کار را امن میکند. |
invalid_request | 400 | خیر | درخواست نادرست است. 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, list_sender_reputation, list_suppressions, remove_suppression, list_blocked_recipients
Campaigns: list_contacts, create_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
Account, usage, analytics, and keys: get_account, get_account_diagnostics, get_analytics, list_api_keys, get_service_health
هیچ ابزاری با این فیلتر مطابقت ندارد.
ایمیلها و رشتههای گفتگو
send_emailارسال یک ایمیل
SENDS REAL EMAIL. Send one message from a verified domain: raw html/text, a published hosted template, a reply in an existing thread, or a message with attachments. Pass idempotency_key so a retry cannot send twice; a retry must reuse the same key AND an identical request, otherwise SendHQ returns 409. attachments is a convenience that creates a draft, uploads each file, and sends with that draft; it cannot be combined with idempotency_key or draft_id (use create_draft + upload_attachment + send_email with draft_id for retry-safe attachment sends). Unpaid workspaces (integration trial) can deliver only to the account email or a mailbox-simulator test address, and cannot send attachments.
دستکم یکی از این موارد را ارائه دهید: html، text، template.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
from | string | بله | فرستنده، مثلاً Acme <hello@example.com>. دامنه باید در این فضای کاری تأیید شده باشد (list_sending_identities را ببینید). (حداکثر 998 کاراکتر) |
to | string[] | بله | گیرندگان. هر مورد یک نشانی است، بهصورت اختیاری همراه با نام نمایشی. مجموع to+cc+bcc حداکثر 100 است؛ هر مقصد یک اعتبار تحویل مصرف میکند. (1 تا 100 مورد) |
cc | string[] | خیر | گیرندگان رونوشت (Cc). (0 تا 100 مورد) |
bcc | string[] | خیر | گیرندگان رونوشت مخفی (Bcc). (0 تا 100 مورد) |
subject | string | خیر | موضوع ایمیل. هنگام ارسال با قالب آن را حذف کنید. (حداکثر 998 کاراکتر) |
text | string | خیر | متن ساده. text، html یا template را ارائه دهید. |
html | string | خیر | بدنه HTML. SendHQ آن را پاکسازی میکند و وقتی text حذف شده باشد، متن را از آن استخراج میکند. |
reply_to | string | خیر | نشانی Reply-To. |
headers | object | خیر | هدرهای سفارشی امن اضافی (با مقادیر رشتهای)، مثلاً {"X-Entity-Ref-ID": "123"}. هدرهای مسیریابی مانند From/To/Message-ID را SendHQ کنترل میکند. |
message_class | string | خیر | transactional (پیشفرض) یا marketing. marketing به پلن یا دامنهای با قابلیت بازاریابی نیاز دارد و مدیریت لغو اشتراک را اضافه میکند. (یکی از transactional، marketing) |
reply_to_email_id | string | خیر | پاسخ درون یک مکالمه موجود: شناسه em_… پیامی که به آن پاسخ داده میشود. SendHQ هدرهای In-Reply-To/References و رشته گفتگو را تنظیم میکند. |
thread_id | string | خیر | شناسه صریح رشته گفتگویی که پیام باید زیر آن ثبت شود. |
draft_id | string | خیر | پیوستهای یک پیشنویس ذخیرهشده (dr_…) را همراه این پیام ارسال کنید. پیشنویس پس از ارسال موفق حذف میشود. |
template | object | خیر | بهجای html/text خام، یک قالب میزبانیشده منتشرشده ارسال کنید. دقیقاً به یک گیرنده to و بدون cc/bcc نیاز دارد؛ موضوع را قالب تعیین میکند. دستکم یکی از این موارد را ارائه دهید: id، key. |
template.id | string | خیر | شناسه قالب (tmpl_…). id یا key را ارائه دهید. |
template.key | string | خیر | کلید قالب مانند account-welcome. id یا key را ارائه دهید. |
template.version_id | string | خیر | شناسه اختیاری نسخه منتشرشده (tmplv_…). پیشفرض، نسخه منتشرشده فعلی است. |
template.data | object | خیر | مقادیر متغیرهای نوعدار قالب. |
labels | string[] | خیر | نام برچسبها یا شناسههای lbl_… که این پیام باید زیر آنها بایگانی شود. نامهای ناشناخته ایجاد میشوند. پاسخهای درون مکالمه برچسبها را به ارث میبرند و برچسب bucket (skip_inbox) این پاسخها را از صندوق ورودی دور نگه میدارد. حداکثر 10. (0 تا 10 مورد) |
idempotency_key | string | خیر | هدر Idempotency-Key (حداکثر 200 کاراکتر). فقط برای تلاش مجدد همین درخواست دقیق دوباره از آن استفاده کنید. (حداکثر 200 کاراکتر) |
attachments | object[] | خیر | فایلهایی که باید پیوست شوند (حداکثر 10 فایل، مجموعاً 10 MB). هر کدام به content_base64 (همراه با filename) یا یک file_path محلی نیاز دارد. (0 تا 10 مورد) دستکم یکی از این موارد را ارائه دهید: content_base64، file_path. |
attachments[].filename | string | خیر | نام فایلی که به گیرنده نمایش داده میشود. همراه با content_base64 الزامی است؛ پیشفرض آن نام پایه file_path است. (حداکثر 255 کاراکتر) |
attachments[].content_type | string | خیر | نوع MIME، مثلاً application/pdf. پیشفرض application/octet-stream است. |
attachments[].content_base64 | string | خیر | محتوای فایل با base64 استاندارد. |
attachments[].file_path | string | خیر | مسیر مطلق یک فایل محلی که پردازه سرور MCP بتواند آن را بخواند. |
{
"name": "send_email",
"arguments": {
"from": "Acme <hello@example.com>",
"to": [
"owner@example.com"
],
"subject": "Your export is ready",
"text": "Download it from your dashboard.",
"idempotency_key": "export-ready-42"
}
}send_batchارسال دستهای ایمیلهای شخصیسازیشده
SENDS REAL EMAIL (ایمیل واقعی ارسال میکند). 1 تا 100 پیام مستقل را در یک درخواست ارسال کنید (برای شخصیسازی قالب بهازای هر گیرنده از این استفاده کنید). هر مورد همان ساختار send_email را دارد (بدون attachments/idempotency_key). موارد بهصورت جداگانه موفق یا ناموفق میشوند: HTTP 207 یعنی موفقیت جزئی؛ هر data[i].ok و data[i].error را بررسی کنید. یک idempotency_key کل بدنه دسته را پوشش میدهد.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
emails | object[] | بله | پیامهایی که باید ارسال شوند. (1 تا 100 مورد) دستکم یکی از این موارد را ارائه دهید: html، text، template. |
idempotency_key | string | خیر | Idempotency-Key برای کل دسته (حداکثر 200 کاراکتر). (حداکثر 200 کاراکتر) |
{
"name": "send_batch",
"arguments": {
"emails": [
{
"from": "Acme <hello@example.com>",
"to": [
"owner@example.com"
],
"template": {
"key": "account-welcome",
"data": {
"first_name": "Asha"
}
}
}
],
"idempotency_key": "welcome-batch-2026-09-26"
}
}list_emailsفهرست و جستجوی ایمیلها
ایمیلهای ارسالی (direction: out) و دریافتی (direction: in) را از جدیدترین به قدیمیترین همراه با فیلترها فهرست کنید. ایمیلهای دریافتی دستهبندی میشوند: صندوق ورودی انسان را با direction: in، archived: false، category: primary بخوانید؛ با important: true اولویتبندی کنید؛ اسپم پنهان است مگر با category: spam یا include_spam: true. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
direction | string | خیر | in برای دریافتی، out برای ارسالی. (یکی از in، out) |
status | string | خیر | فیلتر وضعیت، مثلاً queued، sent، delivered، bounced، complained، failed. |
domain | string | خیر | فقط پیامهای این دامنه، یا فهرستی از دامنهها که با کاما جدا شدهاند (تطابق با هر کدام). |
inbox_id | string | خیر | فقط پیامهایی که این صندوق ورودی (inb_…) دریافت کرده است. |
label | string | خیر | فقط پیامهایی که این برچسب را دارند: شناسه برچسب lbl_… یا نام دقیق آن، یا فهرستی جداشده با کاما (تطابق با هر کدام). برای دیدن پوشهها از list_labels استفاده کنید. |
archived | boolean | خیر | false = نمای صندوق ورودی (ایمیلهای دریافتی بایگانینشده)، true = فقط بایگانیشدهها. برای همه ایمیلها آن را حذف کنید. |
category | string | خیر | primary (افراد)، updates (خبرنامهها، انبوه، خودکار) یا spam؛ یا فهرستی جداشده با کاما. اسپم پنهان است مگر اینکه درخواست شود. |
important | boolean | خیر | true = فقط پیامهایی که مهم علامت خوردهاند (پاسخ به مکالمههایی که شما آغاز کردهاید و فرستندگانی که مهم علامت خوردهاند). |
include_spam | boolean | خیر | اسپم را در نتایج بگنجانید (برای جستجو در همه پوشهها). |
from | string | خیر | نشانی فرستنده شامل این مقدار باشد. |
to | string | خیر | نشانی گیرنده شامل این مقدار باشد. |
unread | boolean | خیر | true = فقط خواندهنشدهها، false = فقط خواندهشدهها. |
after | string | خیر | مهر زمانی ISO-8601؛ فقط پیامهایی که پس از آن ایجاد شدهاند. (date-time) |
before | string | خیر | مهر زمانی ISO-8601؛ فقط پیامهایی که پیش از آن ایجاد شدهاند. (date-time) |
query | string | خیر | جستجوی متن آزاد در موضوعها، متن ایمیلها، نشانیهای فرستنده/گیرنده و نام فایل پیوستها. (حداکثر 200 کاراکتر) |
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_emails",
"arguments": {
"direction": "in",
"unread": true,
"limit": 25
}
}get_emailدریافت یک ایمیل
یک پیام را همراه با هدرها، بدنه html/text، وضعیت، فراداده رشته گفتگو و فراداده پیوستها دریافت کنید (بایتهای پیوست را با download_attachment دانلود کنید).
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
email_id | string | بله | شناسه ایمیل (با em_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "get_email",
"arguments": {
"email_id": "em_123"
}
}mark_emailعلامتگذاری بهعنوان خواندهشده، بایگانیشده، اسپم یا مهم
یک پیام را بهروز کنید: read، archived، category (primary، updates، spam؛ فقط ایمیلهای دریافتی) و important. گزارش اسپم یا علامتگذاری بهعنوان مهم، به SendHQ درباره آن فرستنده برای ایمیلهای آینده آموزش میدهد؛ برای تغییر فقط همین پیام learn: false را ارسال کنید. دستکم یک فیلد ارسال کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
email_id | string | بله | شناسه ایمیل (با em_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
read | boolean | خیر | true = خواندهشده، false = خواندهنشده. |
archived | boolean | خیر | true = بایگانی (خارج از صندوق ورودی)، false = بازگرداندن به صندوق ورودی. |
category | string | خیر | یک پیام دریافتی را به primary، updates یا spam منتقل کنید. (یکی از primary، updates، spam) |
important | boolean | خیر | علامت مهم را روی پیام بگذارید یا بردارید. |
learn | boolean | خیر | false = این تصمیم برای فرستنده به خاطر سپرده نشود (پیشفرض true). |
{
"name": "mark_email",
"arguments": {
"email_id": "em_123",
"read": true
}
}delete_emailحذف یک ایمیل
DESTRUCTIVE (مخرب): یک پیام نگهداریشده و پیوستهای ذخیرهشده آن را برای همیشه از SendHQ حذف میکند. پیامی را که قبلاً تحویل شده بازنمیگرداند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
email_id | string | بله | شناسه ایمیل (با em_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "delete_email",
"arguments": {
"email_id": "em_123"
}
}list_email_eventsفهرست رویدادهای تحویل یک ایمیل
رویدادهای ارائهدهنده برای یک پیام ارسالی: delivery، bounce، complaint، reject، open، click. اینها شواهدی هستند که نشان میدهند پیام تحویل شده یا چرا شکست خورده است. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
email_id | string | بله | شناسه ایمیل (با em_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_email_events",
"arguments": {
"email_id": "em_123"
}
}get_threadدریافت یک مکالمه
همه پیامهای یک مکالمه (ارسالی و دریافتی) را به ترتیب زمانی، هر کدام همراه با فراداده پیوستها، دریافت کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
thread_id | string | بله | شناسه رشته گفتگو (معمولاً شناسه em_… نخستین پیام؛ threadId هر ایمیل را ببینید). (حداکثر 128 کاراکتر) |
{
"name": "get_thread",
"arguments": {
"thread_id": "em_123"
}
}email_deliveryGet an email delivery timeline
Queued, sent, delivered, delayed, bounced, complained, and failed events for one email, with bounce type and the SMTP diagnostic. Reasons are plain text.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
email_id | string | بله | |
limit | integer | خیر | |
offset | integer | خیر |
{
"name": "email_delivery",
"arguments": {
"email_id": "em_123"
}
}thread_deliveryGet a thread delivery summary
Counts of delivered, bounced, complained, and failed outbound messages in one conversation, plus each message's failure reason.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
thread_id | string | بله |
{
"name": "thread_delivery",
"arguments": {
"thread_id": "thr_123"
}
}برچسبها و قوانین بایگانی خودکار
list_labelsفهرست برچسبها
برچسبهای (پوشههای) فضای کاری را همراه با تعداد کل و خواندهنشدهها و قوانین بایگانی خودکارشان فهرست کنید. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_labels",
"arguments": {}
}get_labelدریافت یک برچسب
یک برچسب را همراه با شمارشها و قوانین بایگانی خودکار دریافت کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
label_id | string | بله | شناسه برچسب (با lbl_ شروع میشود) یا نام دقیق برچسب. (حداکثر 128 کاراکتر) |
{
"name": "get_label",
"arguments": {
"label_id": "Billing"
}
}create_labelساخت برچسب
یک برچسب از نوع پوشه بسازید. skip_inbox: true را تنظیم کنید تا به bucketی تبدیل شود که ایجنت مالک آن است: با labels: [name] ارسال کنید تا پاسخها در آن برچسب بایگانی شوند و از صندوق ورودی دور بمانند. قوانین اختیاری بایگانی خودکار، ایمیلهای ارسالی/دریافتی جدید را بایگانی میکنند (همه شرطهای یک قانون باید برقرار باشند). برای بایگانی ایمیلهای نگهداریشده نیز apply_to_existing را تنظیم کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
name | string | بله | نام برچسب، مثلاً Billing یا Clients/Acme. در هر فضای کاری یکتاست (بدون حساسیت به حروف بزرگ و کوچک). (حداکثر 64 کاراکتر) |
color | string | خیر | رنگ hex مانند #1a73e8. اختیاری. |
skip_inbox | boolean | خیر | حالت bucket: ایمیل دریافتیای که این برچسب را میگیرد (از طریق قانون، پاسخ به مکالمهای که با این برچسب ارسال شده، یا بهصورت دستی) بایگانی میشود تا فقط در برچسب نمایش داده شود، نه در صندوق ورودی. |
rules | object[] | خیر | قوانین اختیاری بایگانی خودکار (حداکثر 20). هر کدام دستکم به یکی از inbox_id، from، to، subject نیاز دارد. (0 تا 20 مورد) |
rules[].direction | string | خیر | فقط ایمیلهای in (دریافتی) یا out (ارسالی). برای هر دو آن را حذف کنید. (یکی از in، out) |
rules[].inbox_id | string | خیر | فقط ایمیلهایی که این صندوق ورودی (inb_…) دریافت کرده است. هر نشانی دریافت را در پوشه مخصوص خودش بایگانی میکند. |
rules[].from | string | خیر | فرستنده شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک)، مثلاً @stripe.com. (حداکثر 200 کاراکتر) |
rules[].to | string | خیر | To/Cc شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک). (حداکثر 200 کاراکتر) |
rules[].subject | string | خیر | موضوع شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک). (حداکثر 200 کاراکتر) |
rules[].skip_inbox | boolean | خیر | ایمیلهای دریافتی منطبق را بایگانی کنید تا فقط در پوشه برچسب نمایش داده شوند، نه در صندوق ورودی. |
apply_to_existing | boolean | خیر | ایمیلهای نگهداریشدهای را که با قوانین مطابقت دارند نیز بایگانی کنید. |
{
"name": "create_label",
"arguments": {
"name": "Agent/Orders",
"skip_inbox": true,
"rules": [
{
"from": "@stripe.com"
}
]
}
}update_labelتغییر نام، تغییر رنگ یا تبدیل برچسب به bucket
نام برچسب را تغییر دهید، رنگش را عوض کنید یا حالت bucket (skip_inbox) را روشن/خاموش کنید. روشن کردن حالت bucket ایمیلهای دریافتی موجود در برچسب را بایگانی میکند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
label_id | string | بله | شناسه برچسب (با lbl_ شروع میشود) یا نام دقیق برچسب. (حداکثر 128 کاراکتر) |
name | string | خیر | نام جدید. (حداکثر 64 کاراکتر) |
color | string | خیر | رنگ hex جدید. |
skip_inbox | boolean | خیر | حالت bucket: ایمیل دریافتیای که این برچسب را میگیرد (از طریق قانون، پاسخ به مکالمهای که با این برچسب ارسال شده، یا بهصورت دستی) بایگانی میشود تا فقط در برچسب نمایش داده شود، نه در صندوق ورودی. |
{
"name": "update_label",
"arguments": {
"label_id": "lbl_123",
"name": "Finance/Billing"
}
}delete_labelحذف برچسب
DESTRUCTIVE (مخرب): یک برچسب و قوانینش را حذف میکند. خود ایمیلها حفظ میشوند؛ فقط این برچسب را از دست میدهند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
label_id | string | بله | شناسه برچسب (با lbl_ شروع میشود) یا نام دقیق برچسب. (حداکثر 128 کاراکتر) |
{
"name": "delete_label",
"arguments": {
"label_id": "lbl_123"
}
}create_label_ruleافزودن قانون بایگانی خودکار
یک قانون به برچسب اضافه کنید تا ایمیلهای جدید منطبق بهطور خودکار بایگانی شوند. همه شرطهایی که تنظیم میکنید باید برقرار باشند. از inbox_id استفاده کنید تا یک نشانی دریافت، پوشه مخصوص خودش را داشته باشد؛ skip_inbox را اضافه کنید تا از صندوق ورودی دور بماند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
label_id | string | بله | شناسه برچسب (با lbl_ شروع میشود) یا نام دقیق برچسب. (حداکثر 128 کاراکتر) |
direction | string | خیر | فقط ایمیلهای in (دریافتی) یا out (ارسالی). برای هر دو آن را حذف کنید. (یکی از in، out) |
inbox_id | string | خیر | فقط ایمیلهایی که این صندوق ورودی (inb_…) دریافت کرده است. هر نشانی دریافت را در پوشه مخصوص خودش بایگانی میکند. |
from | string | خیر | فرستنده شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک)، مثلاً @stripe.com. (حداکثر 200 کاراکتر) |
to | string | خیر | To/Cc شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک). (حداکثر 200 کاراکتر) |
subject | string | خیر | موضوع شامل این متن باشد (بدون حساسیت به حروف بزرگ و کوچک). (حداکثر 200 کاراکتر) |
skip_inbox | boolean | خیر | ایمیلهای دریافتی منطبق را بایگانی کنید تا فقط در پوشه برچسب نمایش داده شوند، نه در صندوق ورودی. |
apply_to_existing | boolean | خیر | ایمیلهای نگهداریشده منطبق را نیز بایگانی کنید. |
{
"name": "create_label_rule",
"arguments": {
"label_id": "Billing",
"inbox_id": "inb_123",
"skip_inbox": true
}
}delete_label_ruleحذف یک قانون بایگانی خودکار
DESTRUCTIVE (مخرب): یک قانون بایگانی خودکار را حذف میکند. ایمیلهایی که قبلاً بایگانی شدهاند برچسب خود را حفظ میکنند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
label_id | string | بله | شناسه برچسب (با lbl_ شروع میشود) یا نام دقیق برچسب. (حداکثر 128 کاراکتر) |
rule_id | string | بله | شناسه قانون (با lrule_ شروع میشود)، از get_label. (حداکثر 128 کاراکتر) |
{
"name": "delete_label_rule",
"arguments": {
"label_id": "lbl_123",
"rule_id": "lrule_123"
}
}label_emailافزودن یا حذف برچسبهای یک ایمیل
یک پیام را بین پوشهها جابهجا کنید: برچسبها را با نام یا شناسه lbl_… اضافه و/یا حذف کنید. نامهای ناشناخته در add ایجاد میشوند، مگر اینکه create برابر false باشد.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
email_id | string | بله | شناسه ایمیل (با em_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
add | string[] | خیر | برچسبهایی که باید اضافه شوند. (0 تا 10 مورد) |
remove | string[] | خیر | برچسبهایی که باید حذف شوند. (0 تا 10 مورد) |
create | boolean | خیر | ایجاد برچسبهای ناشناخته در add (پیشفرض true). |
{
"name": "label_email",
"arguments": {
"email_id": "em_123",
"add": [
"Billing"
],
"remove": [
"Support"
]
}
}پیشنویسها، پیوستها و هویتهای فرستنده
list_sending_identitiesفهرست هویتهای فرستنده تأییدشده
نشانیها و دامنههایی که این فضای کاری همین حالا میتواند از آنها ارسال کند (دامنههای تأییدشده، From پیشفرض آنها و نشانیهای صندوق ورودی فعال). پیش از send_email آن را فراخوانی کنید تا یک from معتبر انتخاب کنید.
بدون پارامتر.
{
"name": "list_sending_identities",
"arguments": {}
}create_draftساخت پیشنویس
یک پیشنویس در ویرایشگر ایمیل بسازید. پیشنویسها پیوستها را نگه میدارند: یک پیشنویس بسازید، upload_attachment را اجرا کنید، سپس send_email را با draft_id فراخوانی کنید. چیزی ارسال نمیکند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
from | string | خیر | نشانی فرستنده روی یک دامنه تأییدشده (در حین پیشنویس میتواند خالی باشد). |
to | string[] | خیر | گیرندگان. (0 تا 100 مورد) |
cc | string[] | خیر | گیرندگان رونوشت (Cc). (0 تا 100 مورد) |
bcc | string[] | خیر | گیرندگان رونوشت مخفی (Bcc). (0 تا 100 مورد) |
subject | string | خیر | موضوع ایمیل. (حداکثر 998 کاراکتر) |
html | string | خیر | بدنه HTML. |
text | string | خیر | متن ساده. |
reply_to_email_id | string | خیر | شناسه ایمیلی که این پیشنویس به آن پاسخ میدهد. |
thread_id | string | خیر | شناسه رشته گفتگویی که این پیشنویس به آن تعلق دارد. |
{
"name": "create_draft",
"arguments": {
"from": "hello@example.com",
"to": [
"owner@example.com"
],
"subject": "Invoice"
}
}list_draftsفهرست پیشنویسها
پیشنویسهای ویرایشگر را به ترتیب آخرین بهروزرسانی فهرست کنید. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_drafts",
"arguments": {}
}get_draftدریافت یک پیشنویس
یک پیشنویس را همراه با فراداده پیوستهایش دریافت کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
draft_id | string | بله | شناسه پیشنویس (با dr_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "get_draft",
"arguments": {
"draft_id": "dr_123"
}
}update_draftجایگزینی محتوای پیشنویس
محتوا و گیرندگان یک پیشنویس را جایگزین کنید. این یک جایگزینی کامل است: فیلدهایی که حذف کنید پاک میشوند، پس ابتدا get_draft را بخوانید و همه فیلدهایی را که میخواهید حفظ شوند ارسال کنید. پیوستها تحت تأثیر قرار نمیگیرند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
draft_id | string | بله | شناسه پیشنویس (با dr_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
from | string | خیر | نشانی فرستنده روی یک دامنه تأییدشده (در حین پیشنویس میتواند خالی باشد). |
to | string[] | خیر | گیرندگان. (0 تا 100 مورد) |
cc | string[] | خیر | گیرندگان رونوشت (Cc). (0 تا 100 مورد) |
bcc | string[] | خیر | گیرندگان رونوشت مخفی (Bcc). (0 تا 100 مورد) |
subject | string | خیر | موضوع ایمیل. (حداکثر 998 کاراکتر) |
html | string | خیر | بدنه HTML. |
text | string | خیر | متن ساده. |
reply_to_email_id | string | خیر | شناسه ایمیلی که این پیشنویس به آن پاسخ میدهد. |
thread_id | string | خیر | شناسه رشته گفتگویی که این پیشنویس به آن تعلق دارد. |
{
"name": "update_draft",
"arguments": {
"draft_id": "dr_123",
"from": "hello@example.com",
"to": [
"owner@example.com"
],
"subject": "Invoice (updated)",
"text": "Attached."
}
}delete_draftدور ریختن پیشنویس
DESTRUCTIVE (مخرب): یک پیشنویس را دور میریزد و پیوستهای ذخیرهشده آن را برای همیشه حذف میکند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
draft_id | string | بله | شناسه پیشنویس (با dr_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "delete_draft",
"arguments": {
"draft_id": "dr_123"
}
}upload_attachmentبارگذاری پیوست در یک پیشنویس
یک فایل را در یک پیشنویس بارگذاری کنید (حداکثر 10 فایل و مجموعاً 10 MB برای هر پیام). content_base64 یا یک file_path محلی ارائه دهید. پیوستها هنگام ارسال به پلن پولی نیاز دارند.
دستکم یکی از این موارد را ارائه دهید: content_base64، file_path.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
draft_id | string | بله | شناسه پیشنویس (با dr_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
filename | string | خیر | نام فایلی که به گیرنده نمایش داده میشود. پیشفرض، نام پایه file_path است. (حداکثر 255 کاراکتر) |
content_type | string | خیر | نوع MIME، مثلاً application/pdf. پیشفرض application/octet-stream است. |
content_base64 | string | خیر | محتوای فایل با base64 استاندارد. |
file_path | string | خیر | مسیر مطلق یک فایل محلی که پردازه سرور MCP بتواند آن را بخواند. |
{
"name": "upload_attachment",
"arguments": {
"draft_id": "dr_123",
"filename": "invoice.pdf",
"content_type": "application/pdf",
"file_path": "/tmp/invoice.pdf"
}
}download_attachmentدانلود پیوست
یک پیوست خصوصی (ارسالی، دریافتی یا پیشنویس) را دانلود کنید. محتوای base64 را برمیگرداند، یا وقتی save_to_path تنظیم شده باشد فایل را مینویسد (بازنویسی نمیکند مگر اینکه overwrite برابر true باشد).
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
attachment_id | string | بله | شناسه پیوست (با att_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
save_to_path | string | خیر | مسیر مطلق محلی اختیاری برای نوشتن فایل بهجای برگرداندن base64. |
overwrite | boolean | خیر | اجازه جایگزینی فایل موجود در save_to_path. پیشفرض false. |
{
"name": "download_attachment",
"arguments": {
"attachment_id": "att_123",
"save_to_path": "/tmp/invoice.pdf"
}
}delete_attachmentحذف پیوست
DESTRUCTIVE (مخرب): یک پیوست ذخیرهشده را برای همیشه حذف میکند (برای مثال، حذف یک فایل از پیشنویس پیش از ارسال).
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
attachment_id | string | بله | شناسه پیوست (با att_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "delete_attachment",
"arguments": {
"attachment_id": "att_123"
}
}قالبهای میزبانیشده
list_templatesفهرست قالبهای میزبانیشده
قالبهای ایمیل میزبانیشده را همراه با وضعیت انتشار و میزان استفاده فهرست کنید. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
lifecycle | string | خیر | active (پیشفرض)، archived یا all. (یکی از active، archived، all) |
query | string | خیر | جستجو بر اساس نام یا کلید. (حداکثر 120 کاراکتر) |
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_templates",
"arguments": {
"lifecycle": "active"
}
}create_templateساخت قالب میزبانیشده
یک قالب با پیشنویس قابلویرایش بسازید، بهصورت اختیاری از یک محتوای آغازین (welcome، reset، receipt یا blank). پیش از ارسال با کلید، آن را منتشر کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
name | string | بله | نام قابلفهم برای انسان. (حداکثر 120 کاراکتر) |
key | string | خیر | کلید پایدار ارسال: حروف کوچک، اعداد و خط تیره؛ با یک حرف شروع میشود (2 تا 64 کاراکتر). در صورت حذف، از نام استخراج میشود. |
starter | string | خیر | محتوای آغازین. (یکی از blank، welcome، reset، receipt) |
{
"name": "create_template",
"arguments": {
"name": "Account welcome",
"key": "account-welcome",
"starter": "welcome"
}
}get_templateدریافت یک قالب
پیشنویس فعلی قالب (همراه با revision)، نسخه منتشرشده فعال، تاریخچه نسخهها و میزان استفاده را دریافت کنید. شناسه یا کلید را میپذیرد.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
template_id | string | بله | شناسه قالب (tmpl_…) یا کلید. (حداکثر 128 کاراکتر) |
{
"name": "get_template",
"arguments": {
"template_id": "account-welcome"
}
}update_template_draftذخیره پیشنویس قالب
پیشنویس قابلویرایش قالب را با همزمانی خوشبینانه ذخیره کنید: revision فعلی را از get_template ارسال کنید (409 یعنی شخص دیگری زودتر ذخیره کرده است؛ دوباره بخوانید و تلاش کنید). این یک جایگزینی کامل محتوای پیشنویس است: فیلدهای حذفشده پاک میشوند، پس همه فیلدهایی را که میخواهید حفظ شوند ارسال کنید. از placeholderهای {{variable}} استفاده کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
template_id | string | بله | شناسه یا کلید قالب. (حداکثر 128 کاراکتر) |
revision | integer | بله | revision فعلی پیشنویس از get_template. (1 تا …) |
name | string | خیر | نام قالب. (حداکثر 120 کاراکتر) |
subject_template | string | خیر | موضوع همراه با placeholderها. (حداکثر 998 کاراکتر) |
preheader_template | string | خیر | متن پیشنمایش. (حداکثر 240 کاراکتر) |
html_template | string | خیر | بدنه HTML همراه با placeholderها. |
text_template | string | خیر | متن ساده همراه با placeholderها. |
from | string | خیر | فرستنده پیشفرض برای ارسالهای این قالب. |
reply_to | string | خیر | Reply-To پیشفرض. |
variables | object[] | خیر | قرارداد متغیرهای نوعدار. هر مورد: {key (حروف کوچک/زیرخط), label, type: text|number|url|boolean, required (پیشفرض true), fallback, description}. |
variables[].key | string | بله | |
variables[].label | string | خیر | |
variables[].type | string | خیر | (یکی از text، number، url، boolean) |
variables[].required | boolean | خیر | |
variables[].fallback | any | خیر | |
variables[].description | string | خیر | |
sample_data | object | خیر | مقادیر نمونه برای پیشنمایشها و آزمایشها. |
{
"name": "update_template_draft",
"arguments": {
"template_id": "account-welcome",
"revision": 3,
"name": "Account welcome",
"subject_template": "Welcome, {{first_name}}",
"text_template": "Hi {{first_name}}",
"variables": [
{
"key": "first_name",
"type": "text",
"required": true
}
],
"sample_data": {
"first_name": "Asha"
}
}
}create_template_draftشروع پیشنویس جدید از نسخه منتشرشده
یک پیشنویس قابلویرایش جدید با کپی از نسخه منتشرشده فعلی بسازید (اگر پیشنویسی از قبل وجود داشته باشد یا چیزی منتشر نشده باشد، 409).
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
template_id | string | بله | شناسه یا کلید قالب. (حداکثر 128 کاراکتر) |
{
"name": "create_template_draft",
"arguments": {
"template_id": "account-welcome"
}
}render_templateرندر پیشنمایش قالب
خروجی دقیق سرور (subject، html، text) را برای پیشنویس، نسخه منتشرشده یا یک نسخه مشخص با داده دادهشده رندر کنید. چیزی ارسال نمیکند. وقتی داده قرارداد متغیرها را نقض کند، 422 همراه با findings برمیگرداند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
template_id | string | بله | شناسه یا کلید قالب. (حداکثر 128 کاراکتر) |
version_id | string | خیر | شناسه اختیاری نسخه؛ پیشفرض پیشنویس است و سپس نسخه منتشرشده. |
data | object | خیر | مقادیر متغیرها؛ پیشفرض داده نمونه همان نسخه است. |
{
"name": "render_template",
"arguments": {
"template_id": "account-welcome",
"data": {
"first_name": "Asha"
}
}
}send_template_testارسال ایمیل آزمایشی قالب
SENDS REAL EMAIL. Send a [Test]-prefixed snapshot of the draft (or a given version) to the given recipients. Counts against usage; trial workspaces can only send to the account email or a mailbox-simulator test address.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
template_id | string | بله | شناسه یا کلید قالب. (حداکثر 128 کاراکتر) |
to | string[] | بله | گیرندگان آزمایشی. (1 تا 100 مورد) |
from | string | خیر | فرستنده روی یک دامنه تأییدشده؛ پیشفرض From قالب است. |
version_id | string | خیر | شناسه اختیاری نسخه. |
data | object | خیر | مقادیر متغیرها؛ پیشفرض داده نمونه است. |
{
"name": "send_template_test",
"arguments": {
"template_id": "account-welcome",
"to": [
"owner@example.com"
]
}
}publish_templateانتشار نسخه قالب
پیشنویس فعلی را بهعنوان یک نسخه تغییرناپذیر منتشر کنید که send_email با template.key از آن استفاده خواهد کرد. در صورت خطای اعتبارسنجی با 422 و findings شکست میخورد، یا اگر قرارداد متغیرهای فعال قالبی را که در محیط عملیاتی استفاده میشود بشکند، با 409.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
template_id | string | بله | شناسه یا کلید قالب. (حداکثر 128 کاراکتر) |
{
"name": "publish_template",
"arguments": {
"template_id": "account-welcome"
}
}archive_templateبایگانی قالب
ارسالهای جدید با این قالب را متوقف میکند (تاریخچه حفظ میشود؛ با restore_template قابل بازگشت است). هر یکپارچهسازیای که با این کلید ارسال میکند با 404 شکست خواهد خورد.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
template_id | string | بله | شناسه یا کلید قالب. (حداکثر 128 کاراکتر) |
{
"name": "archive_template",
"arguments": {
"template_id": "account-welcome"
}
}restore_templateبازیابی قالب بایگانیشده
یک قالب بایگانیشده را دوباره فعال کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
template_id | string | بله | شناسه یا کلید قالب. (حداکثر 128 کاراکتر) |
{
"name": "restore_template",
"arguments": {
"template_id": "account-welcome"
}
}دامنهها و DNS
list_domainsفهرست دامنهها
دامنههای ارسال را همراه با setup_status تجمیعی (verified | checking | pending)، وضعیت DNS هر رکورد و وضعیت ورودی فهرست کنید. ممکن است کند باشد: دامنههای تأییدنشده بهصورت زنده دوباره بررسی میشوند. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_domains",
"arguments": {}
}get_domainدریافت جزئیات راهاندازی دامنه
یک دامنه را همراه با رکوردهای دقیق DNS برای انتشار (type، name، value)، وضعیت زنده هر رکورد از دو resolver عمومی، dns_issues همراه با راهحلها و وضعیت ورودی دریافت کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
domain_id | string | بله | شناسه دامنه (با dom_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "get_domain",
"arguments": {
"domain_id": "dom_123"
}
}add_domainافزودن دامنه ارسال
Register a domain you control for sending. Returns the DNS records (Easy DKIM CNAMEs) the owner must publish. Does not change DNS itself. Counts against the plan's domain limit.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
name | string | بله | نام دامنه بدون پیشوند، مثلاً example.com یا mail.example.com. (حداکثر 253 کاراکتر) |
default_from | string | خیر | نشانی فرستنده پیشفرض اختیاری روی این دامنه. |
{
"name": "add_domain",
"arguments": {
"name": "example.com"
}
}verify_domainتأیید دامنه
Run a live DNS and DKIM verification check now. Safe to repeat; poll every 30–60 s after DNS changes (propagation can take minutes to hours). Sending is allowed once status is verified.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
domain_id | string | بله | شناسه دامنه (با dom_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "verify_domain",
"arguments": {
"domain_id": "dom_123"
}
}delete_domainحذف دامنه
DESTRUCTIVE (مخرب): دامنه را همراه با مسیر دریافت ایمیل ورودی آن از فضای کاری حذف میکند. ارسال از آن بلافاصله پس از این کار شکست میخورد. رکوردهای DNS را نزد ارائهدهنده DNS شما حذف نمیکند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
domain_id | string | بله | شناسه دامنه (با dom_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "delete_domain",
"arguments": {
"domain_id": "dom_123"
}
}get_dns_providerتشخیص ارائهدهنده DNS و hostهای رکوردها
ارائهدهنده DNS معتبر (authoritative) دامنه را تشخیص میدهد و host نسبیای را که باید برای هر رکورد در آن ارائهدهنده وارد شود، رکورد DMARC پیشنهادی، راهنمای MX ورودی و در دسترس بودن راهاندازی یککلیکی (Domain Connect) را برمیگرداند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
domain_id | string | بله | شناسه دامنه (با dom_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "get_dns_provider",
"arguments": {
"domain_id": "dom_123"
}
}get_domain_connect_linkدریافت لینک راهاندازی یککلیکی DNS
وقتی get_dns_provider مقدار providers.domainConnect.available را گزارش میکند، یک URL رضایت امضاشده بسازید. آن را به انسان بدهید: او آن را باز میکند و تغییر DNS را نزد ارائهدهنده خود تأیید میکند. تا زمان تأیید چیزی تغییر نمیکند. در صورت عدم پشتیبانی، 409.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
domain_id | string | بله | شناسه دامنه (با dom_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "get_domain_connect_link",
"arguments": {
"domain_id": "dom_123"
}
}ایمیل ورودی
setup_inboundفعالسازی دریافت ایمیل ورودی برای یک دامنه
Provision inbound receiving for a verified domain. Uses the root domain when it has no conflicting MX, otherwise inbound.<domain>. Returns the MX record the owner must publish; it does not edit DNS.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
domain_id | string | بله | شناسه دامنه (با dom_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "setup_inbound",
"arguments": {
"domain_id": "dom_123"
}
}verify_inboundتأیید MX ورودی
رکورد MX ورودی را دوباره بررسی میکند. وقتی هر دو resolver عمومی آن را ببینند، وضعیت ready میشود.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
domain_id | string | بله | شناسه دامنه (با dom_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "verify_inbound",
"arguments": {
"domain_id": "dom_123"
}
}list_inboxesفهرست نشانیهای ورودی
نشانیهای دریافت را، بهصورت اختیاری برای یک دامنه، فهرست کنید. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
domain_id | string | خیر | فیلتر اختیاری شناسه دامنه. |
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_inboxes",
"arguments": {
"domain_id": "dom_123"
}
}get_inboxدریافت یک صندوق ورودی
یک نشانی ورودی را دریافت کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
inbox_id | string | بله | شناسه صندوق ورودی (با inb_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "get_inbox",
"arguments": {
"inbox_id": "inb_123"
}
}create_inboxساخت نشانی ورودی
نشانیای مانند support@<receiving domain> را روی دامنهای بسازید که وضعیت ورودی آن ready است (ابتدا setup_inbound و verify_inbound را اجرا کنید). ایمیلهای دریافتی در list_emails با direction برابر in نمایش داده میشوند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
domain_id | string | بله | شناسه دامنه (با dom_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
local_part | string | بله | بخش پیش از @، مثلاً support. (حداکثر 64 کاراکتر) |
name | string | خیر | نام نمایشی اختیاری. |
{
"name": "create_inbox",
"arguments": {
"domain_id": "dom_123",
"local_part": "support",
"name": "Support"
}
}update_inboxتغییر نام، فعال یا غیرفعال کردن صندوق ورودی
نام یک صندوق ورودی را تغییر دهید یا وضعیت آن را روی active / disabled تنظیم کنید.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
inbox_id | string | بله | شناسه صندوق ورودی (با inb_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
name | string | خیر | نام نمایشی جدید. |
status | string | خیر | وضعیت جدید. (یکی از active، disabled) |
{
"name": "update_inbox",
"arguments": {
"inbox_id": "inb_123",
"status": "disabled"
}
}set_inbox_forwardingفوروارد صندوق ورودی به نشانی دیگر
SENDS REAL EMAIL (ایمیل واقعی ارسال میکند) وقتی به کسی جز مالک حساب فوروارد شود: مقصد فوروارد ایمیلهای دریافتی یک صندوق ورودی را تنظیم میکند. نشانی خود مالک بلافاصله فعال میشود؛ هر نشانی دیگری یک ایمیل تأیید دریافت میکند و فوروارد تا زمانی که کسی در آنجا تأیید کند در وضعیت pending میماند. برای خاموش کردن فوروارد، forward_to: null را ارسال کنید. نسخههای فورواردشده از نشانی صندوق ورودی و با فرستنده اصلی بهعنوان Reply-To ارسال میشوند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
inbox_id | string | بله | شناسه صندوق ورودی (با inb_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
forward_to | string,null | بله | نشانی ایمیل مقصد فوروارد، یا null برای خاموش کردن فوروارد. (حداکثر 254 کاراکتر) |
{
"name": "set_inbox_forwarding",
"arguments": {
"inbox_id": "inb_123",
"forward_to": "team@example.net"
}
}delete_inboxحذف صندوق ورودی
DESTRUCTIVE (مخرب): یک نشانی ورودی را حذف میکند. ایمیلهایی که قبلاً دریافت شدهاند نگه داشته میشوند؛ ایمیلهای جدید به این نشانی دیگر در آن ثبت نمیشوند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
inbox_id | string | بله | شناسه صندوق ورودی (با inb_ شروع میشود)، همانطور که یک ابزار فهرست یا ایجاد برگردانده است. (حداکثر 128 کاراکتر) |
{
"name": "delete_inbox",
"arguments": {
"inbox_id": "inb_123"
}
}تحویلپذیری، برگشتها و فهرست توقف ارسال
deliverability_statsدریافت آمار تحویل 30 روزه
مجموعهای 30 روزه در سطح فضای کاری: sent، delivery، bounce، complaint، reject، open، click و deliveryRate (%).
بدون پارامتر.
{
"name": "deliverability_stats",
"arguments": {}
}deliverability_accountGet account delivery rates
Daily ladder, today's usage, 7-day hard-bounce and complaint rates against the promote, hold, and pause thresholds, and a per-day trend. Diagnostic text is plain text.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
days | integer | خیر | (one of 7, 30, 90) |
{
"name": "deliverability_account",
"arguments": {
"days": 30
}
}deliverability_domainsGet domain delivery rates
Per sending domain: sent, delivered, hard and soft bounces, complaints, failures, rates, and an active Gmail cap or 4.7.28 backoff when one applies.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
days | integer | خیر | |
domain | string | خیر | |
limit | integer | خیر | |
offset | integer | خیر |
{
"name": "deliverability_domains",
"arguments": {
"days": 30
}
}deliverability_sendersGet sender delivery rates
Per From address: sent, delivered, hard and soft bounces, complaints, failures, and rates.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
days | integer | خیر | |
domain | string | خیر | |
limit | integer | خیر | |
offset | integer | خیر |
{
"name": "deliverability_senders",
"arguments": {
"days": 30
}
}list_sender_reputationفهرست اعتبار فرستنده
وضعیت اعتبار برای هر نشانی From مشخص: active، throttled (محدودیت روزانه کمتر) یا paused (ارسالها 423 برمیگردانند)، همراه با دلیل و محدودیت روزانه. وقتی ارسالها با 423 یا 429 شکست میخورند این را بررسی کنید. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_sender_reputation",
"arguments": {}
}list_suppressionsفهرست موارد توقف ارسال
فهرست توقف ارسال فضای کاری: گیرندگانی که پس از برگشت دائمی یا گزارش اسپم مسدود شدهاند. ارسال به آنها با 422 شکست میخورد. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_suppressions",
"arguments": {}
}remove_suppressionحذف مورد توقف ارسال ناشی از برگشت ایمیل
DESTRUCTIVE (مخرب؛ یک مانع ایمنی را تضعیف میکند): یک مورد توقف ارسال ناشی از برگشت را حذف میکند تا بتوان دوباره به آن نشانی ایمیل فرستاد. فقط وقتی این کار را انجام دهید که انسان تأیید کند نشانی اکنون معتبر است. موارد ناشی از گزارش اسپم قابل حذف نیستند (409).
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
email | string | بله | نشانی گیرنده موجود در فهرست توقف ارسال. (حداکثر 320 کاراکتر) |
{
"name": "remove_suppression",
"arguments": {
"email": "fixed-mailbox@example.net"
}
}list_blocked_recipientsفهرست گیرندگان مسدودشده
همه گیرندگانی که SendHQ از ارسال به آنها خودداری میکند: برگشتها، گزارشهای اسپم و لغو اشتراکهای بازاریابی در سطح دامنه، همراه با خلاصهای به تفکیک نوع. حداکثر 500 مورد جدیدتر را میخواند. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_blocked_recipients",
"arguments": {}
}Campaigns
list_contactsList contacts
Campaigns: Newest-first contacts with their status, consent evidence, tags, custom fields, engagement (bot-filtered, estimated opens and clicks), and the lists they are subscribed to. Filter by list, status (including dormant), email/name substring (* is an email wildcard, e.g. *@example.com), tag, source, signup date, or a saved segment. Paginated: the result includes pagination {offset, limit, returned, has_more, next_offset}.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
list_id | string | خیر | Only members of this list (lst_…). |
status | string | خیر | Only contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant) |
query | string | خیر | Email or name contains this text; * is a wildcard on the email. (max 200 chars) |
tag | string | خیر | Only contacts with this tag. (max 60 chars) |
source | string | خیر | How the contact was added. (one of form, api, import) |
after | string | خیر | Signed up at or after this time. ISO 8601 date or date-time. (max 40 chars) |
before | string | خیر | Signed up before this time. ISO 8601 date or date-time. (max 40 chars) |
segment_id | string | خیر | Only contacts matching this saved segment (seg_…). |
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_contacts",
"arguments": {
"status": "subscribed"
}
}create_contactAdd a contact
Campaigns: Add one contact to the workspace, optionally to lists and with tags. A subscribed contact (the default) needs consent_basis: how this person agreed to receive your email. Only add people who asked for your email. Use status: unsubscribed to record an opt-out. Addresses already suppressed or unsubscribed from the workspace are stored with that status. Fails with 409 if the email already exists.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
email | string | بله | Email address. (max 320 chars) |
name | string | خیر | Display name; the first word is {{first_name}}. (max 200 chars) |
fields | object | خیر | Custom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field. |
tags | string[] | خیر | Tags to attach, e.g. ["VIP"]. Up to 50. (0–50 items) |
list_ids | string[] | خیر | Lists to add the contact to (lst_…). (0–100 items) |
status | string | خیر | subscribed (default, requires consent_basis) or unsubscribed. (one of subscribed, unsubscribed) |
consent_basis | string | خیر | How these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars) |
{
"name": "create_contact",
"arguments": {
"email": "ada@example.net",
"name": "Ada Lovelace",
"consent_basis": "Ticked the newsletter box at checkout on acme.com"
}
}get_contactGet a contact
Campaigns: One contact by ID or email: status, consent evidence (source, basis, opt-in and confirmation times), custom fields, and subscribed lists.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
contact_id | string | بله | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "get_contact",
"arguments": {
"contact_id": "ct_123"
}
}update_contactUpdate, tag, or unsubscribe a contact
Campaigns: Change a contact's name, merge custom fields (null removes one), change tags (tags replaces the whole set; add_tags and remove_tags change it), or set status to unsubscribed. A contact can never be resubscribed through the API; only the recipient can, by confirming a signup form.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
contact_id | string | بله | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
name | string | خیر | New display name. (max 200 chars) |
fields | object | خیر | Custom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field. |
tags | string[] | خیر | Replace all of the contact's tags with these. (0–50 items) |
add_tags | string[] | خیر | Tags to add. (0–50 items) |
remove_tags | string[] | خیر | Tags to remove. (0–50 items) |
status | string | خیر | Only unsubscribed is accepted. (one of unsubscribed) |
{
"name": "update_contact",
"arguments": {
"contact_id": "ct_123",
"fields": {
"plan": "team"
}
}
}delete_contactDelete a contact
DESTRUCTIVE: permanently delete a contact and its list memberships. Suppressions and recorded unsubscribes are kept, so the address still cannot be mailed if it is added again. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
contact_id | string | بله | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "delete_contact",
"arguments": {
"contact_id": "ct_123"
}
}import_contactsImport contacts from CSV
Campaigns: Import up to 5,000 CSV rows (5 MB) per call, optionally into a list. The header row needs an email column; name (or first_name/last_name), status, and tags (separated by ; or |) are recognized and other columns become custom fields. consent_basis is required and recorded on every new contact. tags are added to every accepted row. Rows whose status says unsubscribed import as unsubscribed; existing contacts keep their status. Returns counts of accepted, created, existing, skipped (duplicates), and invalid rows with line numbers.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
csv | string | بله | The CSV file content, header row first. (max 5242880 chars) |
list_id | string | خیر | Add every accepted row to this list (lst_…). |
consent_basis | string | بله | How these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars) |
tags | string[] | خیر | Tags to add to every accepted row, e.g. ["imported-2026-11"]. (0–50 items) |
update_existing | boolean | خیر | Merge names and fields into contacts that already exist. Their status never changes. |
{
"name": "import_contacts",
"arguments": {
"csv": "email,name\nada@example.net,Ada Lovelace\n",
"consent_basis": "Newsletter signups exported from Mailchimp (double opt-in)"
}
}list_contact_importsList contact imports
Campaigns: Recent CSV imports with their consent basis and row counts.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_contact_imports",
"arguments": {}
}bulk_update_contactsBulk update contacts
DESTRUCTIVE when action is delete (permanent) or unsubscribe (cannot be undone through the API). Apply one action to up to 10,000 contacts: the IDs in contact_ids, or everyone matching filter (the list_contacts filters). Actions: tag / untag (with tags), add_to_list / remove_from_list (with list_id), unsubscribe, delete. Adding to a list mirrors each contact's status, so nobody is resubscribed. delete needs confirm_count equal to the number of contacts it would delete: call once without it to get that count (409), confirm with the user, then repeat with it. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
action | string | بله | What to do. (one of tag, untag, add_to_list, remove_from_list, unsubscribe, delete) |
contact_ids | string[] | خیر | Contact IDs (ct_…). Use this or filter. (0–10000 items) |
filter | object | خیر | Everyone matching these list_contacts filters. Use this or contact_ids. |
filter.list_id | string | خیر | Members of this list. |
filter.status | string | خیر | Only contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant) |
filter.query | string | خیر | Email or name contains; * is an email wildcard. (max 200 chars) |
filter.tag | string | خیر | Has this tag. (max 60 chars) |
filter.source | string | خیر | How the contact was added. (one of form, api, import) |
filter.after | string | خیر | Signed up at or after. ISO 8601 date or date-time. (max 40 chars) |
filter.before | string | خیر | Signed up before. ISO 8601 date or date-time. (max 40 chars) |
filter.segment_id | string | خیر | Matches this segment. |
tags | string[] | خیر | For tag and untag. (0–50 items) |
list_id | string | خیر | For add_to_list and remove_from_list (lst_…). |
confirm_count | integer | خیر | For delete: the number of contacts that will be deleted, from the 409 response. (0–…) |
{
"name": "bulk_update_contacts",
"arguments": {
"action": "tag",
"tags": [
"october"
],
"filter": {
"list_id": "lst_123",
"status": "subscribed"
}
}
}list_tagsList contact tags
Campaigns: The workspace's contact tags, most used first, with how many contacts carry each (up to 500). Paginated.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_tags",
"arguments": {}
}list_contact_fieldsList custom contact fields
Campaigns: Defined custom contact fields with label and type (text, number, date). Defined fields are known to check_broadcast's merge-tag check and typed in segment conditions. Contacts may also carry undefined keys. Paginated.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_contact_fields",
"arguments": {}
}set_contact_fieldDefine a custom contact field
Campaigns: Create or change a custom field definition (label and type). Values live on each contact's fields. Built-in merge tags (email, name, first_name, last_name, fields, unsubscribe_url) cannot be used as keys. A workspace may define 50 fields.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
field_key | string | بله | Field key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars) |
label | string | خیر | Label shown in the dashboard. Defaults to the key. (max 80 chars) |
type | string | خیر | text (default), number, or date. (one of text, number, date) |
{
"name": "set_contact_field",
"arguments": {
"field_key": "plan",
"label": "Plan",
"type": "text"
}
}delete_contact_fieldDelete a custom field definition
DESTRUCTIVE: delete a custom field definition. Values already stored on contacts are kept. Fails with 404 when the field is not defined. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
field_key | string | بله | Field key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars) |
{
"name": "delete_contact_field",
"arguments": {
"field_key": "plan"
}
}list_segmentsList segments
Campaigns: Saved segments with count (subscribed, non-dormant contacts in the workspace that match now) and fields, the condition fields and operators each accepts. Paginated.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_segments",
"arguments": {}
}get_segmentGet a segment
Campaigns: One segment with its conditions and live count.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
segment_id | string | بله | Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars) |
{
"name": "get_segment",
"arguments": {
"segment_id": "seg_123"
}
}preview_segmentPreview segment conditions
Campaigns: Count and sample (up to 5) the subscribed, non-dormant contacts that match conditions without saving them. Read-only; use it to check conditions before create_segment.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
match | string | خیر | all (default): every condition must match. any: at least one. (one of all, any) |
conditions | object[] | خیر | Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items) |
conditions[].field | string | بله | tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars) |
conditions[].key | string | خیر | Custom field key when field is field. (max 40 chars) |
conditions[].op | string | بله | tag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt) |
conditions[].value | string,number | خیر | Required except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after. |
{
"name": "preview_segment",
"arguments": {
"match": "all",
"conditions": [
{
"field": "tag",
"op": "has",
"value": "VIP"
},
{
"field": "opened",
"op": "in_last_days",
"value": 90
}
]
}
}create_segmentCreate a segment
Campaigns: Save a segment: up to 20 conditions joined by match. Use it as a broadcast's audience.segment_id, as list_contacts segment_id, or in bulk_update_contacts filters. A workspace may have 200 segments.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
name | string | بله | Segment name. (max 120 chars) |
match | string | خیر | all (default): every condition must match. any: at least one. (one of all, any) |
conditions | object[] | خیر | Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items) |
conditions[].field | string | بله | tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars) |
conditions[].key | string | خیر | Custom field key when field is field. (max 40 chars) |
conditions[].op | string | بله | tag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt) |
conditions[].value | string,number | خیر | Required except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after. |
{
"name": "create_segment",
"arguments": {
"name": "Engaged pro customers",
"conditions": [
{
"field": "fields.plan",
"op": "equals",
"value": "pro"
},
{
"field": "opened",
"op": "in_last_days",
"value": 90
}
]
}
}update_segmentUpdate a segment
Campaigns: Rename a segment or change match or conditions (which replaces the whole list). Broadcasts using it pick up the change when they start sending.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
segment_id | string | بله | Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars) |
name | string | خیر | Segment name. (max 120 chars) |
match | string | خیر | all (default): every condition must match. any: at least one. (one of all, any) |
conditions | object[] | خیر | Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items) |
conditions[].field | string | بله | tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars) |
conditions[].key | string | خیر | Custom field key when field is field. (max 40 chars) |
conditions[].op | string | بله | tag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt) |
conditions[].value | string,number | خیر | Required except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after. |
{
"name": "update_segment",
"arguments": {
"segment_id": "seg_123",
"name": "Pro customers"
}
}delete_segmentDelete a segment
DESTRUCTIVE: delete a saved segment. Contacts are not affected. Fails with 409 while a sending or scheduled broadcast uses it. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
segment_id | string | بله | Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars) |
{
"name": "delete_segment",
"arguments": {
"segment_id": "seg_123"
}
}list_listsList contact lists
Campaigns: Contact lists with subscribed, pending, and unsubscribed counts and their hosted signup form settings.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_lists",
"arguments": {}
}create_listCreate a list
Campaigns: Create a contact list. Set form_enabled to publish a hosted double opt-in signup form (its URL is in form.url); form_from is the sender, on a verified domain, of the confirmation email, and redirect_url is an optional https page shown after confirming. welcome sends one welcome email when someone confirms. site publishes a public newsletter site at https://sendhq.cc/n/<slug> with the signup form, sent issues, and RSS.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
name | string | بله | List name, shown on the signup form. (max 200 chars) |
description | string | خیر | Short description shown on the signup form. (max 500 chars) |
form_enabled | boolean | خیر | Publish the hosted signup form. |
form_from | string | خیر | Sender of signup confirmation emails, e.g. Acme <news@example.com>, on a verified domain. (max 320 chars) |
redirect_url | string | خیر | https page to open after a signup is confirmed. (max 500 chars) |
welcome | object | خیر | Welcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled. |
welcome.enabled | boolean | خیر | Send it. |
welcome.subject | string | خیر | Subject; merge tags allowed. (max 300 chars) |
welcome.html | string | خیر | HTML body; merge tags allowed. (max 500000 chars) |
welcome.markdown | string | خیر | Markdown body instead of html, rendered with the workspace design. (max 200000 chars) |
site | object | خیر | Public newsletter site at https://sendhq.cc/n/<slug>: a signup form, every issue sent with web.enabled, and an RSS feed at /n/<slug>/feed.xml. Needs the signup form on. A reserved or taken slug fails with 409. |
site.enabled | boolean | خیر | Publish the site. |
site.slug | string,null | خیر | Address after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars) |
site.title | string,null | خیر | Site title. Defaults to the list name. (max 120 chars) |
site.description | string,null | خیر | Short description under the title. (max 300 chars) |
site.accent | string,null | خیر | Accent color, e.g. #0a7d4f. |
{
"name": "create_list",
"arguments": {
"name": "Product updates"
}
}get_listGet a list
Campaigns: One list with member counts and signup form settings.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
list_id | string | بله | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
{
"name": "get_list",
"arguments": {
"list_id": "lst_123"
}
}update_listUpdate a list
Campaigns: Rename a list, change its description, or change its hosted signup form, welcome email, or newsletter site. Omitted keys inside welcome and site keep their value.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
list_id | string | بله | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
name | string | خیر | New name. (max 200 chars) |
description | string | خیر | New description. (max 500 chars) |
form_enabled | boolean | خیر | Publish or unpublish the hosted signup form. |
form_from | string | خیر | Sender of signup confirmation emails, on a verified domain. (max 320 chars) |
redirect_url | string | خیر | https page to open after a signup is confirmed. (max 500 chars) |
welcome | object | خیر | Welcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled. |
welcome.enabled | boolean | خیر | Send it. |
welcome.subject | string | خیر | Subject; merge tags allowed. (max 300 chars) |
welcome.html | string | خیر | HTML body; merge tags allowed. (max 500000 chars) |
welcome.markdown | string | خیر | Markdown body instead of html, rendered with the workspace design. (max 200000 chars) |
site | object | خیر | Public newsletter site at https://sendhq.cc/n/<slug>: a signup form, every issue sent with web.enabled, and an RSS feed at /n/<slug>/feed.xml. Needs the signup form on. A reserved or taken slug fails with 409. |
site.enabled | boolean | خیر | Publish the site. |
site.slug | string,null | خیر | Address after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars) |
site.title | string,null | خیر | Site title. Defaults to the list name. (max 120 chars) |
site.description | string,null | خیر | Short description under the title. (max 300 chars) |
site.accent | string,null | خیر | Accent color, e.g. #0a7d4f. |
{
"name": "update_list",
"arguments": {
"list_id": "lst_123",
"form_enabled": false
}
}delete_listDelete a list
DESTRUCTIVE: delete a list and its memberships. The contacts themselves are kept. Fails with 409 while a broadcast to the list is sending. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
list_id | string | بله | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
{
"name": "delete_list",
"arguments": {
"list_id": "lst_123"
}
}add_list_contactsAdd contacts to a list
Campaigns: Add up to 500 existing contacts to a list by ID or email. Subscribed contacts join subscribed; others join in their current state. Unknown references come back in notFound.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
list_id | string | بله | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
contact_ids | string[] | خیر | Contact IDs (ct_…). (0–500 items) |
emails | string[] | خیر | Contact email addresses. (0–500 items) |
{
"name": "add_list_contacts",
"arguments": {
"list_id": "lst_123",
"emails": [
"ada@example.net"
]
}
}remove_list_contactRemove a contact from a list
DESTRUCTIVE: remove one contact from a list. The contact and its status are kept. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
list_id | string | بله | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
contact_id | string | بله | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "remove_list_contact",
"arguments": {
"list_id": "lst_123",
"contact_id": "ct_123"
}
}list_broadcastsList broadcasts
Campaigns: Newest-first broadcasts with their status. Paginated: the result includes pagination.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
status | string | خیر | Only broadcasts with this status. (one of draft, sending, sent, cancelled, failed) |
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_broadcasts",
"arguments": {}
}create_broadcastCreate a broadcast draft
Campaigns: Create a draft broadcast to one list. Content is html and/or text, markdown, a block document in content, or a published hosted template. Raw content supports merge tags: {{first_name}}, {{name}}, {{email}}, {{fields.plan}}, with fallbacks like {{first_name | there}}. audience narrows it to a segment and/or a number of people (most engaged first with order: engaged); tracking turns open and click tracking off; web publishes it on the list's newsletter site once sent. Nothing is sent until send_broadcast or schedule_broadcast; run check_broadcast and send_broadcast_test first.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
name | string | خیر | Internal name. Defaults to the subject. (max 200 chars) |
list_id | string | خیر | The list to send to (lst_…). |
from | string | خیر | Sender on a verified domain, e.g. Acme <news@example.com>. (max 320 chars) |
reply_to | string | خیر | Reply-To address. (max 320 chars) |
subject | string | خیر | Subject line; merge tags allowed. (max 998 chars) |
preview_text | string | خیر | Inbox preview text shown after the subject. (max 300 chars) |
html | string | خیر | HTML body; merge tags allowed and escaped. |
text | string | خیر | Plain-text body; merge tags allowed. |
template | object | خیر | A published hosted template instead of subject/html/text. Template variables are filled from the contact's name, email, and fields. |
template.id | string | خیر | |
template.key | string | خیر | |
template.version_id | string | خیر | |
markdown | string | خیر | Markdown body instead of html: converted to a block document and rendered with the workspace design (get_newsletter_settings). Merge tags allowed. Not combinable with html or content. (max 1000000 chars) |
content | object,null | خیر | Block document ({"type": "doc", "content": [...]}, the dashboard editor's format: paragraph, heading, bulletList, orderedList, blockquote, image, button, callout, horizontalRule, codeBlock). Rendered with the workspace design unless html is also sent. |
editor | string | خیر | Which editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks) |
audience | object | خیر | Who gets it, within the list. Subscribed, non-dormant members only. |
audience.segment_id | string,null | خیر | Only list members matching this segment (seg_…), or null for the whole list. |
audience.order | string | خیر | With a limit: signup (default) or engaged (most engaged first). (one of signup, engaged) |
audience.limit | integer,null | خیر | Send to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000) |
tracking | object | خیر | Open and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email. |
tracking.opens | boolean | خیر | Add an open pixel. |
tracking.clicks | boolean | خیر | Rewrite links to signed SendHQ redirects (the unsubscribe link never is). |
web | object | خیر | Publish this issue on the list's newsletter site (see create_list site) once it is sent. |
web.enabled | boolean | خیر | Publish it. |
web.slug | string,null | خیر | Issue address; defaults to the subject. (max 100 chars) |
web.pinned | boolean | خیر | Keep it at the top of the site. |
{
"name": "create_broadcast",
"arguments": {
"list_id": "lst_123",
"from": "news@example.com",
"subject": "October update",
"markdown": "Hi {{first_name | there}}, here's what shipped.",
"audience": {
"order": "engaged",
"limit": 1000
}
}
}get_broadcastGet a broadcast
Campaigns: One broadcast with its content and, once sending, recipient totals (queued, sending, sent, held, skipped, failed). While a limit or reputation pause holds delivery, lastError explains why and nextAttemptAt says when it resumes.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "get_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}update_broadcastEdit a draft broadcast
Campaigns: Change any field of an unscheduled draft broadcast (content, audience, tracking, web). A scheduled draft must be unscheduled first (unschedule_broadcast); sent or sending broadcasts cannot be edited.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
name | string | خیر | Internal name. (max 200 chars) |
list_id | string | خیر | The list to send to. |
from | string | خیر | Sender on a verified domain. (max 320 chars) |
reply_to | string | خیر | Reply-To address. (max 320 chars) |
subject | string | خیر | موضوع ایمیل. (حداکثر 998 کاراکتر) |
preview_text | string | خیر | Inbox preview text. (max 300 chars) |
html | string | خیر | بدنه HTML. |
text | string | خیر | متن ساده. |
template | object,null | خیر | A published hosted template, or null to remove it. |
markdown | string | خیر | Markdown body instead of html: converted to a block document and rendered with the workspace design (get_newsletter_settings). Merge tags allowed. Not combinable with html or content. (max 1000000 chars) |
content | object,null | خیر | Block document ({"type": "doc", "content": [...]}, the dashboard editor's format: paragraph, heading, bulletList, orderedList, blockquote, image, button, callout, horizontalRule, codeBlock). Rendered with the workspace design unless html is also sent. |
editor | string | خیر | Which editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks) |
audience | object | خیر | Who gets it, within the list. Subscribed, non-dormant members only. |
audience.segment_id | string,null | خیر | Only list members matching this segment (seg_…), or null for the whole list. |
audience.order | string | خیر | With a limit: signup (default) or engaged (most engaged first). (one of signup, engaged) |
audience.limit | integer,null | خیر | Send to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000) |
tracking | object | خیر | Open and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email. |
tracking.opens | boolean | خیر | Add an open pixel. |
tracking.clicks | boolean | خیر | Rewrite links to signed SendHQ redirects (the unsubscribe link never is). |
web | object | خیر | Publish this issue on the list's newsletter site (see create_list site) once it is sent. |
web.enabled | boolean | خیر | Publish it. |
web.slug | string,null | خیر | Issue address; defaults to the subject. (max 100 chars) |
web.pinned | boolean | خیر | Keep it at the top of the site. |
{
"name": "update_broadcast",
"arguments": {
"broadcast_id": "bc_123",
"subject": "October product update"
}
}delete_broadcastDelete a draft broadcast
DESTRUCTIVE: permanently delete a draft broadcast. Broadcasts that were sent cannot be deleted. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "delete_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}send_broadcastSend a broadcast
SENDS REAL EMAIL to the broadcast's audience: every subscribed, non-dormant member of its list, narrowed by its segment and limit. Only call it when the user asked to send this broadcast now. Each message goes through the normal checks (verified domain, marketing plan, suppressions, unsubscribes, reputation, daily and monthly limits) and carries one-click unsubscribe from this list; members that cannot be mailed are skipped. Each contact is sent at most once. Delivery continues in the background: poll get_broadcast for totals and get_broadcast_report for engagement. A scheduled broadcast fails with 409 until unscheduled. Unpaid workspaces (integration trial) can send only to the account email. Pass idempotency_key so a retry cannot start the send twice. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
idempotency_key | string | خیر | هدر Idempotency-Key (حداکثر 200 کاراکتر). فقط برای تلاش مجدد همین درخواست دقیق دوباره از آن استفاده کنید. (حداکثر 200 کاراکتر) |
{
"name": "send_broadcast",
"arguments": {
"broadcast_id": "bc_123",
"idempotency_key": "october-update"
}
}cancel_broadcastCancel a broadcast
DESTRUCTIVE: stop a draft or sending broadcast for good. Recipients not yet sent are marked skipped; messages already handed to the provider are not recalled. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "cancel_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}list_broadcast_recipientsList broadcast recipients
Campaigns: Per-recipient outcomes and engagement of a broadcast: queued, sending, sent, held, skipped (with the reason), or failed (with the error), the inbox provider, delivered/opened/clicked/bounced/complained/unsubscribed times, and the email ID to inspect delivery events with list_email_events. Filter by outcome, by activity (who opened, clicked, did not open, ...), or by email. Opens are bot-filtered estimates, never proof of reading. Paginated.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
status | string | خیر | Only recipients with this outcome. (one of queued, sending, sent, held, skipped, failed) |
activity | string | خیر | Only recipients who did this. (one of opened, clicked, not_opened, not_delivered, bounced, complained, unsubscribed) |
query | string | خیر | Recipient email contains this text. (max 200 chars) |
include | string | خیر | links adds the links each recipient clicked (implied by activity: clicked). (one of links) |
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_broadcast_recipients",
"arguments": {
"broadcast_id": "bc_123",
"status": "failed"
}
}check_broadcastRun a broadcast's pre-send checks
Campaigns: The review list shown before sending: sender verification, subject, preview text, content, audience size, size against Gmail's 102 KB clipping limit, postal address, merge tags without data or fallback, empty or shortened links, image descriptions, placeholder text, spam-prone wording, the trial's own-address rule, and whether a test was sent. ready is false while any check has level block; schedule_broadcast refuses then. Fix warn items or tell the user about them.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "check_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}send_broadcast_testSend a broadcast test
SENDS REAL EMAIL: a copy of the draft marked [Test] to up to 5 addresses (default: the saved test recipients, or the account email), with merge tags filled from contact_id or a sample contact. Never goes to the list. Only send to addresses the user gave or owns. Limited to 100 test sends a day. Template broadcasts are tested with send_template_test. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
to | string[] | خیر | Test recipients (up to 5). (1–5 items) |
contact_id | string | خیر | Fill merge tags from this contact (ct_…). (max 320 chars) |
remember | boolean | خیر | Save to as the default test recipients. |
{
"name": "send_broadcast_test",
"arguments": {
"broadcast_id": "bc_123",
"to": [
"owner@example.com"
]
}
}schedule_broadcastSchedule a broadcast
SENDS REAL EMAIL at scheduled_at to the broadcast's audience, with the same checks as send_broadcast. Only call it when the user asked to send this broadcast at that time. The pre-send checks run now (422 with checks if one blocks). It starts within about a minute of the time; if it can no longer send then, it returns to a draft with the reason in lastError. A scheduled draft cannot be edited until unschedule_broadcast. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
scheduled_at | string | بله | When to send: ISO 8601 date-time with a timezone, at least a minute and at most a year ahead, e.g. 2026-11-10T09:00:00Z. (max 40 chars) |
{
"name": "schedule_broadcast",
"arguments": {
"broadcast_id": "bc_123",
"scheduled_at": "2026-11-10T09:00:00Z"
}
}unschedule_broadcastUnschedule a broadcast
Campaigns: Return a scheduled broadcast to an editable draft so it does not send. Fails with 409 when it is not scheduled.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "unschedule_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}duplicate_broadcastDuplicate a broadcast
Campaigns: Copy any broadcast (draft, sent, or cancelled) into a new draft named <name> (copy) with the same list, sender, content, audience, and tracking settings. Nothing is sent.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "duplicate_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}send_broadcast_to_moreSend a broadcast to more people
SENDS REAL EMAIL: sends a sent or sending broadcast to up to limit more people in its audience who have not received it (the rest of a limited audience, or people who joined since), in its audience order. Only call it when the user asked for this. Same checks as send_broadcast; each contact still gets it at most once. Fails with 422 when everyone already got it. Pass idempotency_key so a retry cannot add people twice. Part of Campaigns.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
limit | integer | بله | How many more people at most. (1–10000000) |
idempotency_key | string | خیر | هدر Idempotency-Key (حداکثر 200 کاراکتر). فقط برای تلاش مجدد همین درخواست دقیق دوباره از آن استفاده کنید. (حداکثر 200 کاراکتر) |
{
"name": "send_broadcast_to_more",
"arguments": {
"broadcast_id": "bc_123",
"limit": 500,
"idempotency_key": "october-update-more-1"
}
}get_broadcast_reportGet a broadcast report
Campaigns: Engagement for a sending or sent broadcast: unique and total opens and clicks, bounces, complaints, and unsubscribes with rates in percent, the same per inbox provider, clicks per link, first opens and clicks by hour, and the average of the previous five broadcasts. Opens are estimates: automated requests (scanners, link previews, privacy prefetching) are counted only in machine. Never claim that a person read the email. Fails with 409 for a draft.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
broadcast_id | string | بله | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "get_broadcast_report",
"arguments": {
"broadcast_id": "bc_123"
}
}get_newsletter_settingsGet newsletter settings
Campaigns: The postal address added to every marketing email footer, the design (accent color, font, alignment) used for Markdown and block content, list cleanup settings, and default test recipients.
بدون پارامتر.
{
"name": "get_newsletter_settings",
"arguments": {}
}update_newsletter_settingsUpdate newsletter settings
Campaigns: Change the postal address (required in marketing email by CAN-SPAM and CASL), design, list cleanup, or default test recipients. Omitted keys keep their value. List cleanup is on by default and sends email automatically: a subscriber who got afterSends broadcasts in a row without opening or clicking and has been quiet for quietDays gets one "still want these?" email; a week later those who did not confirm become dormant (kept, but skipped by broadcasts). Confirm with the user before turning it on or changing its email.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
postal_address | string | خیر | Sender's postal address for the footer. Empty string removes it. (max 300 chars) |
design | object | خیر | Rendering design for Markdown and block content. |
design.accentColor | string,null | خیر | Hex color like #0a7d4f, or null for the default. |
design.font | string | خیر | Font family. (one of sans, serif, mono) |
design.align | string | خیر | Text alignment. (one of left, center) |
cleanup | object | خیر | List cleanup of readers who stopped opening. |
cleanup.enabled | boolean | خیر | Turn list cleanup on or off. |
cleanup.afterSends | integer | خیر | Broadcasts in a row without an open or click (3-50). (3–50) |
cleanup.quietDays | integer | خیر | Days without engagement (30-730). (30–730) |
cleanup.subject | string,null | خیر | Subject of the cleanup email; merge tags allowed. (max 200 chars) |
cleanup.body | string,null | خیر | Body text of the cleanup email. (max 2000 chars) |
cleanup.from | string,null | خیر | Sender on a verified domain. Defaults to the last sent broadcast's sender. (max 320 chars) |
test_recipients | string[] | خیر | Default addresses for send_broadcast_test (up to 5). (0–5 items) |
{
"name": "update_newsletter_settings",
"arguments": {
"postal_address": "Acme Inc., 1 Main St, Springfield",
"design": {
"accentColor": "#0a7d4f"
}
}
}get_campaign_overviewGet campaign overview
Campaigns: Subscriber growth and recent results for the last days (7-365, default 30): active, dormant, and pending subscribers, joined and left, a daily series, and the six latest broadcasts with open and click rates (bot-filtered estimates) and their average.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
days | integer | خیر | Window in days, 7 to 365. Defaults to 30. (7–365) |
{
"name": "get_campaign_overview",
"arguments": {
"days": 30
}
}list_uploaded_imagesList uploaded images
Campaigns: The workspace's 60 most recent editor image uploads with their public URLs (https://sendhq.cc/i/<id>), to reuse in broadcast HTML, Markdown, or image blocks. Uploading needs the dashboard or the REST API (raw image body). Paginated.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_uploaded_images",
"arguments": {}
}حساب، میزان مصرف، analytics و کلیدها
get_accountدریافت حساب، میزان مصرف و صورتحساب
ایمیل مالک حساب، پلن/سطح دسترسی، تحویل به گیرندگان مصرفشده در دوره جاری در برابر سهمیه، دامنههای مصرفشده در برابر سقف، انتقال پیوست، خلاصه اعتبار، وضعیت اشتراک، پلنهای منتشرشده و شمارشهای فضای کاری. از آن برای بررسی سهمیه باقیمانده یا اینکه دوره آزمایشی به چه کسی میتواند تحویل دهد (ایمیل حساب) استفاده کنید.
بدون پارامتر.
{
"name": "get_account",
"arguments": {}
}get_account_diagnosticsDiagnose sending and receiving
One read that explains what is wrong with sending or receiving in this workspace: an issues list (unverified domains and missing DKIM records, inbound MX not ready, paused or throttled senders, quota or daily limit reached, trial restrictions, high bounce or complaint rates, failing webhooks), plan and usage against limits, each domain with its DKIM and inbound state, sending identities, 30-day deliverability and sender reputation, suppressions and unsubscribes, and the last 30 days of messages that were not sent (with reasons) plus bounce, complaint and reject events. Start here when a user asks why mail is not arriving. Never returns message bodies or secrets.
بدون پارامتر.
{
"name": "get_account_diagnostics",
"arguments": {}
}get_analyticsدریافت analytics ارسال
analytics داشبورد برای 7، 30 یا 90 روز گذشته: مجموع sent/received/delivered/bounced/blocked/opened/clicked/complaint، یک خط زمانی روزانه، دامنههای پرارسال و موضوعهای پرتکرار.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
days | integer | خیر | بازه به روز: 7، 30 (پیشفرض) یا 90. (یکی از 7، 30، 90) |
{
"name": "get_analytics",
"arguments": {
"days": 30
}
}list_api_keysفهرست فراداده کلیدهای API
نام کلیدهای API، پیشوندهای غیرمحرمانه و زمان آخرین استفاده را فهرست میکند. فقطخواندنی: این سرور MCP نمیتواند کلید بسازد، بچرخاند یا باطل کند؛ این کار را انسان در داشبورد انجام میدهد. صفحهبندیشده: نتیجه شامل pagination {offset, limit, returned, total?, has_more, next_offset} است.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer | خیر | اندازه صفحه. پیشفرض 50. (پیشفرض 50؛ 1 تا 200) |
offset | integer | خیر | تعداد رکوردهایی که باید رد شوند. از pagination.next_offset صفحه قبل استفاده کنید. (پیشفرض 0؛ 0 تا …) |
{
"name": "list_api_keys",
"arguments": {}
}get_service_healthبررسی سلامت سرویس SendHQ
بررسی میکند که API SendHQ در دسترس است و کدام ارائهدهنده ایمیل فعال است. به کلید API معتبر نیاز ندارد.
بدون پارامتر.
{
"name": "get_service_health",
"arguments": {}
}فهرست پوشش API
هر عملیات در API عمومی و ابزاری که آن را پوشش میدهد. هر کاری که کاربر در داشبورد میتواند انجام دهد و API دارد پوشش داده شده است؛ موارد مستثنای زیر عمدی هستند.
| Endpoint | ابزار | یادداشتها |
|---|---|---|
| POST /emails | send_email | ارسال یک ایمیل |
| POST /emails/batch | send_batch | ارسال حداکثر 100 پیام شخصیسازیشده |
| GET /emails | list_emails | فهرست ایمیلهای ارسالی و دریافتی |
| GET /emails/:id | get_email | دریافت یک ایمیل و پیوستهای آن |
| PATCH /emails/:id | mark_email | بهروزرسانی وضعیت خواندهشدن، بایگانی، اسپم، دسته یا اهمیت |
| POST /emails/:id/labels | label_email | افزودن یا حذف برچسبهای یک ایمیل |
| DELETE /emails/:id | delete_email | حذف یک ایمیل نگهداریشده |
| GET /emails/:id/events | list_email_events | فهرست رویدادهای تحویل یک ایمیل |
| GET /threads/:id | get_thread | دریافت یک مکالمه به ترتیب زمانی |
| GET /labels | list_labels | فهرست برچسبها همراه با تعداد پیامها و قوانین بایگانی |
| POST /labels | create_label | ساخت برچسب، بهصورت اختیاری همراه با قوانین بایگانی خودکار |
| GET /labels/:id | get_label | دریافت یک برچسب با شناسه یا نام |
| PATCH /labels/:id | update_label | تغییر نام، تغییر رنگ یا تبدیل برچسب به bucket |
| DELETE /labels/:id | delete_label | حذف یک برچسب بدون حذف ایمیلهای آن |
| POST /labels/:id/rules | create_label_rule | افزودن قانون بایگانی خودکار به یک برچسب |
| DELETE /labels/:id/rules/:rule_id | delete_label_rule | حذف یک قانون بایگانی خودکار |
| POST /drafts | create_draft | ساخت پیشنویس در ویرایشگر |
| GET /drafts | list_drafts | فهرست پیشنویسهای ویرایشگر |
| GET /drafts/:id | get_draft | دریافت یک پیشنویس و پیوستهای آن |
| PUT /drafts/:id | update_draft | جایگزینی محتوای پیشنویس |
| DELETE /drafts/:id | delete_draft | دور ریختن پیشنویس |
| POST /drafts/:id/attachments | upload_attachment | بارگذاری پیوست در یک پیشنویس |
| GET /attachments/:id | download_attachment | دانلود یک پیوست خصوصی |
| DELETE /attachments/:id | delete_attachment | حذف یک پیوست خصوصی |
| GET /sending-identities | list_sending_identities | فهرست هویتهای فرستنده تأییدشده |
| GET /templates | list_templates | فهرست قالبهای میزبانیشده |
| POST /templates | create_template | ساخت قالب میزبانیشده |
| GET /templates/:id | get_template | دریافت پیشنویسها، نسخههای منتشرشده و میزان استفاده |
| PUT /templates/:id/draft | update_template_draft | ذخیره خودکار پیشنویس قالب |
| POST /templates/:id/draft | create_template_draft | ساخت پیشنویس جدید از نسخه منتشرشده |
| POST /templates/:id/render | render_template | رندر خروجی دقیق سرور |
| POST /templates/:id/test | send_template_test | ارسال یک snapshot آزمایشی |
| POST /templates/:id/publish | publish_template | انتشار یک نسخه تغییرناپذیر از قالب |
| POST /templates/:id/archive | archive_template | بایگانی قالب |
| POST /templates/:id/restore | restore_template | بازیابی قالب بایگانیشده |
| POST /domains | add_domain | افزودن دامنه ارسال |
| GET /domains | list_domains | فهرست دامنهها و وضعیت ذخیرهشده DNS |
| GET /domains/:id | get_domain | دریافت جزئیات راهاندازی دامنه |
| POST /domains/:id/verify | verify_domain | Refresh domain and DNS verification |
| POST /domains/:id/inbound/setup | setup_inbound | Provision inbound receiving |
| POST /domains/:id/inbound/verify | verify_inbound | تأیید مسیریابی MX ورودی |
| DELETE /domains/:id | delete_domain | حذف دامنه |
| GET /dns/provider | get_dns_provider | تشخیص ارائهدهنده DNS معتبر (authoritative) و hostهای نسبی رکوردها |
| GET /dns/domain-connect/connect | get_domain_connect_link | ساخت لینک رضایت Domain Connect برای راهاندازی یککلیکی DNS |
| POST /inboxes | create_inbox | ساخت نشانی ورودی |
| GET /inboxes | list_inboxes | فهرست نشانیهای ورودی |
| GET /inboxes/:id | get_inbox | دریافت یک نشانی ورودی |
| PATCH /inboxes/:id | update_inbox | تغییر نام، فعال یا غیرفعال کردن صندوق ورودی |
| PUT /inboxes/:id/forwarding | set_inbox_forwarding | فوروارد ایمیلهای دریافتی یک صندوق ورودی به نشانی دیگر |
| DELETE /inboxes/:id | delete_inbox | حذف صندوق ورودی با حفظ پیامها |
| GET /deliverability/stats | deliverability_stats | دریافت آمار تحویل 30 روز اخیر |
| GET /deliverability/reputation | list_sender_reputation | فهرست وضعیت اعتبار به تفکیک دقیق هویت فرستنده |
| GET /deliverability/account | deliverability_account | Account delivery rates, daily ladder, and bounce trend |
| GET /deliverability/domains | deliverability_domains | Per-domain sent, delivered, hard and soft bounces, complaints, and failures |
| GET /deliverability/senders | deliverability_senders | Per-From-address delivery rates |
| GET /emails/:id/delivery | email_delivery | Delivery timeline for one email, with bounce and complaint reasons |
| GET /threads/:id/delivery | thread_delivery | Per-thread delivery counts and per-message failure reasons |
| GET /suppressions | list_suppressions | فهرست موارد توقف ارسال فضای کاری |
| DELETE /suppressions/:email | remove_suppression | حذف یک مورد توقف ارسال ناشی از برگشت ایمیل که واجد شرایط حذف است |
| GET /blocked-recipients | list_blocked_recipients | فهرست برگشتها، گزارشهای اسپم و لغو اشتراکها |
| GET /webhooks | در دسترس نیست | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| POST /webhooks | در دسترس نیست | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| GET /webhooks/:id | در دسترس نیست | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| PATCH /webhooks/:id | در دسترس نیست | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| DELETE /webhooks/:id | در دسترس نیست | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| POST /webhooks/:id/rotate-secret | در دسترس نیست | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| POST /webhooks/:id/test | در دسترس نیست | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| GET /webhooks/:id/deliveries | در دسترس نیست | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| GET /webhooks/:id/deliveries/:deliveryId | در دسترس نیست | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| POST /webhooks/:id/deliveries/:deliveryId/retry | در دسترس نیست | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| GET /contacts | list_contacts | List contacts |
| POST /contacts | create_contact | Add a contact with its consent basis |
| POST /contacts/bulk | bulk_update_contacts | Tag, move, unsubscribe, or delete many contacts at once |
| GET /contacts/export | در دسترس نیست | Image uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated). |
| GET /contacts/:id | get_contact | Retrieve a contact by ID or email |
| PATCH /contacts/:id | update_contact | Update a contact's name, fields, or tags, or unsubscribe it |
| DELETE /contacts/:id | delete_contact | Delete a contact and its list memberships |
| POST /contact-imports | import_contacts | Import contacts from CSV |
| GET /contact-imports | list_contact_imports | List recent contact imports |
| GET /tags | list_tags | List contact tags with how many contacts carry each |
| GET /contact-fields | list_contact_fields | List custom contact field definitions |
| PUT /contact-fields/:key | set_contact_field | Define or change a custom contact field |
| DELETE /contact-fields/:key | delete_contact_field | Delete a custom field definition |
| GET /segments | list_segments | List saved segments with live counts |
| POST /segments | create_segment | Save a segment |
| POST /segments/preview | preview_segment | Count and sample the contacts that match unsaved conditions |
| GET /segments/:id | get_segment | Retrieve a segment and its live count |
| PATCH /segments/:id | update_segment | Rename a segment or change its conditions |
| DELETE /segments/:id | delete_segment | Delete a segment |
| GET /lists | list_lists | List contact lists with member counts |
| POST /lists | create_list | Create a list with an optional signup form, welcome email, and newsletter site |
| GET /lists/:id | get_list | Retrieve a list |
| PATCH /lists/:id | update_list | Rename a list or change its signup form, welcome email, or site |
| DELETE /lists/:id | delete_list | Delete a list without deleting its contacts |
| POST /lists/:id/contacts | add_list_contacts | Add existing contacts to a list |
| DELETE /lists/:id/contacts/:contact_id | remove_list_contact | Remove a contact from a list |
| GET /broadcasts | list_broadcasts | List broadcasts |
| POST /broadcasts | create_broadcast | Create a broadcast draft |
| GET /broadcasts/:id | get_broadcast | Retrieve a broadcast and its delivery totals |
| PATCH /broadcasts/:id | update_broadcast | Edit a draft broadcast |
| DELETE /broadcasts/:id | delete_broadcast | Delete a draft broadcast |
| GET /broadcasts/:id/checks | check_broadcast | Run the pre-send checks for a broadcast |
| POST /broadcasts/:id/test | send_broadcast_test | Send a test copy of a draft |
| POST /broadcasts/:id/schedule | schedule_broadcast | Schedule a draft to send later |
| POST /broadcasts/:id/unschedule | unschedule_broadcast | Unschedule a draft |
| POST /broadcasts/:id/duplicate | duplicate_broadcast | Copy a broadcast into a new draft |
| POST /broadcasts/:id/send | send_broadcast | Send a broadcast to its audience |
| POST /broadcasts/:id/send-more | send_broadcast_to_more | Send a sent broadcast to more of its audience |
| POST /broadcasts/:id/cancel | cancel_broadcast | Cancel a draft or sending broadcast |
| GET /broadcasts/:id/recipients | list_broadcast_recipients | List a broadcast's recipients, outcomes, and engagement |
| GET /broadcasts/:id/report | get_broadcast_report | Retrieve a broadcast's engagement report |
| GET /campaigns/overview | get_campaign_overview | Retrieve subscriber growth and recent broadcast performance |
| GET /newsletter-settings | get_newsletter_settings | Retrieve newsletter settings |
| PATCH /newsletter-settings | update_newsletter_settings | Change newsletter settings |
| POST /uploads/images | در دسترس نیست | Image uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated). |
| GET /uploads/images | list_uploaded_images | List recently uploaded images |
| GET /account | get_account | دریافت حساب، میزان مصرف، وضعیت صورتحساب و شمارشهای فضای کاری با کلید API |
| GET /account/diagnostics | get_account_diagnostics | Diagnose sending and receiving problems in the workspace |
| GET /analytics | get_analytics | دریافت analytics ارسال داشبورد برای 7، 30 یا 90 روز |
| GET /profile | get_account | نسخه مبتنی بر نشست (session) از GET /account؛ سرور MCP مسیر مبتنی بر کلید API را میخواند. |
| POST /billing/checkout | در دسترس نیست | تغییرات صورتحساب طبق طراحی فقط از طریق نشست انجام میشوند و به حضور مالک حساب در داشبورد نیاز دارند. وضعیت صورتحساب با get_account قابلخواندن است. |
| POST /billing/cancel | در دسترس نیست | تغییرات صورتحساب طبق طراحی فقط از طریق نشست انجام میشوند و به حضور مالک حساب در داشبورد نیاز دارند. وضعیت صورتحساب با get_account قابلخواندن است. |
| POST /keys | در دسترس نیست | عمداً مستثنا شده است: ایجنت نباید اعتبارنامه بسازد یا از بین ببرد. کلیدها را انسان در داشبورد مدیریت میکند. |
| GET /keys | list_api_keys | فهرست فراداده کلیدهای API |
| DELETE /keys/:id | در دسترس نیست | عمداً مستثنا شده است: ایجنت نباید اعتبارنامه بسازد یا از بین ببرد. کلیدها را انسان در داشبورد مدیریت میکند. |
عمداً در دسترس نیست
| قابلیت | endpointها | دلیل |
|---|---|---|
| ساخت، چرخش، ابطال یا حذف کلیدهای API | POST /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 deliveries | GET /webhooks, POST /webhooks, GET /webhooks/:id, PATCH /webhooks/:id, DELETE /webhooks/:id, POST /webhooks/:id/rotate-secret, POST /webhooks/:id/test, GET /webhooks/:id/deliveries, GET /webhooks/:id/deliveries/:deliveryId, POST /webhooks/:id/deliveries/:deliveryId/retry | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| Upload editor images and export contacts as CSV | POST /uploads/images, GET /contacts/export | Image uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated). |
کاتالوگ قابلخواندن برای ماشین: /docs/mcp/tools.json (schemaها، annotationها، نگاشت endpointها، موارد مستثنا). نسخه Markdown این صفحه: /docs/mcp.md. با نصب CLI، دستور sendhq commands --format json همین کاتالوگ را چاپ میکند.