لوكلاء الذكاء الاصطناعي
خادم SendHQ MCP
Give an AI agent full, safe control of one SendHQ workspace: send and receive email, verify domains, publish templates, and investigate deliverability through 142 strictly typed tools. Written for agents first; humans welcome.
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcpما هذا الخادم
The SendHQ MCP server lets an AI agent operate one SendHQ workspace through the Model Context Protocol: send email (single, batch, templated, replies, attachments, idempotent retries), read and search sent and received mail (subjects, bodies, and attachment names) and its delivery events, organize mail into labels with auto-filing rules, manage drafts and private attachments, author and publish hosted templates, add and verify domains and their DNS, set up inbound receiving and inbound addresses, inspect deliverability, bounces, complaints, and suppressions, run newsletters (consented contacts with tags and custom fields, segments, lists with signup forms, welcome emails, and newsletter sites, and broadcasts with pre-send checks, test sends, scheduling, and bot-filtered open and click reports), and read account usage, billing state, analytics, and API-key metadata.
وهو خادم stdio محلي مدمج في الملف التنفيذي لـ CLI باسم sendhq. يشغّل عميل MCP لديك الأمر sendhq mcp بوصفه عملية فرعية ويتخاطب بـ JSON-RPC عبر stdin/stdout. وكل استدعاء أداة يتحول إلى طلب موثَّق واحد إلى SendHQ REST API على https://sendhq.cc/api/v1 بمصادقة مفتاح API الخاص بمساحة عملك، فتكون لخادم MCP صلاحيات ذلك المفتاح تمامًا ولا تزيد.
- 142 tools in 10 groups, generated from one catalog that is also published as tools.json.
- مخططات JSON Schema صارمة: تُرفض الوسائط غير المعروفة والأنواع الخاطئة والحقول المطلوبة المفقودة محليًا قبل أن يصل أي شيء إلى SendHQ.
- أخطاء منظَّمة تتضمن
codeثابتًا، وstatusبحالة HTTP، وexplanation، وremedyملموسًا، وما إذا كانت إعادة المحاولة قد تفيد. - كل أداة ترسل بريدًا حقيقيًا أو تتلف بيانات تنص على ذلك في أولى كلمات وصفها وتحمل توصيفات أمان MCP.
- يُخفي وضع
--read-onlyكل أداة إرسال وكل أداة تُغيّر الحالة. - لا يُسجَّل شيء. يحمل stdout رسائل البروتوكول فقط؛ ولا يصل مفتاح API ولا محتوى الرسائل إلى أي سجل.
https://sendhq.cc/api/mcp (بحث في الأسعار والتوثيق، دون وصول إلى الحساب). أما الخادم في هذه الصفحة فهو الكامل المرتبط بنطاق الحساب؛ ويعمل محليًا أو بوصفه الموصّل المستضاف أدناه.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، اختر Needs approval لتلك الأدوات ضمن Settings ← Connectors ← SendHQ.
- يحصل الموصّل على مفتاح API خاص به، يحمل اسم المساعد (مثل «Claude (AI connector)»). احذفه ضمن API Keys لقطع الاتصال فورًا.
- لا يستطيع إنشاء مفاتيح API أو إلغاءها ولا تغيير الفوترة. تُرسَل المرفقات وتُعاد بترميز base64؛ ولا يوجد وصول إلى الملفات المحلية.
- Sending requires an active subscription. There is no free allowance, including mail to the account owner.
للاستفسارات: postmaster@sendhq.cc. الخصوصية: sendhq.cc/privacy.
التثبيت
ثبّت الملف التنفيذي sendhq (Linux وmacOS وWindows على x86-64 وarm64). يتحقق المثبّت من المجموع الاختباري للإصدار ويضع الملف التنفيذي في ~/.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 المشترك، أشِر إلى المفتاح من البيئة بدل إيداعه في المستودع؛ إذ يوسّع 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 مستضاف للخادم المرتبط بنطاق الحساب. فنقطة نهاية MCP بعيدة وقادرة على الكتابة تتطلب OAuth لكل مستخدم، وهو ما لا تقدّمه SendHQ؛ ويُبقي الملف التنفيذي المحلي المفتاح على الجهاز الذي يحتفظ به أصلًا.
البيئة والخيارات
| المتغير أو الخيار | مطلوب | المعنى |
|---|---|---|
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 auth login في سلسلة مفاتيح نظام التشغيل بدل SENDHQ_API_KEY. ويتقدّم متغير البيئة عند وجود الاثنين. |
يُرسَل المفتاح فقط في الترويسة 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). - لا تبدّل إلى عنوان From مختلف للالتفاف على إيقاف
423، ولا تُعِد أبدًا إضافة مستلِمين ألغوا اشتراكهم أو قدّموا شكاوى.
مفاتيح 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 المعتمد وتُعيد المضيف النسبي الدقيق الذي تُدخله لكل سجل لدى ذلك المزوّد. - 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 وإشعارات الأحداث
Webhooks push signed events to an endpoint a human configures in the dashboard or with the REST API (see /docs/webhooks): email events (email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.failed, email.received), contact.unsubscribed when a recipient unsubscribes from a marketing or automation email, and, for automations, automation.entered, automation.converted, and automation.exited. There is no webhook tool, because endpoint responses carry signing secrets. An agent without a webhook polls instead: list_email_events for one message's outcome, list_emails with status (for example bounced) or after for recent changes, list_emails with direction: "in" and unread: true for new inbound mail, and list_blocked_recipients for new suppressions. Poll no more than about once a minute per question.
6. تشخيص إخفاق التسليم
- جد الرسالة:
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. امتلاك مجموعة مهام (التصنيفات)
- استخدم
create_labelمعname(مثلAgent/Orders) وskip_inbox: true. وهذا يحوّل التصنيف إلى مجموعة: يُؤرشَف البريد المستلَم الذي يحصل عليه، فيظهر داخل التصنيف فقط ولا يظهر أبدًا في صندوق وارد الإنسان. - أرسل بريد المهمة بـ
send_email(أوsend_batch) معlabels: ["Agent/Orders"]. وترث الردود على تلك المحادثة التصنيف تلقائيًا وتتخطى صندوق الوارد. - للبريد الذي يبدأ خارج محادثاتك، أضف قاعدة فرز:
create_label_ruleمعinbox_id(عنوان مخصص مثلorders@…) أوfromأوtoأوsubject. ومرّرapply_to_existing: trueلفرز البريد المستلَم أصلًا. - اعمل على المجموعة:
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). وإضافة تصنيف مجموعة إلى رسالة مستلَمة تؤرشفها أيضًا. - اختياريًا، ترسل
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_…"
}
}
}10. Run an automation
An automation is a timed sequence of emails that starts when a contact does something and stops when they convert. Automations are being enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled from every tool below.
create_automationwith akey, theentryevent,exit_rules(thegoal_eventthat counts as converting, orno_goal: true), a verifiedfrom_address, andsteps, each dueoffset_secondsafter the person entered. It starts as a draft and sends nothing. Every automation carriesdomain, the domain of itsfrom_address; in a workspace that sends from several domains,list_automationsandget_automations_overviewtakedomainto show the automations of one of them.- To let the user read it first:
send_automation_test_emailsends one email, andsend_automation_testevery email in order, to the account's own address only (never to a contact), with stand-in values for the merge tags. A test enrols nobody, is in no report, and works while the automation is still a draft. Both send real email, so only when the user asks.send_automation_test_emailwithdry_run: truereturns the rendered email without sending anything. get_sending_limitsshows how much automation email one person may get across every automation, and during which hours. Change them withupdate_sending_limitsonly when the user asks.- To start from a ready-made email instead of writing one:
list_automation_templatesis the template library (welcome, onboarding tips, a nudge to finish setup, trial ending and trial ended, abandoned checkout, failed payment or dunning, receipt, upgrade at a usage limit, feature announcement, review request, feedback score, cancellation survey, and winback for retention),get_automation_templateshows one with the email as this workspace would send it, anduse_automation_templatemakes the draft automation with the emails, the suggested entry event and the suggested goal. Some templates come as a set that makes one automation: three onboarding tips, trial ending then trial ended, payment failed then a last notice.set_automation_stepwithtemplateloads one template into an email of an automation that already exists. - An email can also be built in the dashboard's drag-and-drop builder.
get_automationshows such an email witheditordesign: itscontentis the builder's project, which only the builder writes, and itshtmlis what is sent. Leave the project alone. To change the wording of a designed email, ask the user to open it in the dashboard; to replace it, send your ownhtmlwitheditorhtml. - A template is finished except for what only the user knows, written as placeholders in square brackets:
[First step], or[Link to plans]as a link's address.to_fillon the automation lists each one by email, and each workspace name the emails print that is blank. Ask the user for the real words and links, write them in withset_automation_step, and setproduct_nameandsender_namewithupdate_sending_limits. Never invent them.set_automation_statusrefuses to turn the automation on while anything is left (422automation_not_ready, with aproblemslist that names each email and detail); test emails are allowed, so the user can read it first. - Only when the user says to start:
set_automation_statuswithstatus: "on". - Record what people do with
track_event(a new contact needscontact.consent_basis). The entry event starts the sequence, the goal event ends it as converted, and adedupe_keymakes a retry harmless.enroll_contactandexit_contactadd or remove one person by hand. preview_automationshows, for everyone in the automation now, which email would go out if they were evaluated at this moment, or why not: nothing due until a time, held by a limit or the sending hours until a time, waiting behind a higher-priority automation, or skipped. It sends nothing and changes nothing.list_automationsgives each automation's 30-day totals. An email that a limit holds back is not dropped: it goes out when the limit allows. When several emails of one automation are due at once, only the latest is sent.- Results:
get_automations_overview(every automation) andget_automation_report(one automation, with a row per email) give totals and a number for each day of a date range: people who entered, emails sent, delivered, opened, clicked, and converted.list_automation_peoplelists who did what (did: entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, or waiting), andget_automation_persongives one contact's history with every open and click. Automation emails are tracked like broadcasts: report opens and clicks as estimates, and note that automated requests are labelledmachineand never counted.
{
"name": "use_automation_template",
"arguments": {
"template_id": "payment-failed-notices",
"from_name": "Dana from Acme",
"from_address": "dana@example.com"
}
}{
"name": "preview_automation",
"arguments": {
"automation_key": "checkout-recovery"
}
}{
"name": "list_automation_people",
"arguments": {
"automation_key": "checkout-recovery",
"did": "clicked",
"step": 1
}
}11. See what came in, and connect another system
Events reach SendHQ three ways: track_event from the workspace's own code, a connection (a secret address a payment provider or another system posts its webhooks to), and a spreadsheet uploaded in the dashboard. See /docs/events.
list_eventsis the feed of everything recorded, newest first: who, what they did (also as plain words), when, where it came from, and which automations it started, ended, or converted. Filter bycontact, byname, or by date.list_event_nameslists the kinds of event seen in the last 30 days.list_connectionsshows each connection with its last delivery in plain words, andget_connectionits last 50 deliveries: "Recorded 2 events", "Skipped: no email address", "Refused: bad signature". Start there when something a provider sent did not show up.- Only when the user asks to connect a system:
create_connectionwithkindstripeordodo(mapped for you) orgenericwith amapping. It returns the secretaddressonce; give it to the user to paste into that system. From then on what arrives is recorded without anyone looking, and can start automations that send email. update_connectionwithenabled: falsepauses a connection (its address answers 404);delete_connectionremoves it. The provider's signing secret and a replacement address are set by a person in the dashboard.
{
"name": "list_events",
"arguments": {
"contact": "ada@example.net"
}
}12. Check an email's content before it is sent
score_email reads a subject, the HTML and the plain text as they were written and returns a score from 0 to 100 with what to change, most points first. A plain email with no links and no images scores 100; a designed layout, links to another site than the sender's, link shorteners, images with few words, hidden text, capitals and very long HTML each take points off. Pass from so links can be compared with the sender's own domain. Nothing is stored or sent, and the footer and tracking SendHQ adds are not scored. The dashboard's email editor shows the same number for the same content. It looks at content only, so use it as a checklist: sender reputation, authentication and how recipients react decide more of where mail lands.
{
"name": "score_email",
"arguments": {
"from": "hello@example.com",
"subject": "Your cart is still here",
"html": "<p>Pick up where you left off.</p><p><a href=\"https://bit.ly/3xyz\">Finish checkout</a></p>"
}
}النتائج والترقيم والأخطاء
يُعيد الاستدعاء الناجح كائن JSON الخاص بـ API بوصفه structuredContent وككتلة نصية JSON. وتقبل كل أداة list_* المعلمة limit (من 1 إلى 200، والافتراضي 50) وoffset، وتضيف كائن pagination. واصل الاستدعاء بـ offset: pagination.next_offset ما دامت has_more مساوية لـ true.
{
"data": [
"…"
],
"count": 50,
"pagination": {
"offset": 0,
"limit": 50,
"returned": 50,
"total": 180,
"has_more": true,
"next_offset": 50
}
}يُعيد الاستدعاء الفاشل isError: true مع خطأ منظَّم. اتبع remedy بدل إعادة المحاولة عشوائيًا؛ ولا تعد المحاولة إلا عندما تكون retryable مساوية لـ true.
{
"error": {
"code": "subscription_required",
"status": 402,
"message": "Sending requires an active SendHQ subscription. Choose a plan to start sending.",
"retryable": false,
"explanation": "This workspace has no active paid subscription. SendHQ does not send any email, including to the account owner, until a plan is active.",
"remedy": "Ask the account owner to choose a plan at https://sendhq.cc/pricing or in the dashboard (Profile & Billing). Do not retry until the subscription is active."
}
}حقول الخطأ الاختيارية: request_id (اذكره للدعم)، وretry_after_seconds، وproblems (قائمة بمخالفات المخطط لـ invalid_arguments)، وidempotent_replayed (انظر عدم التكرار).
عدم التكرار (Idempotency)
تقبل send_email وsend_batch المعلمة idempotency_key (200 حرف كحد أقصى)، وتُرسَل بوصفها الترويسة Idempotency-Key. ولّد مفتاحًا ثابتًا واحدًا لكل رسالة منطقية، مثل invoice-4812-receipt.
- يجب أن تعيد المحاولة استخدام المفتاح نفسه مع جسم طلب مطابق. المفتاح نفسه مع أي تغيير (المستلِم أو الموضوع أو النص أو الترويسة أو بيانات القالب، وحتى قيم الوسائط) يُعيد
409 idempotency_conflict. - المفتاح نفسه والجسم نفسه وانتهاء الطلب الأصلي: تُعيد SendHQ النتيجة المخزَّنة دون إرسال مجددًا. بهذه الطريقة تعيد المحاولة بأمان بعد انتهاء المهلة أو
network_error. - المفتاح نفسه بينما الطلب الأصلي لا يزال قيد التنفيذ:
409 idempotency_in_progress، ويمكن إعادة المحاولة بعد انتظار قصير. - الرسالة المنطقية الجديدة تحتاج إلى مفتاح جديد.
- تُعاد الإخفاقات المخزَّنة كذلك. فإذا أخفقت المحاولة الأولى، فإن إعادة المحاولة بالمفتاح نفسه تُعيد الإخفاق نفسه مع
idempotent_replayed: trueوretryable: false. افحصlist_emails(direction: out) للتأكد من أن شيئًا لم يُرسَل، وأصلح السبب، ثم أرسل بمفتاح جديد. - لا يعيد الخادم محاولة POST من تلقاء نفسه أبدًا. تُعاد استدعاءات GET للقراءة فقط تلقائيًا (حتى 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 رسالة. - قاطع دائرة السمعة (circuit breaker): في نافذة متجددة مدتها 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 | لا | الفئة التسويقية غير مفعّلة لهذا النطاق أو هذه الباقة. لا تستخدم 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 هذا موقوف مؤقتًا بواسطة قاطع الدائرة الخاص بارتدادات وشكاوى الأيام السبعة. توقف، وأصلح القائمة، وانتظر التعافي التلقائي. |
account_paused | 423 | لا | Workspace paused for a deliverability review. The body has the measured rate and the limit when the pause was for bounces or complaints. Do not send until it is restored. |
quota_exhausted | 429 | لا | Monthly allowance, per-sender daily limit, or attachment transfer. Not the workspace daily ladder. Check get_account; wait for that limit to reset or upgrade. |
daily_limit_reached | 429 | after reset | Workspace daily ladder. Not a short backoff. Wait until resets_at (midnight UTC). The message was not queued. |
hourly_limit_reached | 429 | after reset | Hourly pace (about a tenth of the day's cap). Wait until the next UTC hour. Not a short backoff. |
gmail_recipient_limit | 429 | after reset | 500 Gmail recipients a day for a sending domain under 30 days old, on any ladder rung. Wait until midnight UTC. Not queued. |
gmail_rate_limited | 429 | after reset | Gmail returned 4.7.28 for this domain. Wait until resets_at. Other providers keep sending. |
rate_limited | 429 | نعم | Slow down; wait retry_after_seconds. This is not a daily, hourly, or Gmail cap. |
server_error | 5xx | نعم | إخفاق مؤقت في SendHQ أو لدى المزوّد. تراجع وأعد المحاولة؛ وفي الإرسال بالمفتاح والجسم نفسيهما. وإذا كانت idempotent_replayed مساوية لـ true، فاستخدم مفتاحًا جديدًا بعد التأكد من أن شيئًا لم يُرسَل. |
network_error | — | نعم | فُقد الطلب أو الاستجابة. أعد المحاولة؛ وفي الإرسال يجعل idempotency_key نفسه ذلك آمنًا. |
invalid_request | 400 | لا | طلب مشوَّه. اقرأ message وصحّحه. |
tool_error | — | لا | إخفاق محلي داخل خادم MCP (مثل file_path غير قابل للقراءة). اقرأ message. |
مرجع الأدوات
كل أداة مع فئة الأمان الخاصة بها ونقطة نهاية REST التي تستدعيها ومعلماتها وشكل القيمة المُعادة ومثال على كائن معلمات tools/call. المعلمات دقيقة: يرفض الخادم أي شيء غير مدرج.
Emails and threads: send_email, send_batch, list_emails, get_email, mark_email, delete_email, list_email_events, get_thread, email_delivery, thread_delivery
Labels and auto-filing rules: list_labels, get_label, create_label, update_label, delete_label, create_label_rule, delete_label_rule, label_email
Drafts, attachments, and sender identities: list_sending_identities, create_draft, list_drafts, get_draft, update_draft, delete_draft, upload_attachment, download_attachment, delete_attachment
Hosted templates: list_templates, create_template, get_template, update_template_draft, create_template_draft, render_template, send_template_test, publish_template, archive_template, restore_template
Domains and DNS: list_domains, get_domain, add_domain, verify_domain, delete_domain, get_dns_provider, get_domain_connect_link
Inbound email: setup_inbound, verify_inbound, list_inboxes, get_inbox, create_inbox, update_inbox, set_inbox_forwarding, delete_inbox
Deliverability, bounces, and suppressions: deliverability_stats, deliverability_account, deliverability_domains, deliverability_senders, score_email, list_sender_reputation, list_suppressions, remove_suppression, list_blocked_recipients
Campaigns: list_contacts, create_contact, upsert_contact, get_contact, update_contact, delete_contact, import_contacts, list_contact_imports, bulk_update_contacts, list_tags, list_contact_fields, set_contact_field, delete_contact_field, list_segments, get_segment, preview_segment, create_segment, update_segment, delete_segment, list_lists, create_list, get_list, update_list, delete_list, add_list_contacts, remove_list_contact, list_broadcasts, create_broadcast, get_broadcast, update_broadcast, delete_broadcast, send_broadcast, cancel_broadcast, list_broadcast_recipients, check_broadcast, send_broadcast_test, schedule_broadcast, unschedule_broadcast, duplicate_broadcast, send_broadcast_to_more, get_broadcast_report, get_newsletter_settings, update_newsletter_settings, get_campaign_overview, list_uploaded_images
Automations, events, and sending limits: track_event, list_automations, get_automation, create_automation, update_automation, delete_automation, set_automation_step, delete_automation_step, set_automation_step_variant, set_automation_status, send_automation_test_email, send_automation_test, enroll_contact, exit_contact, preview_automation, get_automations_overview, get_automation_report, list_automation_people, get_automation_person, get_sending_limits, update_sending_limits, list_automation_templates, get_automation_template, use_automation_template, list_events, list_event_names, list_connections, get_connection, create_connection, update_connection, delete_connection
Account, usage, analytics, and keys: get_account, get_account_diagnostics, get_analytics, list_api_keys, get_service_health
لا توجد أدوات تطابق عامل التصفية هذا.
الرسائل وسلاسل الرسائل
send_emailإرسال رسالة واحدة
SENDS REAL EMAIL. Send one message from a verified domain: raw html/text, a published hosted template, a reply in an existing thread, or a message with attachments. Pass idempotency_key so a retry cannot send twice; a retry must reuse the same key AND an identical request, otherwise SendHQ returns 409. attachments is a convenience that creates a draft, uploads each file, and sends with that draft; it cannot be combined with idempotency_key or draft_id (use create_draft + upload_attachment + send_email with draft_id for retry-safe attachment sends). Unpaid workspaces (integration trial) can deliver only to the account email or a mailbox-simulator test address, and cannot send attachments.
قدّم واحدًا على الأقل من: html أو text أو template.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
from | string | نعم | المُرسِل، مثل Acme <hello@example.com>. يجب أن يكون النطاق موثَّقًا في مساحة العمل هذه (راجع list_sending_identities). (حتى 998 حرفًا) |
to | string[] | نعم | المستلِمون. كل عنصر عنوان، مع اسم عرض اختياري. يمكن أن يبلغ مجموع to وcc وbcc 100 على الأكثر؛ وتستهلك كل وجهة رصيد تسليم واحدًا. (من 1 إلى 100 عنصر) |
cc | string[] | لا | مستلِمو النسخة الكربونية. (من 0 إلى 100 عنصر) |
bcc | string[] | لا | مستلِمو النسخة المخفية. (من 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_… لحفظ هذه الرسالة تحتها. تُنشأ الأسماء غير المعروفة. وترث الردود في المحادثة التصنيفات، ويُبقي تصنيف المجموعة (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 لتحويله إلى مجموعة يملكها الوكيل: أرسل بـ labels: [name] فتُفرز الردود إلى التصنيف وتبقى خارج صندوق الوارد. وتفرز قواعد الفرز التلقائي الاختيارية البريد المرسل/المستلَم الجديد (يجب أن تتحقق كل الشروط في القاعدة). واضبط apply_to_existing لفرز البريد المحفوظ أيضًا.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
name | string | نعم | اسم التصنيف، مثل Billing أو Clients/Acme. فريد لكل مساحة عمل (دون مراعاة حالة الأحرف). (حتى 64 حرفًا) |
color | string | لا | لون بصيغة hex مثل #1a73e8. اختياري. |
skip_inbox | boolean | لا | وضع المجموعة: يُؤرشَف البريد المستلَم الذي يحصل على هذا التصنيف (بقاعدة، أو بالرد على محادثة أُرسلت بهذا التصنيف، أو يدويًا) فيظهر داخل التصنيف فقط وليس في صندوق الوارد. |
rules | object[] | لا | قواعد فرز تلقائي اختيارية (20 كحد أقصى). تحتاج كل قاعدة إلى واحد على الأقل من inbox_id أو from أو to أو subject. (من 0 إلى 20 عنصرًا) |
rules[].direction | string | لا | البريد in (المستلَم) أو out (المرسَل) فقط. احذفها للاثنين معًا. (إحدى القيم in أو out) |
rules[].inbox_id | string | لا | البريد الذي استلمه صندوق البريد هذا فقط (inb_…). يفرز كل عنوان استقبال في مجلده الخاص. |
rules[].from | string | لا | المُرسِل يحتوي على هذا النص (دون مراعاة حالة الأحرف)، مثل @stripe.com. (حتى 200 حرف) |
rules[].to | string | لا | To/Cc يحتوي على هذا النص (دون مراعاة حالة الأحرف). (حتى 200 حرف) |
rules[].subject | string | لا | الموضوع يحتوي على هذا النص (دون مراعاة حالة الأحرف). (حتى 200 حرف) |
rules[].skip_inbox | boolean | لا | أرشفة البريد المستلَم المطابق ليظهر داخل مجلد التصنيف فقط وليس في صندوق الوارد. |
apply_to_existing | boolean | لا | فرز البريد المحفوظ أصلًا الذي يطابق القواعد أيضًا. |
{
"name": "create_label",
"arguments": {
"name": "Agent/Orders",
"skip_inbox": true,
"rules": [
{
"from": "@stripe.com"
}
]
}
}update_labelإعادة تسمية تصنيف أو تغيير لونه أو تحويله إلى مجموعة
أعد تسمية تصنيف أو غيّر لونه أو بدّل وضع المجموعة (skip_inbox). يؤدي تفعيل وضع المجموعة إلى أرشفة البريد المستلَم الموجود أصلًا في التصنيف.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
label_id | string | نعم | معرّف التصنيف (يبدأ بـ lbl_) أو اسم التصنيف المطابق تمامًا. (حتى 128 حرفًا) |
name | string | لا | الاسم الجديد. (حتى 64 حرفًا) |
color | string | لا | لون hex الجديد. |
skip_inbox | boolean | لا | وضع المجموعة: يُؤرشَف البريد المستلَم الذي يحصل على هذا التصنيف (بقاعدة، أو بالرد على محادثة أُرسلت بهذا التصنيف، أو يدويًا) فيظهر داخل التصنيف فقط وليس في صندوق الوارد. |
{
"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[] | لا | مستلِمو النسخة الكربونية. (من 0 إلى 100 عنصر) |
bcc | string[] | لا | مستلِمو النسخة المخفية. (من 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[] | لا | مستلِمو النسخة الكربونية. (من 0 إلى 100 عنصر) |
bcc | string[] | لا | مستلِمو النسخة المخفية. (من 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 أن شخصًا آخر حفظ أولًا؛ فأعد القراءة وأعد المحاولة). وهذا استبدال كامل لمحتوى المسودة: تُمسح الحقول المحذوفة، فأرسل كل حقل تريد الاحتفاظ به. استخدم العناصر النائبة {{variable}}.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
template_id | string | نعم | معرّف القالب أو مفتاحه. (حتى 128 حرفًا) |
revision | integer | نعم | مراجعة المسودة الحالية من get_template. (من 1 فصاعدًا) |
name | string | لا | اسم القالب. (حتى 120 حرفًا) |
subject_template | string | لا | الموضوع مع عناصر نائبة. (حتى 998 حرفًا) |
preheader_template | string | لا | نص المعاينة. (حتى 240 حرفًا) |
html_template | string | لا | نص HTML مع عناصر نائبة. |
text_template | string | لا | النص العادي مع عناصر نائبة. |
from | string | لا | المُرسِل الافتراضي لعمليات إرسال هذا القالب. |
reply_to | string | لا | Reply-To الافتراضي. |
variables | object[] | لا | عقد المتغيّرات المُنمَّطة. كل عنصر: {key (أحرف صغيرة/شرطات سفلية), label, type: text|number|url|boolean, required (الافتراضي true), fallback, description}. |
variables[].key | string | نعم | |
variables[].label | string | لا | |
variables[].type | string | لا | (إحدى القيم text أو number أو url أو boolean) |
variables[].required | boolean | لا | |
variables[].fallback | any | لا | |
variables[].description | string | لا | |
sample_data | object | لا | قيم عيّنة تُستخدم في المعاينات والاختبارات. |
{
"name": "update_template_draft",
"arguments": {
"template_id": "account-welcome",
"revision": 3,
"name": "Account welcome",
"subject_template": "Welcome, {{first_name}}",
"text_template": "Hi {{first_name}}",
"variables": [
{
"key": "first_name",
"type": "text",
"required": true
}
],
"sample_data": {
"first_name": "Asha"
}
}
}create_template_draftبدء مسودة جديدة من الإصدار المنشور
أنشئ مسودة جديدة قابلة للتعديل منسوخة من الإصدار المنشور الحالي (409 إذا كانت هناك مسودة قائمة أو لم يُنشر شيء).
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
template_id | string | نعم | معرّف القالب أو مفتاحه. (حتى 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 عند أخطاء التحقق، أو 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 الدقيقة المطلوب نشرها (النوع والاسم والقيمة)، والحالة الحية لكل سجل من محلّلَي DNS عامّين، و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 ومضيفات السجلات
اكتشف مزوّد DNS المعتمد للنطاق وأعِد المضيف النسبي الذي تكتبه لدى ذلك المزوّد لكل سجل، وسجل 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 الوارد. تصبح الحالة ready عندما يراه محلّلا DNS العامّان كلاهما.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
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 مع الاتجاه 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
}
}score_emailScore an email's content
A checklist of one email's content before it is sent: 100 for a plain email with no links and no images, lower for each thing mail filters look at (a designed layout, links to another site than the sender's, link shorteners, images with few words, hidden text, capitals, an empty subject, very long HTML). Returns each finding with the points it costs and a one-line suggestion, most points first. Read-only: nothing is stored or sent. Pass the email as written; the unsubscribe footer and tracking SendHQ adds are not scored. It looks at content only: sender reputation, authentication and how recipients react decide more of where mail lands, so treat it as a checklist, not a prediction.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
subject | string | لا | The subject line. |
html | string | لا | The HTML as written, before SendHQ adds its footer or tracking. (max 2000000 chars) |
text | string | لا | The plain-text part. Compared with the HTML when both are given; scored on its own when there is no HTML. (max 2000000 chars) |
from | string | لا | The sender: an email address or a domain such as example.com. Without it, links to other sites are not judged. (max 320 chars) |
{
"name": "score_email",
"arguments": {
"from": "hello@example.com",
"subject": "Your cart is still here",
"html": "<p>Pick up where you left off.</p><p><a href=\"https://bit.ly/3xyz\">Finish checkout</a></p>"
}
}list_sender_reputationعرض سمعة المُرسِل
حالة السمعة لكل عنوان From بعينه: active أو throttled (حد يومي أقل) أو paused (تُعيد عمليات الإرسال 423)، مع السبب والحد اليومي. افحصها عندما تخفق عمليات الإرسال بالرمز 423 أو 429. مقسَّمة إلى صفحات: تتضمن النتيجة pagination {offset, limit, returned, total?, has_more, next_offset}.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_sender_reputation",
"arguments": {}
}list_suppressionsعرض عناصر المنع
قائمة المنع في مساحة العمل: المستلِمون المحظورون بعد ارتداد دائم أو شكوى بريد مزعج. تخفق عمليات الإرسال إليهم بالرمز 422. مقسَّمة إلى صفحات: تتضمن النتيجة pagination {offset, limit, returned, total?, has_more, next_offset}.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_suppressions",
"arguments": {}
}remove_suppressionإزالة عنصر منع ناتج عن ارتداد
DESTRUCTIVE (يُضعف حاجز أمان): أزل عنصر منع ناتجًا عن ارتداد ليصبح بالإمكان مراسلة العنوان مجددًا. لا تفعل ذلك إلا عندما يؤكد الإنسان أن العنوان صار صالحًا. لا يمكن إزالة عناصر المنع الناتجة عن الشكاوى (409).
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
email | string | نعم | عنوان المستلِم المدرج في قائمة المنع. (حتى 320 حرفًا) |
{
"name": "remove_suppression",
"arguments": {
"email": "fixed-mailbox@example.net"
}
}list_blocked_recipientsعرض المستلِمين المحظورين
كل مستلِم سترفضه SendHQ: الارتدادات والشكاوى وعمليات إلغاء الاشتراك التسويقية على مستوى النطاق، مع ملخص حسب النوع. تقرأ حتى أحدث 500. مقسَّمة إلى صفحات: تتضمن النتيجة pagination {offset, limit, returned, total?, has_more, next_offset}.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_blocked_recipients",
"arguments": {}
}Campaigns
list_contactsList contacts
Campaigns: Newest-first contacts with their status, consent evidence, tags, custom fields, engagement (bot-filtered, estimated opens and clicks), and the lists they are subscribed to. Filter by list, status (including dormant), email/name substring (* is an email wildcard, e.g. *@example.com), tag, source, signup date, or a saved segment. Paginated: the result includes pagination {offset, limit, returned, has_more, next_offset}.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
list_id | string | لا | Only members of this list (lst_…). |
status | string | لا | Only contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant) |
query | string | لا | Email or name contains this text; * is a wildcard on the email. (max 200 chars) |
tag | string | لا | Only contacts with this tag. (max 60 chars) |
source | string | لا | How the contact was added. (one of form, api, import) |
after | string | لا | Signed up at or after this time. ISO 8601 date or date-time. (max 40 chars) |
before | string | لا | Signed up before this time. ISO 8601 date or date-time. (max 40 chars) |
segment_id | string | لا | Only contacts matching this saved segment (seg_…). |
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_contacts",
"arguments": {
"status": "subscribed"
}
}create_contactAdd a contact
Campaigns: Add one contact to the workspace, optionally to lists and with tags. A subscribed contact (the default) needs consent_basis: how this person agreed to receive your email. Only add people who asked for your email. Use status: unsubscribed to record an opt-out. Addresses already suppressed or unsubscribed from the workspace are stored with that status. Fails with 409 if the email already exists.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
email | string | نعم | Email address. (max 320 chars) |
name | string | لا | Display name; the first word is {{first_name}}. (max 200 chars) |
fields | object | لا | Custom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field. |
tags | string[] | لا | Tags to attach, e.g. ["VIP"]. Up to 50. (0–50 items) |
list_ids | string[] | لا | Lists to add the contact to (lst_…). (0–100 items) |
status | string | لا | subscribed (default, requires consent_basis) or unsubscribed. (one of subscribed, unsubscribed) |
consent_basis | string | لا | How these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars) |
{
"name": "create_contact",
"arguments": {
"email": "ada@example.net",
"name": "Ada Lovelace",
"consent_basis": "Ticked the newsletter box at checkout on acme.com"
}
}upsert_contactCreate or update a contact by email
Campaigns: Create the contact with this email, or change the one that exists: set name, timezone, and locale, merge fields, and add tags. A new contact needs consent_basis and takes the status its address already has (bounced or complained when suppressed, unsubscribed when it opted out, otherwise subscribed). An existing contact's status is never changed, so nobody is resubscribed. Unlike create_contact it does not fail when the email exists. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
email | string | نعم | Email address. (max 320 chars) |
name | string | لا | Display name; the first word is {{first_name}}. (max 200 chars) |
fields | object | لا | Custom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field. |
tags | string[] | لا | Tags to add, e.g. ["VIP"]. Existing tags are kept. (0–50 items) |
timezone | string | لا | IANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars) |
locale | string | لا | Language tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars) |
consent_basis | string | لا | How this person agreed to receive your email, e.g. Created an account on acme.com and accepted product emails. Required when the email is not a contact yet. 10-500 characters. (max 500 chars) |
{
"name": "upsert_contact",
"arguments": {
"email": "ada@example.net",
"name": "Ada Lovelace",
"fields": {
"plan": "pro"
},
"timezone": "Europe/London",
"consent_basis": "Created an account on acme.com and accepted product emails"
}
}get_contactGet a contact
Campaigns: One contact by ID or email: status, consent evidence (source, basis, opt-in and confirmation times), custom fields, and subscribed lists.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
contact_id | string | نعم | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "get_contact",
"arguments": {
"contact_id": "ct_123"
}
}update_contactUpdate, tag, or unsubscribe a contact
Campaigns: Change a contact's name, merge custom fields (null removes one), change tags (tags replaces the whole set; add_tags and remove_tags change it), or set status to unsubscribed. A contact can never be resubscribed through the API; only the recipient can, by confirming a signup form.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
contact_id | string | نعم | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
name | string | لا | New display name. (max 200 chars) |
fields | object | لا | Custom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field. |
tags | string[] | لا | Replace all of the contact's tags with these. (0–50 items) |
add_tags | string[] | لا | Tags to add. (0–50 items) |
remove_tags | string[] | لا | Tags to remove. (0–50 items) |
status | string | لا | Only unsubscribed is accepted. (one of unsubscribed) |
{
"name": "update_contact",
"arguments": {
"contact_id": "ct_123",
"fields": {
"plan": "team"
}
}
}delete_contactDelete a contact
DESTRUCTIVE: permanently delete a contact and its list memberships. Suppressions and recorded unsubscribes are kept, so the address still cannot be mailed if it is added again. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
contact_id | string | نعم | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "delete_contact",
"arguments": {
"contact_id": "ct_123"
}
}import_contactsImport contacts from CSV
Campaigns: Import up to 5,000 CSV rows (5 MB) per call, optionally into a list. The header row needs an email column; name (or first_name/last_name), status, and tags (separated by ; or |) are recognized and other columns become custom fields. consent_basis is required and recorded on every new contact. tags are added to every accepted row. Rows whose status says unsubscribed import as unsubscribed; existing contacts keep their status. Returns counts of accepted, created, existing, skipped (duplicates), and invalid rows with line numbers.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
csv | string | نعم | The CSV file content, header row first. (max 5242880 chars) |
list_id | string | لا | Add every accepted row to this list (lst_…). |
consent_basis | string | نعم | How these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars) |
tags | string[] | لا | Tags to add to every accepted row, e.g. ["imported-2026-11"]. (0–50 items) |
update_existing | boolean | لا | Merge names and fields into contacts that already exist. Their status never changes. |
{
"name": "import_contacts",
"arguments": {
"csv": "email,name\nada@example.net,Ada Lovelace\n",
"consent_basis": "Newsletter signups exported from Mailchimp (double opt-in)"
}
}list_contact_importsList contact imports
Campaigns: Recent CSV imports with their consent basis and row counts.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_contact_imports",
"arguments": {}
}bulk_update_contactsBulk update contacts
DESTRUCTIVE when action is delete (permanent) or unsubscribe (cannot be undone through the API). Apply one action to up to 10,000 contacts: the IDs in contact_ids, or everyone matching filter (the list_contacts filters). Actions: tag / untag (with tags), add_to_list / remove_from_list (with list_id), unsubscribe, delete. Adding to a list mirrors each contact's status, so nobody is resubscribed. delete needs confirm_count equal to the number of contacts it would delete: call once without it to get that count (409), confirm with the user, then repeat with it. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
action | string | نعم | What to do. (one of tag, untag, add_to_list, remove_from_list, unsubscribe, delete) |
contact_ids | string[] | لا | Contact IDs (ct_…). Use this or filter. (0–10000 items) |
filter | object | لا | Everyone matching these list_contacts filters. Use this or contact_ids. |
filter.list_id | string | لا | Members of this list. |
filter.status | string | لا | Only contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant) |
filter.query | string | لا | Email or name contains; * is an email wildcard. (max 200 chars) |
filter.tag | string | لا | Has this tag. (max 60 chars) |
filter.source | string | لا | How the contact was added. (one of form, api, import) |
filter.after | string | لا | Signed up at or after. ISO 8601 date or date-time. (max 40 chars) |
filter.before | string | لا | Signed up before. ISO 8601 date or date-time. (max 40 chars) |
filter.segment_id | string | لا | Matches this segment. |
tags | string[] | لا | For tag and untag. (0–50 items) |
list_id | string | لا | For add_to_list and remove_from_list (lst_…). |
confirm_count | integer | لا | For delete: the number of contacts that will be deleted, from the 409 response. (0–…) |
{
"name": "bulk_update_contacts",
"arguments": {
"action": "tag",
"tags": [
"october"
],
"filter": {
"list_id": "lst_123",
"status": "subscribed"
}
}
}list_tagsList contact tags
Campaigns: The workspace's contact tags, most used first, with how many contacts carry each (up to 500). Paginated.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_tags",
"arguments": {}
}list_contact_fieldsList custom contact fields
Campaigns: Defined custom contact fields with label and type (text, number, date). Defined fields are known to check_broadcast's merge-tag check and typed in segment conditions. Contacts may also carry undefined keys. Paginated.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_contact_fields",
"arguments": {}
}set_contact_fieldDefine a custom contact field
Campaigns: Create or change a custom field definition (label and type). Values live on each contact's fields. Built-in merge tags (email, name, first_name, last_name, fields, unsubscribe_url) cannot be used as keys. A workspace may define 50 fields.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
field_key | string | نعم | Field key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars) |
label | string | لا | Label shown in the dashboard. Defaults to the key. (max 80 chars) |
type | string | لا | text (default), number, or date. (one of text, number, date) |
{
"name": "set_contact_field",
"arguments": {
"field_key": "plan",
"label": "Plan",
"type": "text"
}
}delete_contact_fieldDelete a custom field definition
DESTRUCTIVE: delete a custom field definition. Values already stored on contacts are kept. Fails with 404 when the field is not defined. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
field_key | string | نعم | Field key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars) |
{
"name": "delete_contact_field",
"arguments": {
"field_key": "plan"
}
}list_segmentsList segments
Campaigns: Saved segments with count (subscribed, non-dormant contacts in the workspace that match now) and fields, the condition fields and operators each accepts. Paginated.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_segments",
"arguments": {}
}get_segmentGet a segment
Campaigns: One segment with its conditions and live count.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
segment_id | string | نعم | Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars) |
{
"name": "get_segment",
"arguments": {
"segment_id": "seg_123"
}
}preview_segmentPreview segment conditions
Campaigns: Count and sample (up to 5) the subscribed, non-dormant contacts that match conditions without saving them. Read-only; use it to check conditions before create_segment.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
match | string | لا | all (default): every condition must match. any: at least one. (one of all, any) |
conditions | object[] | لا | Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items) |
conditions[].field | string | نعم | tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars) |
conditions[].key | string | لا | Custom field key when field is field. (max 40 chars) |
conditions[].op | string | نعم | tag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt) |
conditions[].value | string,number | لا | Required except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after. |
{
"name": "preview_segment",
"arguments": {
"match": "all",
"conditions": [
{
"field": "tag",
"op": "has",
"value": "VIP"
},
{
"field": "opened",
"op": "in_last_days",
"value": 90
}
]
}
}create_segmentCreate a segment
Campaigns: Save a segment: up to 20 conditions joined by match. Use it as a broadcast's audience.segment_id, as list_contacts segment_id, or in bulk_update_contacts filters. A workspace may have 200 segments.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
name | string | نعم | Segment name. (max 120 chars) |
match | string | لا | all (default): every condition must match. any: at least one. (one of all, any) |
conditions | object[] | لا | Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items) |
conditions[].field | string | نعم | tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars) |
conditions[].key | string | لا | Custom field key when field is field. (max 40 chars) |
conditions[].op | string | نعم | tag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt) |
conditions[].value | string,number | لا | Required except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after. |
{
"name": "create_segment",
"arguments": {
"name": "Engaged pro customers",
"conditions": [
{
"field": "fields.plan",
"op": "equals",
"value": "pro"
},
{
"field": "opened",
"op": "in_last_days",
"value": 90
}
]
}
}update_segmentUpdate a segment
Campaigns: Rename a segment or change match or conditions (which replaces the whole list). Broadcasts using it pick up the change when they start sending.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
segment_id | string | نعم | Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars) |
name | string | لا | Segment name. (max 120 chars) |
match | string | لا | all (default): every condition must match. any: at least one. (one of all, any) |
conditions | object[] | لا | Up to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items) |
conditions[].field | string | نعم | tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars) |
conditions[].key | string | لا | Custom field key when field is field. (max 40 chars) |
conditions[].op | string | نعم | tag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt) |
conditions[].value | string,number | لا | Required except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after. |
{
"name": "update_segment",
"arguments": {
"segment_id": "seg_123",
"name": "Pro customers"
}
}delete_segmentDelete a segment
DESTRUCTIVE: delete a saved segment. Contacts are not affected. Fails with 409 while a sending or scheduled broadcast uses it. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
segment_id | string | نعم | Segment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars) |
{
"name": "delete_segment",
"arguments": {
"segment_id": "seg_123"
}
}list_listsList contact lists
Campaigns: Contact lists with subscribed, pending, and unsubscribed counts and their hosted signup form settings.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_lists",
"arguments": {}
}create_listCreate a list
Campaigns: Create a contact list. Set form_enabled to publish a hosted double opt-in signup form (its URL is in form.url); form_from is the sender, on a verified domain, of the confirmation email, and redirect_url is an optional https page shown after confirming. welcome sends one welcome email when someone confirms. site publishes a public newsletter site at https://sendhq.cc/n/<slug> with the signup form, sent issues, and RSS.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
name | string | نعم | List name, shown on the signup form. (max 200 chars) |
description | string | لا | Short description shown on the signup form. (max 500 chars) |
form_enabled | boolean | لا | Publish the hosted signup form. |
form_from | string | لا | Sender of signup confirmation emails, e.g. Acme <news@example.com>, on a verified domain. (max 320 chars) |
redirect_url | string | لا | https page to open after a signup is confirmed. (max 500 chars) |
welcome | object | لا | Welcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled. |
welcome.enabled | boolean | لا | Send it. |
welcome.subject | string | لا | Subject; merge tags allowed. (max 300 chars) |
welcome.html | string | لا | HTML body; merge tags allowed. (max 500000 chars) |
welcome.markdown | string | لا | Markdown body instead of html, rendered with the workspace design. (max 200000 chars) |
site | object | لا | Public newsletter site at https://sendhq.cc/n/<slug>: a signup form, every issue sent with web.enabled, and an RSS feed at /n/<slug>/feed.xml. Needs the signup form on. A reserved or taken slug fails with 409. |
site.enabled | boolean | لا | Publish the site. |
site.slug | string,null | لا | Address after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars) |
site.title | string,null | لا | Site title. Defaults to the list name. (max 120 chars) |
site.description | string,null | لا | Short description under the title. (max 300 chars) |
site.accent | string,null | لا | Accent color, e.g. #0a7d4f. |
{
"name": "create_list",
"arguments": {
"name": "Product updates"
}
}get_listGet a list
Campaigns: One list with member counts and signup form settings.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
list_id | string | نعم | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
{
"name": "get_list",
"arguments": {
"list_id": "lst_123"
}
}update_listUpdate a list
Campaigns: Rename a list, change its description, or change its hosted signup form, welcome email, or newsletter site. Omitted keys inside welcome and site keep their value.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
list_id | string | نعم | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
name | string | لا | New name. (max 200 chars) |
description | string | لا | New description. (max 500 chars) |
form_enabled | boolean | لا | Publish or unpublish the hosted signup form. |
form_from | string | لا | Sender of signup confirmation emails, on a verified domain. (max 320 chars) |
redirect_url | string | لا | https page to open after a signup is confirmed. (max 500 chars) |
welcome | object | لا | Welcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled. |
welcome.enabled | boolean | لا | Send it. |
welcome.subject | string | لا | Subject; merge tags allowed. (max 300 chars) |
welcome.html | string | لا | HTML body; merge tags allowed. (max 500000 chars) |
welcome.markdown | string | لا | Markdown body instead of html, rendered with the workspace design. (max 200000 chars) |
site | object | لا | Public newsletter site at https://sendhq.cc/n/<slug>: a signup form, every issue sent with web.enabled, and an RSS feed at /n/<slug>/feed.xml. Needs the signup form on. A reserved or taken slug fails with 409. |
site.enabled | boolean | لا | Publish the site. |
site.slug | string,null | لا | Address after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars) |
site.title | string,null | لا | Site title. Defaults to the list name. (max 120 chars) |
site.description | string,null | لا | Short description under the title. (max 300 chars) |
site.accent | string,null | لا | Accent color, e.g. #0a7d4f. |
{
"name": "update_list",
"arguments": {
"list_id": "lst_123",
"form_enabled": false
}
}delete_listDelete a list
DESTRUCTIVE: delete a list and its memberships. The contacts themselves are kept. Fails with 409 while a broadcast to the list is sending. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
list_id | string | نعم | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
{
"name": "delete_list",
"arguments": {
"list_id": "lst_123"
}
}add_list_contactsAdd contacts to a list
Campaigns: Add up to 500 existing contacts to a list by ID or email. Subscribed contacts join subscribed; others join in their current state. Unknown references come back in notFound.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
list_id | string | نعم | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
contact_ids | string[] | لا | Contact IDs (ct_…). (0–500 items) |
emails | string[] | لا | Contact email addresses. (0–500 items) |
{
"name": "add_list_contacts",
"arguments": {
"list_id": "lst_123",
"emails": [
"ada@example.net"
]
}
}remove_list_contactRemove a contact from a list
DESTRUCTIVE: remove one contact from a list. The contact and its status are kept. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
list_id | string | نعم | List ID (starts with lst_), as returned by a list or create tool. (max 128 chars) |
contact_id | string | نعم | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "remove_list_contact",
"arguments": {
"list_id": "lst_123",
"contact_id": "ct_123"
}
}list_broadcastsList broadcasts
Campaigns: Newest-first broadcasts with their status. Paginated: the result includes pagination.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
status | string | لا | Only broadcasts with this status. (one of draft, sending, sent, cancelled, failed) |
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_broadcasts",
"arguments": {}
}create_broadcastCreate a broadcast draft
Campaigns: Create a draft broadcast to one list. Content is html and/or text, markdown, a block document in content, or a published hosted template. Raw content supports merge tags: {{first_name}}, {{name}}, {{email}}, {{fields.plan}}, with fallbacks like {{first_name | there}}. audience narrows it to a segment and/or a number of people (most engaged first with order: engaged); tracking turns open and click tracking off; web publishes it on the list's newsletter site once sent. Nothing is sent until send_broadcast or schedule_broadcast; run check_broadcast and send_broadcast_test first.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
name | string | لا | Internal name. Defaults to the subject. (max 200 chars) |
list_id | string | لا | The list to send to (lst_…). |
from | string | لا | Sender on a verified domain, e.g. Acme <news@example.com>. (max 320 chars) |
reply_to | string | لا | Reply-To address. (max 320 chars) |
subject | string | لا | Subject line; merge tags allowed. (max 998 chars) |
preview_text | string | لا | Inbox preview text shown after the subject. (max 300 chars) |
html | string | لا | HTML body; merge tags allowed and escaped. |
text | string | لا | Plain-text body; merge tags allowed. |
template | object | لا | A published hosted template instead of subject/html/text. Template variables are filled from the contact's name, email, and fields. |
template.id | string | لا | |
template.key | string | لا | |
template.version_id | string | لا | |
markdown | string | لا | Markdown body instead of html: converted to a block document and rendered with the workspace design (get_newsletter_settings). Merge tags allowed. Not combinable with html or content. (max 1000000 chars) |
content | object,null | لا | Block document ({"type": "doc", "content": [...]}, the dashboard editor's format: paragraph, heading, bulletList, orderedList, blockquote, image, button, callout, horizontalRule, codeBlock). Rendered with the workspace design unless html is also sent. |
editor | string | لا | Which editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks) |
audience | object | لا | Who gets it, within the list. Subscribed, non-dormant members only. |
audience.segment_id | string,null | لا | Only list members matching this segment (seg_…), or null for the whole list. |
audience.order | string | لا | With a limit: signup (default) or engaged (most engaged first). (one of signup, engaged) |
audience.limit | integer,null | لا | Send to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000) |
tracking | object | لا | Open and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email. |
tracking.opens | boolean | لا | Add an open pixel. |
tracking.clicks | boolean | لا | Rewrite links to signed SendHQ redirects (the unsubscribe link never is). |
web | object | لا | Publish this issue on the list's newsletter site (see create_list site) once it is sent. |
web.enabled | boolean | لا | Publish it. |
web.slug | string,null | لا | Issue address; defaults to the subject. (max 100 chars) |
web.pinned | boolean | لا | Keep it at the top of the site. |
{
"name": "create_broadcast",
"arguments": {
"list_id": "lst_123",
"from": "news@example.com",
"subject": "October update",
"markdown": "Hi {{first_name | there}}, here's what shipped.",
"audience": {
"order": "engaged",
"limit": 1000
}
}
}get_broadcastGet a broadcast
Campaigns: One broadcast with its content and, once sending, recipient totals (queued, sending, sent, held, skipped, failed). While a limit or reputation pause holds delivery, lastError explains why and nextAttemptAt says when it resumes.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "get_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}update_broadcastEdit a draft broadcast
Campaigns: Change any field of an unscheduled draft broadcast (content, audience, tracking, web). A scheduled draft must be unscheduled first (unschedule_broadcast); sent or sending broadcasts cannot be edited.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
name | string | لا | Internal name. (max 200 chars) |
list_id | string | لا | The list to send to. |
from | string | لا | Sender on a verified domain. (max 320 chars) |
reply_to | string | لا | Reply-To address. (max 320 chars) |
subject | string | لا | سطر الموضوع. (حتى 998 حرفًا) |
preview_text | string | لا | Inbox preview text. (max 300 chars) |
html | string | لا | نص الرسالة بصيغة HTML. |
text | string | لا | نص الرسالة العادي. |
template | object,null | لا | A published hosted template, or null to remove it. |
markdown | string | لا | Markdown body instead of html: converted to a block document and rendered with the workspace design (get_newsletter_settings). Merge tags allowed. Not combinable with html or content. (max 1000000 chars) |
content | object,null | لا | Block document ({"type": "doc", "content": [...]}, the dashboard editor's format: paragraph, heading, bulletList, orderedList, blockquote, image, button, callout, horizontalRule, codeBlock). Rendered with the workspace design unless html is also sent. |
editor | string | لا | Which editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks) |
audience | object | لا | Who gets it, within the list. Subscribed, non-dormant members only. |
audience.segment_id | string,null | لا | Only list members matching this segment (seg_…), or null for the whole list. |
audience.order | string | لا | With a limit: signup (default) or engaged (most engaged first). (one of signup, engaged) |
audience.limit | integer,null | لا | Send to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000) |
tracking | object | لا | Open and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email. |
tracking.opens | boolean | لا | Add an open pixel. |
tracking.clicks | boolean | لا | Rewrite links to signed SendHQ redirects (the unsubscribe link never is). |
web | object | لا | Publish this issue on the list's newsletter site (see create_list site) once it is sent. |
web.enabled | boolean | لا | Publish it. |
web.slug | string,null | لا | Issue address; defaults to the subject. (max 100 chars) |
web.pinned | boolean | لا | Keep it at the top of the site. |
{
"name": "update_broadcast",
"arguments": {
"broadcast_id": "bc_123",
"subject": "October product update"
}
}delete_broadcastDelete a draft broadcast
DESTRUCTIVE: permanently delete a draft broadcast. Broadcasts that were sent cannot be deleted. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "delete_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}send_broadcastSend a broadcast
SENDS REAL EMAIL to the broadcast's audience: every subscribed, non-dormant member of its list, narrowed by its segment and limit. Only call it when the user asked to send this broadcast now. Each message goes through the normal checks (verified domain, marketing plan, suppressions, unsubscribes, reputation, daily and monthly limits) and carries one-click unsubscribe from this list; members that cannot be mailed are skipped. Each contact is sent at most once. Delivery continues in the background: poll get_broadcast for totals and get_broadcast_report for engagement. A scheduled broadcast fails with 409 until unscheduled. Unpaid workspaces (integration trial) can send only to the account email. Pass idempotency_key so a retry cannot start the send twice. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
idempotency_key | string | لا | ترويسة Idempotency-Key (حتى 200 حرف). أعد استخدامه فقط لإعادة محاولة هذا الطلب نفسه تمامًا. (حتى 200 حرف) |
{
"name": "send_broadcast",
"arguments": {
"broadcast_id": "bc_123",
"idempotency_key": "october-update"
}
}cancel_broadcastCancel a broadcast
DESTRUCTIVE: stop a draft or sending broadcast for good. Recipients not yet sent are marked skipped; messages already handed to the provider are not recalled. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "cancel_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}list_broadcast_recipientsList broadcast recipients
Campaigns: Per-recipient outcomes and engagement of a broadcast: queued, sending, sent, held, skipped (with the reason), or failed (with the error), the inbox provider, delivered/opened/clicked/bounced/complained/unsubscribed times, and the email ID to inspect delivery events with list_email_events. Filter by outcome, by activity (who opened, clicked, did not open, ...), or by email. Opens are bot-filtered estimates, never proof of reading. Paginated.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
status | string | لا | Only recipients with this outcome. (one of queued, sending, sent, held, skipped, failed) |
activity | string | لا | Only recipients who did this. (one of opened, clicked, not_opened, not_delivered, bounced, complained, unsubscribed) |
query | string | لا | Recipient email contains this text. (max 200 chars) |
include | string | لا | links adds the links each recipient clicked (implied by activity: clicked). (one of links) |
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_broadcast_recipients",
"arguments": {
"broadcast_id": "bc_123",
"status": "failed"
}
}check_broadcastRun a broadcast's pre-send checks
Campaigns: The review list shown before sending: sender verification, subject, preview text, content, audience size, size against Gmail's 102 KB clipping limit, postal address, merge tags without data or fallback, empty or shortened links, image descriptions, placeholder text, spam-prone wording, the trial's own-address rule, and whether a test was sent. ready is false while any check has level block; schedule_broadcast refuses then. Fix warn items or tell the user about them.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "check_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}send_broadcast_testSend a broadcast test
SENDS REAL EMAIL: a copy of the draft marked [Test] to up to 5 addresses (default: the saved test recipients, or the account email), with merge tags filled from contact_id or a sample contact. Never goes to the list. Only send to addresses the user gave or owns. Limited to 100 test sends a day. Template broadcasts are tested with send_template_test. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
to | string[] | لا | Test recipients (up to 5). (1–5 items) |
contact_id | string | لا | Fill merge tags from this contact (ct_…). (max 320 chars) |
remember | boolean | لا | Save to as the default test recipients. |
{
"name": "send_broadcast_test",
"arguments": {
"broadcast_id": "bc_123",
"to": [
"owner@example.com"
]
}
}schedule_broadcastSchedule a broadcast
SENDS REAL EMAIL at scheduled_at to the broadcast's audience, with the same checks as send_broadcast. Only call it when the user asked to send this broadcast at that time. The pre-send checks run now (422 with checks if one blocks). It starts within about a minute of the time; if it can no longer send then, it returns to a draft with the reason in lastError. A scheduled draft cannot be edited until unschedule_broadcast. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
scheduled_at | string | نعم | When to send: ISO 8601 date-time with a timezone, at least a minute and at most a year ahead, e.g. 2026-11-10T09:00:00Z. (max 40 chars) |
{
"name": "schedule_broadcast",
"arguments": {
"broadcast_id": "bc_123",
"scheduled_at": "2026-11-10T09:00:00Z"
}
}unschedule_broadcastUnschedule a broadcast
Campaigns: Return a scheduled broadcast to an editable draft so it does not send. Fails with 409 when it is not scheduled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "unschedule_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}duplicate_broadcastDuplicate a broadcast
Campaigns: Copy any broadcast (draft, sent, or cancelled) into a new draft named <name> (copy) with the same list, sender, content, audience, and tracking settings. Nothing is sent.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "duplicate_broadcast",
"arguments": {
"broadcast_id": "bc_123"
}
}send_broadcast_to_moreSend a broadcast to more people
SENDS REAL EMAIL: sends a sent or sending broadcast to up to limit more people in its audience who have not received it (the rest of a limited audience, or people who joined since), in its audience order. Only call it when the user asked for this. Same checks as send_broadcast; each contact still gets it at most once. Fails with 422 when everyone already got it. Pass idempotency_key so a retry cannot add people twice. Part of Campaigns.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
limit | integer | نعم | How many more people at most. (1–10000000) |
idempotency_key | string | لا | ترويسة Idempotency-Key (حتى 200 حرف). أعد استخدامه فقط لإعادة محاولة هذا الطلب نفسه تمامًا. (حتى 200 حرف) |
{
"name": "send_broadcast_to_more",
"arguments": {
"broadcast_id": "bc_123",
"limit": 500,
"idempotency_key": "october-update-more-1"
}
}get_broadcast_reportGet a broadcast report
Campaigns: Engagement for a sending or sent broadcast: unique and total opens and clicks, bounces, complaints, and unsubscribes with rates in percent, the same per inbox provider, clicks per link, first opens and clicks by hour, and the average of the previous five broadcasts. Opens are estimates: automated requests (scanners, link previews, privacy prefetching) are counted only in machine. Never claim that a person read the email. Fails with 409 for a draft.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
broadcast_id | string | نعم | Broadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars) |
{
"name": "get_broadcast_report",
"arguments": {
"broadcast_id": "bc_123"
}
}get_newsletter_settingsGet newsletter settings
Campaigns: The postal address added to every marketing email footer, the design (accent color, font, alignment) used for Markdown and block content, list cleanup settings, and default test recipients.
لا توجد معلمات.
{
"name": "get_newsletter_settings",
"arguments": {}
}update_newsletter_settingsUpdate newsletter settings
Campaigns: Change the postal address (required in marketing email by CAN-SPAM and CASL), design, list cleanup, or default test recipients. Omitted keys keep their value. List cleanup is on by default and sends email automatically: a subscriber who got afterSends broadcasts in a row without opening or clicking and has been quiet for quietDays gets one "still want these?" email; a week later those who did not confirm become dormant (kept, but skipped by broadcasts). Confirm with the user before turning it on or changing its email.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
postal_address | string | لا | Sender's postal address for the footer. Empty string removes it. (max 300 chars) |
design | object | لا | Rendering design for Markdown and block content. |
design.accentColor | string,null | لا | Hex color like #0a7d4f, or null for the default. |
design.font | string | لا | Font family. (one of sans, serif, mono) |
design.align | string | لا | Text alignment. (one of left, center) |
cleanup | object | لا | List cleanup of readers who stopped opening. |
cleanup.enabled | boolean | لا | Turn list cleanup on or off. |
cleanup.afterSends | integer | لا | Broadcasts in a row without an open or click (3-50). (3–50) |
cleanup.quietDays | integer | لا | Days without engagement (30-730). (30–730) |
cleanup.subject | string,null | لا | Subject of the cleanup email; merge tags allowed. (max 200 chars) |
cleanup.body | string,null | لا | Body text of the cleanup email. (max 2000 chars) |
cleanup.from | string,null | لا | Sender on a verified domain. Defaults to the last sent broadcast's sender. (max 320 chars) |
test_recipients | string[] | لا | Default addresses for send_broadcast_test (up to 5). (0–5 items) |
{
"name": "update_newsletter_settings",
"arguments": {
"postal_address": "Acme Inc., 1 Main St, Springfield",
"design": {
"accentColor": "#0a7d4f"
}
}
}get_campaign_overviewGet campaign overview
Campaigns: Subscriber growth and recent results for the last days (7-365, default 30): active, dormant, and pending subscribers, joined and left, a daily series, and the six latest broadcasts with open and click rates (bot-filtered estimates) and their average.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
days | integer | لا | Window in days, 7 to 365. Defaults to 30. (7–365) |
{
"name": "get_campaign_overview",
"arguments": {
"days": 30
}
}list_uploaded_imagesList uploaded images
Campaigns: The workspace's 60 most recent editor image uploads with their public URLs (https://sendhq.cc/i/<id>), to reuse in broadcast HTML, Markdown, or image blocks. Uploading needs the dashboard or the REST API (raw image body). Paginated.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_uploaded_images",
"arguments": {}
}Automations, events, and sending limits
track_eventRecord something a contact did
SENDS REAL EMAIL later, when an automation is listening: the contact enters every automation that is on and starts on this event, and that automation then emails them on its schedule, within the workspace's sending limits and hours. Only record what the person really did. In order: the contact changes in contact and the event are saved; open enrolments whose automation names the event as its goal end as converted, and ones that list it as a stop event end; then the contact enters the automations that start on it, unless already in them or reentry forbids it. A contact that is unsubscribed, bounced, or complained is recorded and can leave automations but never enters one. A new contact needs contact.consent_basis. Pass dedupe_key so a retry changes nothing and returns the first result. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
email | string | نعم | The contact's email address. (max 320 chars) |
event | string | نعم | What they did: a lowercase letter, then a-z, 0-9, and _ (e.g. checkout_started). Names starting email. are reserved. (max 64 chars) |
properties | object | لا | Up to 50 values (string, number, or boolean; strings are cut at 500 characters), e.g. {"plan": "pro"}. Usable in the automation's emails as merge tags such as {{ plan }}. The names email, name, first_name, last_name, and fields are reserved. |
occurred_at | string | لا | When it happened, ISO 8601 with a time zone. Defaults to now; may not be in the future. The automation's emails are timed from it. (max 40 chars) |
dedupe_key | string | لا | Stable ID for this event (max 200 chars). A second call with the same key records nothing and returns the first result. (max 200 chars) |
contact | object | لا | Changes to the contact, applied with the event. |
contact.name | string | لا | Display name. (max 200 chars) |
contact.fields | object | لا | Custom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field. |
contact.timezone | string | لا | IANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars) |
contact.locale | string | لا | Language tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars) |
contact.consent_basis | string | لا | How this person agreed to receive your email, e.g. Created an account on acme.com and accepted product emails. Required when the email is not a contact yet. 10-500 characters. (max 500 chars) |
{
"name": "track_event",
"arguments": {
"email": "ada@example.net",
"event": "checkout_started",
"properties": {
"plan": "pro"
},
"dedupe_key": "checkout_8f3a"
}
}list_automationsList automations
Automations: Every automation in priority order with its status (draft, on, or off), how many emails it has, and totals for the last 30 days (entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held). held counts each time an email was made to wait by the sending limits, the sending hours, or the automation's daily cap. Each automation carries domain, the domain of its from_address (null while it has no sender). domain narrows the list to the automations that send from one domain (none: those with no sender yet); domains always lists every sender domain of the workspace, in alphabetical order, with how many automations each has. Email bodies are not included; use get_automation. For other date ranges and daily numbers use get_automation_report. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
domain | string | لا | Only the automations that send from this domain: the exact domain of their from_address (e.g. example.com), or none for automations with no sender yet. (max 253 chars) |
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_automations",
"arguments": {
"domain": "example.com"
}
}get_automationGet an automation
Automations: One automation with its emails in order and their language versions, how many people are in it now, and overlap: the other automations that are on and currently have the same people in them, with goes_first true for one that ranks above this automation (the shared people get its emails first and wait in this one). to_fill lists what must still be filled in before it can be turned on: placeholders of the template library left in its emails, and workspace names they print that are blank. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
{
"name": "get_automation",
"arguments": {
"automation_key": "checkout-recovery"
}
}create_automationCreate an automation
Automations: Create a timed sequence of emails for one kind of person, as a draft. To start from a ready-made email instead (welcome, onboarding, trial, abandoned checkout, failed payment, winback and more), use use_automation_template. Nothing is sent until set_automation_status turns it on. key is its address and cannot be changed. entry says how people enter, exit_rules when they leave, and steps are the emails, each due offset_seconds after the person entered. from_address must be on a verified domain. Fails with 409 when the key is taken. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
key | string | نعم | Address of the automation: 1-63 characters of a-z, 0-9, and - (e.g. checkout-recovery). (max 63 chars) |
name | string | نعم | Name shown in the dashboard. (max 200 chars) |
audience_label | string | لا | Who this is for, in plain words, e.g. Started checkout and left. (max 200 chars) |
goal_label | string | لا | What converting means, in a word or two, e.g. paid. (max 80 chars) |
entry | object | لا | How people enter. {type: "event", event} starts on an event recorded with track_event; {type: "manual"} only through enroll_contact. bucket (with segment_id) and date_field (with field) are stored, but nobody enters through them automatically yet. reentry: never (default) or after_end. |
entry.type | string | نعم | Entry type. (one of event, bucket, date_field, manual) |
entry.event | string | لا | Event name for an event entry, e.g. checkout_started. |
entry.segment_id | string | لا | Segment ID (seg_…) for a bucket entry. (max 128 chars) |
entry.field | string | لا | Contact field key for a date_field entry. (max 40 chars) |
entry.reentry | string | لا | Whether someone who finished may enter again. (one of never, after_end) |
exit_rules | object | لا | When people leave. goal_event ends the enrolment as converted and credits the latest email sent within attribution_days before it. Each of stop_events ends it without a conversion. An automation with no goal must say so with no_goal: true. Sent whole: it replaces the current rules. |
exit_rules.goal_event | string,null | لا | Event that counts as converting, e.g. payment_completed. |
exit_rules.no_goal | boolean | لا | True when this automation deliberately has no goal. |
exit_rules.stop_events | string[] | لا | Events that take a person out, e.g. ["account_closed"]. (0–20 items) |
exit_rules.attribution_days | integer | لا | Days before the goal within which an email earns the conversion. Default 14. (1–90) |
settings | object | لا | Per-automation settings. Omitted keys keep their value. |
settings.exempt_from_hold | boolean | لا | Skip the workspace's per-person limits (max_emails and min_gap_hours) for this automation. The sending hours still apply, and its emails still count toward the limits of other automations. |
settings.daily_send_cap | integer,null | لا | At most this many emails a day from this automation, counted by the day of the workspace's default_timezone; emails over it wait until the next day. null for no cap. (1–…) |
settings.daily_entry_cap | integer,null | لا | Stored for bucket entries, which are not started automatically yet. It does not limit people entering by event or through enroll_contact. null for no cap. (1–…) |
settings.holdout_pct | number | لا | Percent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100) |
settings.stale_days | integer | لا | An email more than this many days overdue is skipped instead of sent late. Default 4. (1–365) |
settings.resume_after_days | integer | لا | How long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365) |
position | integer | لا | Priority. While one person is in several automations that are on, only the one with the lowest position emails them; the others wait and resume resume_after_days after it ends. (0–100000) |
from_name | string | لا | Sender display name, e.g. Acme. (max 120 chars) |
from_address | string | لا | Sender address on a verified workspace domain (see list_sending_identities). (max 320 chars) |
reply_to | string | لا | Reply-To address. (max 320 chars) |
steps | object[] | لا | The emails, in order. position defaults to the place in this list. (0–50 items) |
steps[].position | integer | لا | Position of the email in the automation, 1 to 50. (1–50) |
steps[].subject | string | لا | Subject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars) |
steps[].preheader | string | لا | Inbox preview line. (max 300 chars) |
steps[].content | object | لا | Block document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html. |
steps[].html | string | لا | HTML body. The unsubscribe footer is added automatically. |
steps[].text | string | لا | نص الرسالة العادي. |
steps[].editor | string | لا | How the email is made: blocks (the dashboard's writing editor, the default), html (your own HTML) or design (the dashboard's drag-and-drop builder). Only the builder makes a design; to send a designed email yourself, send html with editor html. (one of blocks, html, design) |
steps[].offset_seconds | integer | لا | When the email is due, in seconds after the moment the person entered (3600 = one hour, 86400 = one day). May be negative for emails that lead up to a date. When several emails are due at once, only the latest is sent and the earlier ones are skipped. (-31622400–31622400) |
steps[].skip_if_empty | string[] | لا | Merge keys, e.g. ["fields.plan"]. The email is skipped for a contact where any of them is blank, 0, or false. (0–20 items) |
steps[].ignore_send_window | boolean | لا | Send as soon as it is due, outside the workspace's sending hours too. The per-person limits still apply. |
{
"name": "create_automation",
"arguments": {
"key": "checkout-recovery",
"name": "Checkout recovery",
"audience_label": "Started checkout and left",
"goal_label": "paid",
"from_name": "Acme",
"from_address": "hello@example.com",
"entry": {
"type": "event",
"event": "checkout_started"
},
"exit_rules": {
"goal_event": "payment_completed"
},
"steps": [
{
"offset_seconds": 3600,
"subject": "Still thinking it over, {{ first_name | there }}?",
"html": "<p>Your cart is waiting.</p>"
}
]
}
}update_automationEdit an automation
Automations: Change an automation's name, labels, entry, exit rules, sender, or priority. settings are merged; entry and exit_rules replace the current ones. The key and the status cannot be changed here (use set_automation_status), and emails are changed with set_automation_step. If the automation is on, the change applies to people in it now, and an edit that would leave it unable to send is refused with 422 automation_not_ready. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
name | string | لا | Name shown in the dashboard. (max 200 chars) |
audience_label | string | لا | Who this is for, in plain words, e.g. Started checkout and left. (max 200 chars) |
goal_label | string | لا | What converting means, in a word or two, e.g. paid. (max 80 chars) |
entry | object | لا | How people enter. {type: "event", event} starts on an event recorded with track_event; {type: "manual"} only through enroll_contact. bucket (with segment_id) and date_field (with field) are stored, but nobody enters through them automatically yet. reentry: never (default) or after_end. |
entry.type | string | نعم | Entry type. (one of event, bucket, date_field, manual) |
entry.event | string | لا | Event name for an event entry, e.g. checkout_started. |
entry.segment_id | string | لا | Segment ID (seg_…) for a bucket entry. (max 128 chars) |
entry.field | string | لا | Contact field key for a date_field entry. (max 40 chars) |
entry.reentry | string | لا | Whether someone who finished may enter again. (one of never, after_end) |
exit_rules | object | لا | When people leave. goal_event ends the enrolment as converted and credits the latest email sent within attribution_days before it. Each of stop_events ends it without a conversion. An automation with no goal must say so with no_goal: true. Sent whole: it replaces the current rules. |
exit_rules.goal_event | string,null | لا | Event that counts as converting, e.g. payment_completed. |
exit_rules.no_goal | boolean | لا | True when this automation deliberately has no goal. |
exit_rules.stop_events | string[] | لا | Events that take a person out, e.g. ["account_closed"]. (0–20 items) |
exit_rules.attribution_days | integer | لا | Days before the goal within which an email earns the conversion. Default 14. (1–90) |
settings | object | لا | Per-automation settings. Omitted keys keep their value. |
settings.exempt_from_hold | boolean | لا | Skip the workspace's per-person limits (max_emails and min_gap_hours) for this automation. The sending hours still apply, and its emails still count toward the limits of other automations. |
settings.daily_send_cap | integer,null | لا | At most this many emails a day from this automation, counted by the day of the workspace's default_timezone; emails over it wait until the next day. null for no cap. (1–…) |
settings.daily_entry_cap | integer,null | لا | Stored for bucket entries, which are not started automatically yet. It does not limit people entering by event or through enroll_contact. null for no cap. (1–…) |
settings.holdout_pct | number | لا | Percent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100) |
settings.stale_days | integer | لا | An email more than this many days overdue is skipped instead of sent late. Default 4. (1–365) |
settings.resume_after_days | integer | لا | How long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365) |
position | integer | لا | Priority. While one person is in several automations that are on, only the one with the lowest position emails them; the others wait and resume resume_after_days after it ends. (0–100000) |
from_name | string | لا | Sender display name, e.g. Acme. (max 120 chars) |
from_address | string | لا | Sender address on a verified workspace domain (see list_sending_identities). (max 320 chars) |
reply_to | string | لا | Reply-To address. (max 320 chars) |
{
"name": "update_automation",
"arguments": {
"automation_key": "checkout-recovery",
"name": "Checkout recovery",
"settings": {
"holdout_pct": 10
}
}
}delete_automationDelete an automation
DESTRUCTIVE: permanently delete an automation with its emails, language versions, enrolments, send records, and statistics. Only a draft or switched-off automation that nobody is currently in can be deleted; otherwise it fails with 409. Confirm with the user first. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
{
"name": "delete_automation",
"arguments": {
"automation_key": "checkout-recovery"
}
}set_automation_stepCreate or change an email of an automation
Automations: Create the email at position, or change the fields you pass on the one that is there; fields left out keep their value. If the automation is on, people who have not received this email yet get the new version, so confirm the wording with the user. An existing email keeps its ID: people who already received it are not sent it again. With template, the email becomes that template of the library (see list_automation_templates): its subject, preview text and content replace the email's and its language versions are removed. While the automation is on, an email must keep a subject and content, and may not hold a placeholder of the template library such as [First step] or print a workspace name that is blank (422 automation_not_ready with problems). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
position | integer | نعم | Position of the email in the automation, 1 to 50. (1–50) |
template | string | لا | Id of a template of the library, e.g. welcome-note (not a set). The email becomes that template; other fields passed here are applied on top. The email's wait is not the template's: pass offset_seconds. (max 63 chars) |
subject | string | لا | Subject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars) |
preheader | string | لا | Inbox preview line. (max 300 chars) |
content | object | لا | Block document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html. |
html | string | لا | HTML body. The unsubscribe footer is added automatically. |
text | string | لا | نص الرسالة العادي. |
editor | string | لا | How the email is made: blocks (the dashboard's writing editor, the default), html (your own HTML) or design (the dashboard's drag-and-drop builder). Only the builder makes a design; to send a designed email yourself, send html with editor html. (one of blocks, html, design) |
offset_seconds | integer | لا | When the email is due, in seconds after the moment the person entered (3600 = one hour, 86400 = one day). May be negative for emails that lead up to a date. When several emails are due at once, only the latest is sent and the earlier ones are skipped. (-31622400–31622400) |
skip_if_empty | string[] | لا | Merge keys, e.g. ["fields.plan"]. The email is skipped for a contact where any of them is blank, 0, or false. (0–20 items) |
ignore_send_window | boolean | لا | Send as soon as it is due, outside the workspace's sending hours too. The per-person limits still apply. |
{
"name": "set_automation_step",
"arguments": {
"automation_key": "checkout-recovery",
"position": 2,
"offset_seconds": 86400,
"subject": "Your cart is still here",
"html": "<p>Pick up where you left off.</p>"
}
}delete_automation_stepRemove an email from an automation
DESTRUCTIVE: remove the email at position from an automation. It is no longer sent or listed; records of who already received it are kept. While the automation is on, its only email cannot be removed (409). Confirm with the user first. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
position | integer | نعم | Position of the email in the automation, 1 to 50. (1–50) |
{
"name": "delete_automation_step",
"arguments": {
"automation_key": "checkout-recovery",
"position": 3
}
}set_automation_step_variantCreate or change a language version of an email
Automations: Save the version of one email for contacts whose locale is this language tag (e.g. fr); a contact with a regional locale such as pt-br gets the pt version when there is no pt-br one. Fields left out keep their value. A version without a body uses the email's own body, and a blank subject or preheader falls back to the email's. Contacts without a matching version get the email as written. If the automation is on, matching contacts who have not received this email yet get this version. While the automation is on, a version may not hold a placeholder of the template library or print a workspace name that is blank (422 automation_not_ready). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
position | integer | نعم | Position of the email in the automation, 1 to 50. (1–50) |
locale | string | نعم | Language tag of the version, e.g. fr or pt-br. (max 35 chars) |
subject | string | لا | Subject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars) |
preheader | string | لا | Inbox preview line. (max 300 chars) |
content | object | لا | Block document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html. |
html | string | لا | HTML body. The unsubscribe footer is added automatically. |
text | string | لا | نص الرسالة العادي. |
{
"name": "set_automation_step_variant",
"arguments": {
"automation_key": "checkout-recovery",
"position": 1,
"locale": "fr",
"subject": "Vous hésitez encore ?",
"html": "<p>Votre panier vous attend.</p>"
}
}set_automation_statusTurn an automation on or off
SENDS REAL EMAIL when status is on: from then on, everyone who enters the automation is emailed on its schedule, within the workspace's sending limits and hours (get_sending_limits), and people already in it continue. Use preview_automation to see who would get which email. Only turn it on when the user asked for this automation to start. Turning on checks an entry, a goal or exit_rules.no_goal, at least one email with a subject and content, no placeholder of the template library such as [First step] or [Link to plans] left in any email (subject, preview text, body, or a link's address), and no blank workspace name that an email prints (422 automation_not_ready with problems, which names each email and detail; get_automation lists the same under to_fill), a sender on a verified domain (403), and an active subscription (402). off stops new entries and sending; people in it stay and continue if it is turned on again, except that an email more than stale_days overdue by then is skipped. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
status | string | نعم | on to start sending, off to stop. (one of on, off) |
{
"name": "set_automation_status",
"arguments": {
"automation_key": "checkout-recovery",
"status": "off"
}
}send_automation_test_emailSend one automation email to yourself as a test
SENDS REAL EMAIL: one email of an automation, marked [Test], to the account's own address (get_account -> user.email) and nowhere else; a recipient cannot be given. It is the email as the automation would send it (the language version for locale, the same sender, unsubscribe footer and checks), with stand-in values for its merge tags; sample replaces any of them. A test is not part of the automation: nobody is enrolled, it is in no report, it counts toward nobody's per-person sending limits, it is not tracked, and the automation does not have to be on. It counts toward the workspace's own sending allowance. With dry_run: true nothing is sent and the result is the email as the test would deliver it, with locales and the sample values used. Fails with 422 automation_not_ready when the automation has no sender or the email has no subject or content, and 429 test_limit_reached after 100 test emails in 24 hours. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
position | integer | نعم | Position of the email in the automation, 1 to 50. (1–50) |
locale | string | لا | Send the language version a contact with this language would get (such as fr or pt-br). Omit for the email as written. (max 35 chars) |
sample | object | لا | Values to print for merge tags, by key, in place of the stand-ins (first_name is Alex, and so on). email, product_name, and sender_name cannot be set. |
dry_run | boolean | لا | Send nothing; return the email as the test would deliver it. |
{
"name": "send_automation_test_email",
"arguments": {
"automation_key": "checkout-recovery",
"position": 1
}
}send_automation_testSend every email of an automation to yourself as tests
SENDS REAL EMAIL: every email of an automation, in order, marked [Test 1 of 3], [Test 2 of 3] and so on, to the account's own address (get_account -> user.email) and nowhere else, without waiting for the emails' delays. Rendering, footer, checks and stand-in values are as in send_automation_test_email. A test is not part of the automation: nobody is enrolled, it is in no report, it counts toward nobody's per-person sending limits, it is not tracked, and the automation does not have to be on. It counts toward the workspace's own sending allowance. Nothing is sent unless everything can be: a sender, a subject and content on every email (422 automation_not_ready with problems), and room for all of them under 100 test emails in 24 hours (429 test_limit_reached). If a send is refused after others went out, the rest are not tried and each email's outcome is returned. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
locale | string | لا | Send the language version a contact with this language would get (such as fr or pt-br). Omit for the email as written. (max 35 chars) |
sample | object | لا | Values to print for merge tags, by key, in place of the stand-ins (first_name is Alex, and so on). email, product_name, and sender_name cannot be set. |
{
"name": "send_automation_test",
"arguments": {
"automation_key": "checkout-recovery"
}
}enroll_contactAdd a contact to an automation
SENDS REAL EMAIL on the automation's schedule: starts the automation for one existing, subscribed contact, counting from anchor_at (now by default). Only call it when the user asked for this person to get this sequence. The automation must be on (409 automation_not_on). Fails with 404 when the email is not a contact (add it with upsert_contact), 422 when the contact cannot be mailed, and 409 when the contact is already in it or went through it before and re-entry is not allowed. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
email | string | نعم | Email address of an existing contact. (max 320 chars) |
properties | object | لا | Up to 50 values (string, number, or boolean; strings are cut at 500 characters), e.g. {"plan": "pro"}. Usable in the automation's emails as merge tags such as {{ plan }}. The names email, name, first_name, last_name, and fields are reserved. |
anchor_at | string | لا | The moment the emails' offsets count from, ISO 8601 with a time zone. Defaults to now; may lie ahead for emails that lead up to a date. (max 40 chars) |
{
"name": "enroll_contact",
"arguments": {
"automation_key": "checkout-recovery",
"email": "ada@example.net",
"properties": {
"plan": "pro"
}
}
}exit_contactTake a contact out of an automation
Automations: End a contact's open enrolment in one automation, so no further emails of it are sent to them. Other automations and broadcasts are not affected, and the contact stays subscribed. Fails with 404 when the contact is not in it. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
email | string | نعم | Email address of the contact. (max 320 chars) |
reason | string | لا | Why, for the record (max 200 chars). Defaults to manual. (max 200 chars) |
{
"name": "exit_contact",
"arguments": {
"automation_key": "checkout-recovery",
"email": "ada@example.net",
"reason": "Asked support to stop"
}
}preview_automationPreview what an automation would send now
Automations: A dry run. For the people in the automation now, in the order they come due, what would happen if each were evaluated at this moment. outcome is send (the email in step would go out), scheduled (nothing is due before until), held (the email waits until until; reason is limit_cap, limit_gap, window, or daily_cap), waiting (behind the higher-priority automation in behind), skip (reason is stale, empty_field, or holdout), exit (the contact can no longer be mailed and would leave), complete, blocked (automation_off or subscription_required), or in_progress. Read-only: nothing is sent or changed. Use it before set_automation_status, or after changing limits, to see who gets which email. It applies the automation's own rules and does not foresee a refusal only a real send meets, such as the workspace's daily sending limit or a paused sender. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "preview_automation",
"arguments": {
"automation_key": "checkout-recovery"
}
}get_automations_overviewGet results across all automations
Automations: What every automation of the workspace did in a date range (the last 30 days by default, at most 366 days): totals and one entry per day for people who entered, emails sent, delivered, opened, clicked, and converted (a goal event credited to an email), plus bounces, complaints, unsubscribes, and held (emails made to wait by a limit). Days on which nothing happened are in the series with zeros. domain narrows it to the automations that send from one domain (none: those with no sender yet). Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
from | string | لا | First day of the report as a UTC date (YYYY-MM-DD), inclusive. |
to | string | لا | Last day of the report as a UTC date (YYYY-MM-DD), inclusive. |
domain | string | لا | Only the automations that send from this domain: the exact domain of their from_address (e.g. example.com), or none for automations with no sender yet. (max 253 chars) |
{
"name": "get_automations_overview",
"arguments": {
"from": "2026-10-20",
"to": "2026-11-18"
}
}get_automation_reportGet the results of one automation
Automations: The results of one automation in a date range (the last 30 days by default, at most 366 days): the same totals and daily series as get_automations_overview, and steps, one row per email with what it sent and what came of it. An email that was removed is listed with archived: true while it still has numbers in the range. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
from | string | لا | First day of the report as a UTC date (YYYY-MM-DD), inclusive. |
to | string | لا | Last day of the report as a UTC date (YYYY-MM-DD), inclusive. |
{
"name": "get_automation_report",
"arguments": {
"automation_key": "checkout-recovery"
}
}list_automation_peopleList the people in an automation
Automations: One row per person who did did in an automation, most recent first: entered (the default: everyone who was ever in it), sent, delivered, opened, clicked, converted (their goal was credited to an email), bounced, unsubscribed, or waiting (waiting now behind a higher-priority automation). step narrows every filter except entered and waiting to one email. Each row has the contact's email and name, when they did it, their enrolment's status, and latest: the most recent thing that happened to them in the automation. counts says how many people each filter would list. Read one person's full history with get_automation_person. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
did | string | لا | What the people did. Defaults to entered. (one of entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, waiting) |
step | integer | لا | Only this email of the automation, by its position. (1–50) |
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_automation_people",
"arguments": {
"automation_key": "checkout-recovery",
"did": "clicked"
}
}get_automation_personGet one person's history in an automation
Automations: Everything that happened to one contact in an automation: each enrolment and how it ended, each email with when it was sent, delivered, first opened, first clicked, bounced, complained about, or unsubscribed from, every open and click on it (machine: true marks an automated request, which is not counted), and the conversion with the email it was credited to. Fails with 404 for a contact that was never in the automation. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
automation_key | string | نعم | Automation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars) |
contact_id | string | نعم | Contact ID (starts with ct_) or the contact's email address. (max 320 chars) |
{
"name": "get_automation_person",
"arguments": {
"automation_key": "checkout-recovery",
"contact_id": "ct_123"
}
}get_sending_limitsGet automation sending limits
Automations: How much automation email one person may get across every automation, and when: at most max_emails in any period_days, at least min_gap_hours apart, only between window_start and window_end (hours in the contact's time zone, or default_timezone) on weekdays (0 = Sunday to 6 = Saturday). An email that would break a limit is not dropped: it waits until the limits allow it. Also product_name and sender_name, available to every automation email as merge tags. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
لا توجد معلمات.
{
"name": "get_sending_limits",
"arguments": {}
}update_sending_limitsUpdate automation sending limits
Automations: Change the workspace's per-person limits and sending hours for automation email. Omitted keys keep their value. Looser limits mean people can get more email, sooner: confirm with the user before raising max_emails, shortening min_gap_hours, or widening the hours. product_name and sender_name are the names the emails of the template library print; one that an automation that is on prints cannot be cleared (409 workspace_name_in_use). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
max_emails | integer | لا | Most automation emails one person may get in period_days. Default 2. (1–50) |
period_days | integer | لا | The period max_emails applies to, in days. Default 7. (1–90) |
min_gap_hours | integer | لا | Least time between two automation emails to one person, in hours. Default 44. (0–720) |
window_start | integer | لا | First hour of the day emails may go out, local time (0-23). Default 9. (0–23) |
window_end | integer | لا | Hour sending stops, local time (1-24); must be later than window_start. Default 18. (1–24) |
weekdays | integer[] | لا | Days emails may go out: 0 = Sunday to 6 = Saturday. Default [1, 2, 3, 4, 5]. (1–7 items) |
default_timezone | string | لا | IANA time zone used for contacts that have none, e.g. Europe/London. (max 64 chars) |
product_name | string | لا | Your product's name, for {{ product_name }}. (max 120 chars) |
sender_name | string | لا | Who the emails are from, for {{ sender_name }}. (max 120 chars) |
{
"name": "update_sending_limits",
"arguments": {
"max_emails": 3,
"min_gap_hours": 24,
"default_timezone": "Europe/London"
}
}list_automation_templatesList automation templates
Automations: The template library: ready-made lifecycle emails to start an automation from instead of writing one. It covers welcome, onboarding tips, a nudge to finish setup (activation), trial ending and trial ended, abandoned checkout, failed payment (dunning), receipt, upgrade at a usage limit, feature announcement, review request, feedback score (NPS), cancellation survey, and winback for retention. Each template has a name, a one-line purpose, the goal it serves (group), its subject, the merge tags it prints, and start: the suggested entry event, the email's wait, and the goal event that ends the automation for a person. sets are templates that arrive together as one automation: three onboarding tips, trial ending then trial ended, and payment failed then a last notice. fill_in lists what only the user knows: placeholders in square brackets such as [First step] or [Link to plans], and the workspace names the email prints. Email bodies are not included; use get_automation_template. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_automation_templates",
"arguments": {}
}get_automation_templateGet an automation template
Automations: One template or one set of the template library, as the draft automation it would make: the suggested start and goal, what the user must fill in, and every email in order with its wait, subject, the email as a block document (content), and preview: the subject and text as this workspace would send them, with sample values for the merge tags. Read it to show the user a welcome, onboarding, trial, abandoned checkout, failed payment (dunning), upgrade, cancellation or winback email before using it. Placeholders such as [First step] are shown as written; a workspace name that is not set reads "Your product" or "Your name" in the preview. Then use_automation_template makes the draft, or set_automation_step with template loads one email into an existing automation. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
template_id | string | نعم | Id of a template or a set, as returned by list_automation_templates (e.g. welcome-note, checkout-not-finished, payment-failed-notices). (max 63 chars) |
{
"name": "get_automation_template",
"arguments": {
"template_id": "welcome-note"
}
}use_automation_templateCreate an automation from a template
Automations: Create a draft automation from a template or a set of the library, ready-made: a welcome email, three onboarding tips, a nudge to finish setup, trial ending and trial ended, abandoned checkout, failed payment (dunning) notices, a receipt, an upgrade email at a usage limit, a feature announcement, a review request, a feedback score, a cancellation survey, or a winback for retention. The draft has the emails, the suggested entry event and the suggested goal. Nothing is sent: it stays a draft until set_automation_status turns it on, and that is refused while anything in to_fill is left. to_fill lists each placeholder to replace, by email (ask the user for the real words and links, then use set_automation_step), and each workspace name the emails print that is blank (product_name, sender_name: set with update_sending_limits). Make sure the entry event is one the workspace records (list_event_names); change the start with update_automation. from_address must be on a verified domain. Fails with 404 for an unknown template and 409 when key is taken. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
template_id | string | نعم | Id of a template or a set, as returned by list_automation_templates (e.g. welcome-note, checkout-not-finished, payment-failed-notices). (max 63 chars) |
key | string | لا | Address of the new automation: 1-63 characters of a-z, 0-9, and -. Defaults to the template's id, with a number added when that is taken. (max 63 chars) |
name | string | لا | Name shown in the dashboard. Defaults to the template's own name. (max 200 chars) |
from_name | string | لا | Sender display name, e.g. Acme. (max 120 chars) |
from_address | string | لا | Sender address on a verified workspace domain (see list_sending_identities). (max 320 chars) |
reply_to | string | لا | Reply-To address. (max 320 chars) |
{
"name": "use_automation_template",
"arguments": {
"template_id": "welcome-note",
"name": "Welcome",
"from_name": "Dana from Acme",
"from_address": "dana@example.com"
}
}list_eventsList what contacts did
Automations: The events recorded for the workspace, newest first: who (the contact's id, email, and name), what they did (the event name, and the same as words), when, its properties, where it came from (source.type: api for the workspace's own code, connection with the connection's name, upload for a spreadsheet, system for SendHQ itself), and effects: the automations it started, ended, or converted for that contact. Filter by contact (a contact ID or an email address), name (one event name), and from / to. With contact, the result also lists every automation that contact is or was in (enrollments). An event being recorded does not mean an email was sent: check the automation with list_automation_people. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
contact | string | لا | Only this contact: a contact ID or an email address. (max 320 chars) |
name | string | لا | Only this event, e.g. checkout_started. See list_event_names. (max 64 chars) |
from | string | لا | Events from this UTC date (YYYY-MM-DD) or ISO 8601 date-time on. (max 40 chars) |
to | string | لا | Events up to this UTC date (the whole day) or ISO 8601 date-time. (max 40 chars) |
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_events",
"arguments": {
"name": "checkout_started",
"from": "2026-11-01"
}
}list_event_namesList the kinds of event recorded
Automations: Every distinct event name recorded in the last 30 days with how many times, the most frequent first, each with the name as words (checkout_started reads checkout started). Use it to see what the workspace is being told about before creating an automation that starts on an event. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_event_names",
"arguments": {}
}list_connectionsList connections
Automations: The workspace's connections. A connection is a secret address another system posts to, such as a payment provider's webhook; what arrives is recorded as events, exactly as track_event records them. Each has its kind (stripe, dodo, or generic), whether it is enabled, whether a signing secret is set, the last four characters of its address, and last_delivery in plain words such as "Recorded 2 events" or "Refused: bad signature". The address and the signing secret are never returned here. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
limit | integer | لا | حجم الصفحة. الافتراضي 50. (الافتراضي 50؛ من 1 إلى 200) |
offset | integer | لا | عدد السجلات المراد تخطيها. استخدم pagination.next_offset من الصفحة السابقة. (الافتراضي 0؛ من 0 فصاعدًا) |
{
"name": "list_connections",
"arguments": {}
}get_connectionGet a connection and its last deliveries
Automations: One connection with its last 50 deliveries, newest first: when each arrived, whether it was recorded, skipped, or refused and why (text says it in plain words), the sender's own event type, the names of the events recorded, and the contact's email address. Payloads are not stored. Use it to find out why something a provider sent did not show up. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
connection_id | string | نعم | Connection ID, as returned by list_connections (e.g. acn_…). (max 128 chars) |
{
"name": "get_connection",
"arguments": {
"connection_id": "acn_123"
}
}create_connectionCreate a connection
SENDS REAL EMAIL later, when an automation is listening: from the moment the address this returns is given to another system, everything that system posts is recorded as events without anyone looking, and a recorded event starts every automation that is on and starts on it. Only create one when the user asked to connect that system. Returns address once; it cannot be read again, so hand it to the user at once. kind is stripe or dodo (mapped for you: checkout_completed, checkout_abandoned, paid, payment_failed, subscription_started, subscription_renewed, subscription_cancelled, plan_changed) or generic with a mapping. consent_basis is recorded on every contact the connection creates. The provider's signing secret is set by a person in the dashboard or with the REST API, not here. A workspace may have 10 connections (409 connection_limit_reached). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
name | string | نعم | What to call it, e.g. Stripe. (max 80 chars) |
kind | string | نعم | stripe, dodo, or generic. (one of generic, stripe, dodo) |
consent_basis | string | نعم | How the people this connection tells you about agreed to receive your email, e.g. Bought a plan on acme.com and accepted product emails. Recorded on every contact it creates. 10-500 characters. (max 500 chars) |
event_prefix | string | لا | Put in front of every event name, e.g. stripe_. (max 32 chars) |
enabled | boolean | لا | Defaults to true. Pass false to create it switched off. |
mapping | object | لا | For a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name. |
mapping.email | string | لا | Where the contact's email address is. (max 120 chars) |
mapping.event | string | لا | Where the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars) |
mapping.event_name | string | لا | One fixed event name, instead of event. (max 64 chars) |
mapping.time | string | لا | Where the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars) |
mapping.id | string | لا | Where a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars) |
mapping.keep | string[] | لا | The fields to keep as event properties. Defaults to the top-level text, number, and boolean fields. (0–50 items) |
{
"name": "create_connection",
"arguments": {
"name": "Stripe",
"kind": "stripe",
"consent_basis": "Bought a plan on acme.com and accepted product emails"
}
}update_connectionChange a connection or switch it on or off
SENDS REAL EMAIL later when enabled is set to true: what the connected system posts is recorded as events again, and a recorded event starts every automation that is on and starts on it. Only switch one on when the user asked. Also changes name, consent_basis, event_prefix, or a generic connection's mapping. While enabled is false the address answers 404 and records nothing. The kind cannot be changed. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
connection_id | string | نعم | Connection ID, as returned by list_connections (e.g. acn_…). (max 128 chars) |
name | string | لا | A new name. (max 80 chars) |
enabled | boolean | لا | true: record what arrives. false: answer 404 and record nothing. |
consent_basis | string | لا | How the people this connection tells you about agreed to receive your email, e.g. Bought a plan on acme.com and accepted product emails. Recorded on every contact it creates. 10-500 characters. (max 500 chars) |
event_prefix | string | لا | Put in front of every event name, e.g. stripe_. (max 32 chars) |
mapping | object | لا | For a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name. |
mapping.email | string | لا | Where the contact's email address is. (max 120 chars) |
mapping.event | string | لا | Where the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars) |
mapping.event_name | string | لا | One fixed event name, instead of event. (max 64 chars) |
mapping.time | string | لا | Where the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars) |
mapping.id | string | لا | Where a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars) |
mapping.keep | string[] | لا | The fields to keep as event properties. Defaults to the top-level text, number, and boolean fields. (0–50 items) |
{
"name": "update_connection",
"arguments": {
"connection_id": "acn_123",
"enabled": false
}
}delete_connectionDelete a connection
DESTRUCTIVE: permanently delete a connection with its delivery records. Its address stops working at once, so the system that posts to it starts getting 404 and nothing more is recorded from it. The events it already recorded stay. Confirm with the user first; to pause one instead, use update_connection with enabled: false. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
connection_id | string | نعم | Connection ID, as returned by list_connections (e.g. acn_…). (max 128 chars) |
{
"name": "delete_connection",
"arguments": {
"connection_id": "acn_123"
}
}الحساب والاستخدام والتحليلات والمفاتيح
get_accountالحصول على الحساب والاستخدام والفوترة
البريد الإلكتروني لمالك الحساب، والباقة/مستوى الوصول، وعمليات تسليم المستلِمين المستخدمة في الفترة الحالية مقابل الحصة، والنطاقات المستخدمة مقابل الحد، ونقل المرفقات، وملخص السمعة، وحالة الاشتراك، والباقات المنشورة، وأعداد مساحة العمل. استخدمها لمعرفة الحصة المتبقية أو الجهة التي يمكن للفترة التجريبية التسليم إليها (البريد الإلكتروني للحساب).
لا توجد معلمات.
{
"name": "get_account",
"arguments": {}
}get_account_diagnosticsDiagnose sending and receiving
One read that explains what is wrong with sending or receiving in this workspace: an issues list (unverified domains and missing DKIM records, inbound MX not ready, paused or throttled senders, quota or daily limit reached, trial restrictions, high bounce or complaint rates, failing webhooks), plan and usage against limits, each domain with its DKIM and inbound state, sending identities, 30-day deliverability and sender reputation, suppressions and unsubscribes, and the last 30 days of messages that were not sent (with reasons) plus bounce, complaint and reject events. Start here when a user asks why mail is not arriving. Never returns message bodies or secrets.
لا توجد معلمات.
{
"name": "get_account_diagnostics",
"arguments": {}
}get_analyticsالحصول على تحليلات الإرسال
تحليلات لوحة التحكم لآخر 7 أو 30 أو 90 يومًا: إجماليات المرسل/المستلَم/المسلَّم/المرتد/المحظور/المفتوح/المنقور/الشكاوى، وجدول زمني يومي، وأكثر نطاقات الإرسال استخدامًا، وأكثر الموضوعات تكرارًا.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
days | integer | لا | النافذة بالأيام: 7 أو 30 (الافتراضي) أو 90. (إحدى القيم 7 أو 30 أو 90) |
{
"name": "get_analytics",
"arguments": {
"days": 30
}
}list_api_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
تحقق من أن SendHQ API تعمل ومن مزوّد البريد النشط. لا تحتاج إلى مفتاح API صالح.
لا توجد معلمات.
{
"name": "get_service_health",
"arguments": {}
}جرد تغطية API
كل عملية في API العامة والأداة التي تغطيها. كل ما يمكن للمستخدم فعله في لوحة التحكم ولديه API مغطًّى؛ أما الاستثناءات أدناه فمقصودة.
| نقطة النهاية | الأداة | ملاحظات |
|---|---|---|
| POST /emails | send_email | إرسال رسالة واحدة |
| POST /emails/batch | send_batch | إرسال ما يصل إلى 100 رسالة مخصّصة |
| GET /emails | list_emails | عرض الرسائل المرسلة والمستلَمة |
| GET /emails/:id | get_email | استرجاع رسالة ومرفقاتها |
| PATCH /emails/:id | mark_email | تحديث حالة القراءة أو الأرشفة أو التصنيف كبريد مزعج أو الفئة أو الأهمية |
| POST /emails/:id/labels | label_email | إضافة تصنيفات إلى رسالة أو إزالتها منها |
| DELETE /emails/:id | delete_email | حذف رسالة محفوظة |
| GET /emails/:id/events | list_email_events | عرض أحداث التسليم لرسالة |
| GET /threads/:id | get_thread | استرجاع محادثة بترتيب زمني |
| GET /labels | list_labels | عرض التصنيفات مع أعداد الرسائل وقواعد الفرز |
| POST /labels | create_label | إنشاء تصنيف، مع قواعد فرز تلقائي اختيارية |
| GET /labels/:id | get_label | استرجاع تصنيف بمعرّفه أو اسمه |
| PATCH /labels/:id | update_label | إعادة تسمية تصنيف أو تغيير لونه أو تحويله إلى مجموعة |
| DELETE /labels/:id | delete_label | حذف تصنيف دون حذف رسائله |
| POST /labels/:id/rules | create_label_rule | إضافة قاعدة فرز تلقائي إلى تصنيف |
| DELETE /labels/:id/rules/:rule_id | delete_label_rule | حذف قاعدة فرز تلقائي |
| POST /drafts | create_draft | إنشاء مسودة في المحرّر |
| GET /drafts | list_drafts | عرض مسودات المحرّر |
| GET /drafts/:id | get_draft | استرجاع مسودة ومرفقاتها |
| PUT /drafts/:id | update_draft | استبدال محتوى مسودة |
| DELETE /drafts/:id | delete_draft | تجاهل مسودة |
| POST /drafts/:id/attachments | upload_attachment | رفع مرفق إلى مسودة |
| GET /attachments/:id | download_attachment | تنزيل مرفق خاص |
| DELETE /attachments/:id | delete_attachment | حذف مرفق خاص |
| GET /sending-identities | list_sending_identities | عرض هويات الإرسال الموثَّقة |
| GET /templates | list_templates | عرض القوالب المستضافة |
| POST /templates | create_template | إنشاء قالب مستضاف |
| GET /templates/:id | get_template | استرجاع المسودات والإصدارات المنشورة والاستخدام |
| PUT /templates/:id/draft | update_template_draft | الحفظ التلقائي لمسودة قالب |
| POST /templates/:id/draft | create_template_draft | إنشاء مسودة جديدة من الإصدار المنشور |
| POST /templates/:id/render | render_template | توليد المخرجات الدقيقة كما يُنتجها الخادم |
| POST /templates/:id/test | send_template_test | إرسال لقطة اختبارية |
| POST /templates/:id/publish | publish_template | نشر إصدار قالب غير قابل للتعديل |
| POST /templates/:id/archive | archive_template | أرشفة قالب |
| POST /templates/:id/restore | restore_template | استعادة قالب مؤرشف |
| POST /domains | add_domain | إضافة نطاق إرسال |
| GET /domains | list_domains | عرض النطاقات وحالة DNS المخزَّنة مؤقتًا |
| GET /domains/:id | get_domain | استرجاع تفاصيل إعداد النطاق |
| POST /domains/:id/verify | verify_domain | Refresh domain and DNS verification |
| POST /domains/:id/inbound/setup | setup_inbound | Provision inbound receiving |
| POST /domains/:id/inbound/verify | verify_inbound | التحقق من توجيه MX الوارد |
| DELETE /domains/:id | delete_domain | حذف نطاق |
| GET /dns/provider | get_dns_provider | اكتشاف مزوّد DNS المعتمد ومضيفات السجلات النسبية |
| GET /dns/domain-connect/connect | get_domain_connect_link | إنشاء رابط موافقة 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 |
| POST /deliverability/score | score_email | Score an email's content before it is sent |
| GET /emails/:id/delivery | email_delivery | Delivery timeline for one email, with bounce and complaint reasons |
| GET /threads/:id/delivery | thread_delivery | Per-thread delivery counts and per-message failure reasons |
| GET /suppressions | list_suppressions | عرض عناصر قائمة المنع في مساحة العمل |
| DELETE /suppressions/:email | remove_suppression | إزالة عنصر منع ناتج عن ارتداد مؤهَّل للإزالة |
| GET /blocked-recipients | list_blocked_recipients | عرض الارتدادات والشكاوى وطلبات إلغاء الاشتراك |
| GET /webhooks | غير مكشوفة | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| POST /webhooks | غير مكشوفة | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| GET /webhooks/:id | غير مكشوفة | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| PATCH /webhooks/:id | غير مكشوفة | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| DELETE /webhooks/:id | غير مكشوفة | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| POST /webhooks/:id/rotate-secret | غير مكشوفة | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| POST /webhooks/:id/test | غير مكشوفة | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| GET /webhooks/:id/deliveries | غير مكشوفة | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| GET /webhooks/:id/deliveries/:deliveryId | غير مكشوفة | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| POST /webhooks/:id/deliveries/:deliveryId/retry | غير مكشوفة | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| GET /contacts | list_contacts | List contacts |
| POST /contacts | create_contact | Add a contact with its consent basis |
| PUT /contacts | upsert_contact | Create or update a contact by email |
| POST /contacts/bulk | bulk_update_contacts | Tag, move, unsubscribe, or delete many contacts at once |
| GET /contacts/export | غير مكشوفة | Image uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated). |
| GET /contacts/:id | get_contact | Retrieve a contact by ID or email |
| PATCH /contacts/:id | update_contact | Update a contact's name, fields, or tags, or unsubscribe it |
| DELETE /contacts/:id | delete_contact | Delete a contact and its list memberships |
| POST /contact-imports | import_contacts | Import contacts from CSV |
| GET /contact-imports | list_contact_imports | List recent contact imports |
| GET /tags | list_tags | List contact tags with how many contacts carry each |
| GET /contact-fields | list_contact_fields | List custom contact field definitions |
| PUT /contact-fields/:key | set_contact_field | Define or change a custom contact field |
| DELETE /contact-fields/:key | delete_contact_field | Delete a custom field definition |
| GET /segments | list_segments | List saved segments with live counts |
| POST /segments | create_segment | Save a segment |
| POST /segments/preview | preview_segment | Count and sample the contacts that match unsaved conditions |
| GET /segments/:id | get_segment | Retrieve a segment and its live count |
| PATCH /segments/:id | update_segment | Rename a segment or change its conditions |
| DELETE /segments/:id | delete_segment | Delete a segment |
| GET /lists | list_lists | List contact lists with member counts |
| POST /lists | create_list | Create a list with an optional signup form, welcome email, and newsletter site |
| GET /lists/:id | get_list | Retrieve a list |
| PATCH /lists/:id | update_list | Rename a list or change its signup form, welcome email, or site |
| DELETE /lists/:id | delete_list | Delete a list without deleting its contacts |
| POST /lists/:id/contacts | add_list_contacts | Add existing contacts to a list |
| DELETE /lists/:id/contacts/:contact_id | remove_list_contact | Remove a contact from a list |
| GET /broadcasts | list_broadcasts | List broadcasts |
| POST /broadcasts | create_broadcast | Create a broadcast draft |
| GET /broadcasts/:id | get_broadcast | Retrieve a broadcast and its delivery totals |
| PATCH /broadcasts/:id | update_broadcast | Edit a draft broadcast |
| DELETE /broadcasts/:id | delete_broadcast | Delete a draft broadcast |
| GET /broadcasts/:id/checks | check_broadcast | Run the pre-send checks for a broadcast |
| POST /broadcasts/:id/test | send_broadcast_test | Send a test copy of a draft |
| POST /broadcasts/:id/schedule | schedule_broadcast | Schedule a draft to send later |
| POST /broadcasts/:id/unschedule | unschedule_broadcast | Unschedule a draft |
| POST /broadcasts/:id/duplicate | duplicate_broadcast | Copy a broadcast into a new draft |
| POST /broadcasts/:id/send | send_broadcast | Send a broadcast to its audience |
| POST /broadcasts/:id/send-more | send_broadcast_to_more | Send a sent broadcast to more of its audience |
| POST /broadcasts/:id/cancel | cancel_broadcast | Cancel a draft or sending broadcast |
| GET /broadcasts/:id/recipients | list_broadcast_recipients | List a broadcast's recipients, outcomes, and engagement |
| GET /broadcasts/:id/report | get_broadcast_report | Retrieve a broadcast's engagement report |
| GET /campaigns/overview | get_campaign_overview | Retrieve subscriber growth and recent broadcast performance |
| GET /newsletter-settings | get_newsletter_settings | Retrieve newsletter settings |
| PATCH /newsletter-settings | update_newsletter_settings | Change newsletter settings |
| POST /uploads/images | غير مكشوفة | Image uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated). |
| GET /uploads/images | list_uploaded_images | List recently uploaded images |
| POST /events | track_event | Record something a contact did |
| POST /events/batch | غير مكشوفة | History import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries. |
| GET /automations | list_automations | List automations with their 30-day totals |
| POST /automations | create_automation | Create an automation as a draft |
| GET /automations/:key | get_automation | Retrieve an automation with its emails |
| PATCH /automations/:key | update_automation | Edit an automation |
| DELETE /automations/:key | delete_automation | Delete an automation and its history |
| PUT /automations/:key/steps/:position | set_automation_step | Create or change one email of an automation |
| DELETE /automations/:key/steps/:position | delete_automation_step | Remove one email from an automation |
| PUT /automations/:key/steps/:position/variants/:locale | set_automation_step_variant | Create or change a language version of an email |
| POST /automations/:key/steps/:position/test | send_automation_test_email | Send one email of an automation to yourself as a test |
| POST /automations/:key/test | send_automation_test | Send every email of an automation to yourself as tests |
| POST /automations/:key/status | set_automation_status | Turn an automation on or off |
| POST /automations/:key/enroll | enroll_contact | Add a contact to an automation |
| POST /automations/:key/exit | exit_contact | Take a contact out of an automation |
| GET /automations/:key/preview | preview_automation | Dry run: what each person in an automation would get now |
| GET /automations/overview | get_automations_overview | Totals and a daily series across every automation |
| GET /automations/:key/report | get_automation_report | Results of one automation, with one row per email |
| GET /automations/:key/people | list_automation_people | List the people in an automation by what they did |
| GET /automations/:key/people/:contact_id | get_automation_person | One person's history in an automation |
| POST /automations/:key/import-history | غير مكشوفة | History import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries. |
| GET /automation-settings | get_sending_limits | Retrieve the workspace's sending limits for automations |
| PUT /automation-settings | update_sending_limits | Change the workspace's sending limits for automations |
| GET /automation-library | list_automation_templates | List the template library: ready-made lifecycle emails |
| GET /automation-library/:id | get_automation_template | Read one template or set, with the email as it will look |
| POST /automation-library/:id/use | use_automation_template | Create a draft automation from a template or set |
| GET /events | list_events | List what contacts did, newest first |
| GET /events/names | list_event_names | List the kinds of event recorded in the last 30 days |
| POST /events/preview | غير مكشوفة | These answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events. |
| GET /connections | list_connections | List the workspace's connections (incoming webhooks) |
| POST /connections | create_connection | Create a connection and get its address |
| POST /connections/test | غير مكشوفة | These answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events. |
| GET /connections/:id | get_connection | Retrieve a connection with its last deliveries |
| PATCH /connections/:id | update_connection | Change a connection or switch it on or off |
| DELETE /connections/:id | delete_connection | Delete a connection |
| POST /connections/:id/address | غير مكشوفة | The address is a credential: whoever holds it can record events for the workspace. Replacing it cuts off the system that uses the old one, so a person does it in the dashboard, next to that system's own settings. |
| GET /account | get_account | استرجاع الحساب والاستخدام وحالة الفوترة وأعداد مساحة العمل بمفتاح API |
| GET /account/diagnostics | get_account_diagnostics | Diagnose sending and receiving problems in the workspace |
| GET /analytics | get_analytics | استرجاع تحليلات الإرسال في لوحة التحكم لمدة 7 أو 30 أو 90 يومًا |
| GET /profile | get_account | النظير الخاص بالجلسات فقط لـ GET /account؛ ويقرأ خادم MCP مسار مفتاح API. |
| POST /billing/checkout | غير مكشوفة | تغييرات الفوترة مخصصة للجلسات فقط بحكم التصميم وتتطلب مالك الحساب في لوحة التحكم. يمكن قراءة حالة الفوترة بـ get_account. |
| POST /billing/cancel | غير مكشوفة | تغييرات الفوترة مخصصة للجلسات فقط بحكم التصميم وتتطلب مالك الحساب في لوحة التحكم. يمكن قراءة حالة الفوترة بـ get_account. |
| POST /keys | غير مكشوفة | مستبعَدة عمدًا: يجب ألا يُنشئ الوكيل بيانات اعتماد أو يتلفها. يدير إنسان المفاتيح في لوحة التحكم. |
| GET /keys | list_api_keys | عرض البيانات الوصفية لمفاتيح API |
| DELETE /keys/:id | غير مكشوفة | مستبعَدة عمدًا: يجب ألا يُنشئ الوكيل بيانات اعتماد أو يتلفها. يدير إنسان المفاتيح في لوحة التحكم. |
غير متاحة عمدًا
| القدرة | نقاط النهاية | السبب |
|---|---|---|
| إنشاء مفاتيح API أو تدويرها أو إلغاؤها أو حذفها | POST /keys, DELETE /keys/:id | مستبعَدة عمدًا: يجب ألا يُنشئ الوكيل بيانات اعتماد أو يتلفها. يدير إنسان المفاتيح في لوحة التحكم. |
| بدء عملية دفع أو إلغاء اشتراك | POST /billing/checkout, POST /billing/cancel | تغييرات الفوترة مخصصة للجلسات فقط بحكم التصميم وتتطلب مالك الحساب في لوحة التحكم. يمكن قراءة حالة الفوترة بـ get_account. |
| إعداد DNS بنقرة واحدة عبر Cloudflare (OAuth) | GET /api/dns/cloudflare/connect | يتطلب جلسة متصفح تفاعلية وموافقة OAuth من Cloudflare. استخدم سجلات get_domain أو مضيفات get_dns_provider أو get_domain_connect_link بدلًا من ذلك. |
| التسجيل وتسجيل الدخول وتسجيل الخروج وربط حساب Google | /api/auth/* | مصادقة بشرية عبر المتصفح؛ ويصادق خادم MCP بمفتاح API. |
| نموذج الاتصال بالدعم | POST /api/contact | نموذج عام في موقع التسويق للبشر، وليس عملية في مساحة العمل. |
| Webhook endpoints and deliveries | GET /webhooks, POST /webhooks, GET /webhooks/:id, PATCH /webhooks/:id, DELETE /webhooks/:id, POST /webhooks/:id/rotate-secret, POST /webhooks/:id/test, GET /webhooks/:id/deliveries, GET /webhooks/:id/deliveries/:deliveryId, POST /webhooks/:id/deliveries/:deliveryId/retry | Webhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients. |
| Upload editor images and export contacts as CSV | POST /uploads/images, GET /contacts/export | Image uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated). |
| Import an automation's send history and record events in bulk | POST /automations/:key/import-history, POST /events/batch | History import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries. |
| Move SendHQ's own win-back emails onto automations (backfill and comparison) | POST /automations/platform-backfill, GET /automations/platform-compare | Internal cutover tools for SendHQ's own workspace only: they answer nobody else, need its owner's dashboard session, and are not part of the public API or of /api/v1. The backfill enrols SendHQ's own accounts, so it is run by a person, one page at a time, after reading the dry run. |
| Replace a connection's secret address | POST /connections/:id/address | The address is a credential: whoever holds it can record events for the workspace. Replacing it cuts off the system that uses the old one, so a person does it in the dashboard, next to that system's own settings. |
| Dry runs for a sample payload and for a set of events | POST /connections/test, POST /events/preview | These answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events. |
الفهرس المقروء آليًا: /docs/mcp/tools.json (المخططات والتوصيفات وربط نقاط النهاية والاستثناءات). نسخة Markdown من هذه الصفحة: /docs/mcp.md. وعند تثبيت CLI، تطبع sendhq commands --format json الفهرس نفسه.