خادم SendHQ MCP

ما هذا الخادم

يتيح خادم SendHQ MCP لوكيل ذكاء اصطناعي تشغيل مساحة عمل SendHQ واحدة عبر بروتوكول سياق النموذج (Model Context Protocol): إرسال البريد (المفرد والدفعي وبالقوالب والردود والمرفقات وإعادة المحاولة غير المكرِّرة)، وقراءة البريد المرسل والمستلَم والبحث فيه (الموضوعات والنصوص وأسماء المرفقات) وأحداث تسليمه، وتنظيم البريد في تصنيفات بقواعد فرز تلقائي، وإدارة المسودات والمرفقات الخاصة، وتأليف القوالب المستضافة ونشرها، وإضافة النطاقات وتوثيقها مع DNS الخاص بها، وإعداد استقبال البريد الوارد وعناوينه، وفحص قابلية التسليم والارتدادات والشكاوى وقوائم المنع، وقراءة استخدام الحساب وحالة الفوترة والتحليلات والبيانات الوصفية لمفاتيح API.

وهو خادم stdio محلي مدمج في الملف التنفيذي لـ CLI باسم sendhq. يشغّل عميل MCP لديك الأمر sendhq mcp بوصفه عملية فرعية ويتخاطب بـ JSON-RPC عبر stdin/stdout. وكل استدعاء أداة يتحول إلى طلب موثَّق واحد إلى SendHQ REST API على https://sendhq.cc/api/v1 بمصادقة مفتاح API الخاص بمساحة عملك، فتكون لخادم MCP صلاحيات ذلك المفتاح تمامًا ولا تزيد.

• 59 أداة في 8 مجموعات، مولَّدة من فهرس واحد يُنشَر أيضًا بصيغة tools.json.
• مخططات JSON Schema صارمة: تُرفض الوسائط غير المعروفة والأنواع الخاطئة والحقول المطلوبة المفقودة محليًا قبل أن يصل أي شيء إلى SendHQ.
• أخطاء منظَّمة تتضمن code ثابتًا، وstatus بحالة HTTP، وexplanation، وremedy ملموسًا، وما إذا كانت إعادة المحاولة قد تفيد.
• كل أداة ترسل بريدًا حقيقيًا أو تتلف بيانات تنص على ذلك في أولى كلمات وصفها وتحمل توصيفات أمان MCP.
• يُخفي وضع --read-only كل أداة إرسال وكل أداة تُغيّر الحالة.
• لا يُسجَّل شيء. يحمل stdout رسائل البروتوكول فقط؛ ولا يصل مفتاح API ولا محتوى الرسائل إلى أي سجل.

استخدم SendHQ في Claude وChatGPT

لا حاجة إلى تثبيت: تشغّل SendHQ هذا الخادم أيضًا بوصفه موصّلًا (connector) مستضافًا على https://mcp.sendhq.cc/mcp بالأدوات نفسها. وتسجّل الدخول بحساب SendHQ بدل لصق مفتاح.

Claude

1. افتح Settings ← Connectors وابحث عن SendHQ في الدليل، أو اختر Add custom connector والصق https://mcp.sendhq.cc/mcp.
2. انقر Connect، وسجّل الدخول إلى SendHQ، وراجع الصلاحيات ثم انقر Allow.
3. اطلب من Claude فحص صندوق الوارد، أو إرسال رسالة من نطاقك الموثَّق، أو شرح سبب ارتداد.

ChatGPT

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

Muse by Meta

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

الموافقة وقطع الاتصال

• The request_feature tool sends a feature request to the SendHQ team with your account details, so we can follow up by email.
• الأدوات التي ترسل بريدًا حقيقيًا أو تحذف بيانات موسومة بذلك. وما إذا كان المساعد يسألك أولًا يُضبط لكل أداة في المساعد نفسه: في Claude، اختر Needs approval لتلك الأدوات ضمن Settings ← Connectors ← SendHQ.
• يحصل الموصّل على مفتاح API خاص به، يحمل اسم المساعد (مثل «Claude (AI connector)»). احذفه ضمن API Keys لقطع الاتصال فورًا.
• لا يستطيع إنشاء مفاتيح API أو إلغاءها ولا تغيير الفوترة. تُرسَل المرفقات وتُعاد بترميز base64؛ ولا يوجد وصول إلى الملفات المحلية.
• لا يمكن لمساحات العمل غير المدفوعة (الفترة التجريبية للتكامل) التسليم إلا إلى البريد الإلكتروني للحساب أو إلى عنوان محاكاة في AWS SES.

للاستفسارات: postmaster@sendhq.cc. الخصوصية: sendhq.cc/privacy.

التثبيت

ثبّت الملف التنفيذي sendhq (Linux وmacOS وWindows على x86-64 وarm64). يتحقق المثبّت من المجموع الاختباري للإصدار ويضع الملف التنفيذي في ~/.local/bin افتراضيًا.

curl -fsSL https://downloads.sendhq.cc/install.sh | sh

irm https://downloads.sendhq.cc/install.ps1 | iex

sendhq version
SENDHQ_API_KEY=re_your_key sendhq doctor

أنشئ مفتاح API في لوحة التحكم على https://sendhq.cc/app#/keys. لا يستطيع خادم MCP إنشاء المفاتيح. والأمر الوحيد الذي يشغّل الخادم هو:

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؛ ويُبقي الملف التنفيذي المحلي المفتاح على الجهاز الذي يحتفظ به أصلًا.

البيئة والخيارات

يُرسَل المفتاح فقط في الترويسة Authorization: Bearer إلى عنوان URL الأساسي المضبوط. ولا يُطبع ولا يُسجَّل ولا يتردد في الأخطاء ولا يُدرج في نتائج الأدوات.

نموذج الأمان للوكلاء

• يرسل بريدًا حقيقيًا. تسلّم send_email وsend_batch وsend_template_test الرسائل إلى أشخاص حقيقيين وتستهلك أرصدة التسليم. تبدأ أوصافها بعبارة SENDS REAL EMAIL. لا تستدعها إلا عندما يطلب المستخدم صراحةً إرسال تلك الرسالة بعينها، بعد تأكيد المستلِمين والمُرسِل والمحتوى.
• مُتلِفة. الأدوات delete_email وdelete_draft وdelete_attachment وdelete_domain وdelete_inbox وremove_suppression موسومة بـ destructiveHint: true وتبدأ أوصافها بـ DESTRUCTIVE. أكّد مع المستخدم أولًا. تُضعف remove_suppression حاجز أمان ولا تناسب إلا عندما يؤكد إنسان أن العنوان يعمل مجددًا.
• تغيّر الحالة. إنشاء المسودات والقوالب والنطاقات وصناديق البريد أو تحديثها، ونشر القوالب، وبدء التوثيق، كلها تغيّر مساحة العمل لكنها لا ترسل بريدًا.
• للقراءة فقط. كل ما عدا ذلك موسوم بـ readOnlyHint: true ويمكن استدعاؤه بحرية.
• لا يغيّر هذا الخادم DNS أبدًا. تُعيد add_domain سجلات ينشرها إنسان؛ وتُعيد get_domain_connect_link عنوان URL للموافقة يجب أن يفتحه شخص ويوافق عليه لدى مزوّد DNS الخاص به.
• لا يغيّر هذا الخادم الفوترة أبدًا. تقرأ get_account الباقة والاستخدام وحالة الاشتراك فقط.
• مساحات العمل غير المدفوعة (الفترة التجريبية للتكامل) لا يمكنها التسليم إلا إلى البريد الإلكتروني لمالك الحساب (get_account ← user.email) أو إلى عنوان محاكاة في AWS SES مثل success@simulator.amazonses.com، ولا يمكنها إرسال مرفقات.
• القبول ليس تسليمًا. يُعيد الإرسال الناجح معرّفًا؛ وتصل أدلة التسليم والارتداد والشكوى لاحقًا في list_email_events. لا تدّعِ أبدًا الوصول إلى صندوق الوارد أو أن شخصًا قرأ الرسالة.
• لا تبدّل إلى عنوان From مختلف للالتفاف على إيقاف 423، ولا تُعِد أبدًا إضافة مستلِمين ألغوا اشتراكهم أو قدّموا شكاوى.

مفاتيح API خارج النطاق

بحكم التصميم لا توجد أدوات تنشئ مفاتيح API أو تعدّلها أو تدوّرها أو تلغيها أو تحذفها. يجب ألا يُنشئ الوكيل بيانات اعتماد أو يتلفها. تُعيد list_api_keys الأسماء والبادئات غير السرية وأوقات آخر استخدام فقط. وتبقى إدارة المفاتيح في لوحة التحكم مع إنسان مسجَّل الدخول.

سير العمل

1. أول إرسال

1. تؤكد get_service_health أن API يمكن الوصول إليها (تعمل دون مفتاح).
2. تعرض get_account الباقة (access.tier) والحصة المتبقية وuser.email. وفي الفترة التجريبية، هذا البريد هو المستلِم الحقيقي الوحيد المسموح به.
3. تسرد list_sending_identities عناوين From التي يمكنك استخدامها. وإذا كانت فارغة، فابدأ بسير عمل النطاق.
4. أكّد المُرسِل والمستلِم والموضوع والنص مع المستخدم، ثم استخدم send_email مع idempotency_key.
5. تُظهر list_email_events مع id المُعاد الأحداث delivery أو bounce أو complaint أو reject بمجرد أن يبلّغ عنها المزوّد (عادةً بعد ثوانٍ إلى دقائق).

{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "SendHQ is connected",
    "text": "It works.",
    "idempotency_key": "first-send-2026-09-26"
  }
}

2. توثيق النطاق من البداية إلى النهاية

1. استخدم add_domain مع name: "example.com". تتضمن النتيجة سجلات DNS (سجلات DKIM من نوع CNAME، والتحقق من SES، وSPF، وDMARC الموصى به).
2. تكتشف get_dns_provider مع domain_id مزوّد DNS المعتمد وتُعيد المضيف النسبي الدقيق الذي تُدخله لكل سجل لدى ذلك المزوّد.
3. إذا كانت providers.domainConnect.available مساوية لـ true، فإن get_domain_connect_link تُعيد عنوان URL للموافقة. سلّمه إلى الإنسان؛ فلا يتغير شيء إلى أن يوافق لدى المزوّد. وإلا فسلّم الإنسان السجلات لينشرها. لا تنشر سجل SPF ثانيًا أبدًا: ادمج include:amazonses.com في قيمة v=spf1 الحالية.
4. تعيد verify_domain فحص DNS وSES. تنتقل الحالة عبر pending وchecking وpropagating إلى verified. استعلم دوريًا عبر verify_domain أو get_domain كل 30 إلى 60 ثانية؛ فقد يستغرق DNS من دقائق إلى ساعات.
5. عندما تكون status مساوية لـ verified، تظهر عناوين النطاق في list_sending_identities.

3. الارتدادات والشكاوى وقوائم المنع

1. تُعيد list_blocked_recipients كل عنوان محظور مع سببه (bounce أو complaint أو unsubscribe) وعددًا إجماليًا.
2. تُعيد list_suppressions عناصر المنع الناتجة عن الارتداد الدائم والشكاوى؛ وتعطي deliverability_stats معدلات التسليم والارتداد والشكاوى لآخر 30 يومًا؛ وتُظهر list_sender_reputation عناوين From التي خُنقت أو أُوقفت مؤقتًا.
3. يخفق الإرسال الذي يتضمن مستلِمًا مدرجًا في قائمة المنع بالخطأ 422 recipient_suppressed. أزل ذلك المستلِم وأعد الإرسال.
4. لا تستدعِ remove_suppression إلا عندما يؤكد إنسان أن صندوق بريد ارتدت رسائله صار يعمل. وعناصر المنع الناتجة عن الشكاوى دائمة (409 complaint_suppression_locked).

4. استقبال البريد الوارد

1. يجب أن يكون النطاق (وغالبًا نطاق فرعي مثل inbound.example.com) موثَّقًا.
2. تهيّئ setup_inbound الاستقبال وتُعيد سجل MX واحدًا. وينشره إنسان.
3. استخدم verify_inbound إلى أن تصبح status مساوية لـ ready.
4. تنشئ create_inbox مع domain_id وlocal_part (مثل support) العنوان support@inbound.example.com.
5. استعلم دوريًا عبر list_emails مع direction: "in" وunread: true (وinbox_id اختياريًا). اقرأ رسالة بـ get_email ومحادثتها بـ get_thread ومرفقاتها بـ download_attachment، وعلّمها على أنها عولجت بـ mark_email (read: true).
6. ردّ ضمن السلسلة بـ send_email وreply_to_email_id؛ وتضبط SendHQ قيم In-Reply-To وReferences والسلسلة.

5. Webhooks وإشعارات الأحداث

لا تقدّم SendHQ حاليًا webhooks قابلة للضبط من العميل، ولذلك لا توجد أداة webhook. تُعالَج إشعارات المزوّد داخل SendHQ وتُتاح عبر عمليات القراءة. استعلم دوريًا بدل ذلك: list_email_events لنتيجة رسالة واحدة، وlist_emails مع status (مثل bounced) أو after للتغييرات الأخيرة، وlist_emails مع direction: "in" وunread: true للبريد الوارد الجديد، وlist_blocked_recipients لعناصر المنع الجديدة. لا تستعلم أكثر من مرة واحدة تقريبًا كل دقيقة لكل سؤال.

6. تشخيص إخفاق التسليم

1. جد الرسالة: list_emails مع direction: "out" وto أو query، أو get_email إذا كان لديك المعرّف. تعني status: failed أن SendHQ أو المزوّد رفضها عند الإرسال؛ ويوضح خطأ الرسالة السبب.
2. list_email_events: bounce (دائم أو عابر، مع تشخيص المزوّد)، أو complaint، أو reject، أو delivery. وعدم وجود أحداث بعد يعني أن المزوّد لم يبلّغ؛ فانتظر وأعد الفحص.
3. إذا أخفق استدعاء الإرسال نفسه، فاقرأ code الخطأ: sender_domain_unverified ← أكمل توثيق النطاق؛ recipient_suppressed ← ارتدت رسائل العنوان ارتدادًا دائمًا أو قدّم شكوى سابقًا؛ sender_paused ← افحص list_sender_reputation وأصلح مصدر القائمة؛ trial_recipient_restricted ← حدود الفترة التجريبية؛ quota_exhausted ← استخدام get_account.
4. تتحقق get_domain من أن DKIM وSPF وDMARC لا تزال منشورة؛ وتُظهر deliverability_stats ما إذا كانت المشكلة في رسالة واحدة أم اتجاهًا عامًا.
5. أبلغ بما تُظهره الأدلة. فحدث delivery يعني أن خادم المستلِم قبِل الرسالة، لا أنها وصلت إلى صندوق الوارد أو قُرئت.

7. امتلاك مجموعة مهام (التصنيفات)

1. استخدم create_label مع name (مثل Agent/Orders) وskip_inbox: true. وهذا يحوّل التصنيف إلى مجموعة: يُؤرشَف البريد المستلَم الذي يحصل عليه، فيظهر داخل التصنيف فقط ولا يظهر أبدًا في صندوق وارد الإنسان.
2. أرسل بريد المهمة بـ send_email (أو send_batch) مع labels: ["Agent/Orders"]. وترث الردود على تلك المحادثة التصنيف تلقائيًا وتتخطى صندوق الوارد.
3. للبريد الذي يبدأ خارج محادثاتك، أضف قاعدة فرز: create_label_rule مع inbox_id (عنوان مخصص مثل orders@…) أو from أو to أو subject. ومرّر apply_to_existing: true لفرز البريد المستلَم أصلًا.
4. اعمل على المجموعة: list_emails مع label: "Agent/Orders" وdirection: "in" وunread: true؛ واقرأ بـ get_email أو get_thread، وردّ بـ send_email وreply_to_email_id، وطبّق mark_email مع read: true عند المعالجة.
5. انقل رسالة شاردة إلى تصنيف أو خارجه بـ label_email (add / remove). وإضافة تصنيف مجموعة إلى رسالة مستلَمة تؤرشفها أيضًا.
6. اختياريًا، ترسل set_inbox_forwarding نسخة من كل ما يستقبله عنوان استقبال إلى صندوق بريد آخر (يؤكد الهدف بالبريد أولًا).

{
  "name": "send_email",
  "arguments": {
    "from": "Orders <orders@example.com>",
    "to": [
      "customer@example.net"
    ],
    "subject": "Order 1042: confirm delivery window",
    "text": "Reply with a time that works.",
    "labels": [
      "Agent/Orders"
    ],
    "idempotency_key": "order-1042-window"
  }
}

8. المرفقات والقوالب

أرفق حتى 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 واحد بالضبط.

النتائج والترقيم والأخطاء

يُعيد الاستدعاء الناجح كائن 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": "trial_recipient_restricted",
    "status": 402,
    "message": "The integration trial can deliver only to your account email or an AWS SES simulator address",
    "retryable": false,
    "explanation": "This workspace is on the unpaid integration trial. Trial sends can be delivered only to the account owner's email address or an AWS SES simulator address.",
    "remedy": "Send to the account email (get_account -> user.email) or a simulator address such as success@simulator.amazonses.com to test. To email anyone else, the account owner must activate a paid plan in the dashboard (Profile & Billing). Do not retry the same recipients."
  }
}

حقول الخطأ الاختيارية: 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 في الباقات المدفوعة).
• الفترة التجريبية للتكامل: 100 مستلِم إجمالًا، فقط إلى البريد الإلكتروني للحساب أو عناوين محاكاة SES.
• المرفقات: 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.

مرجع الأدوات

كل أداة مع فئة الأمان الخاصة بها ونقطة نهاية REST التي تستدعيها ومعلماتها وشكل القيمة المُعادة ومثال على كائن معلمات tools/call. المعلمات دقيقة: يرفض الخادم أي شيء غير مدرج.

الرسائل وسلاسل الرسائل: send_email, send_batch, list_emails, get_email, mark_email, delete_email, list_email_events, get_thread
التصنيفات وقواعد الفرز التلقائي: list_labels, get_label, create_label, update_label, delete_label, create_label_rule, delete_label_rule, label_email
المسودات والمرفقات وهويات الإرسال: list_sending_identities, create_draft, list_drafts, get_draft, update_draft, delete_draft, upload_attachment, download_attachment, delete_attachment
القوالب المستضافة: list_templates, create_template, get_template, update_template_draft, create_template_draft, render_template, send_template_test, publish_template, archive_template, restore_template
النطاقات وDNS: list_domains, get_domain, add_domain, verify_domain, delete_domain, get_dns_provider, get_domain_connect_link
البريد الوارد: setup_inbound, verify_inbound, list_inboxes, get_inbox, create_inbox, update_inbox, set_inbox_forwarding, delete_inbox
قابلية التسليم والارتدادات وقوائم المنع: deliverability_stats, list_sender_reputation, list_suppressions, remove_suppression, list_blocked_recipients
الحساب والاستخدام والتحليلات والمفاتيح: get_account, get_analytics, list_api_keys, get_service_health

لا توجد أدوات تطابق عامل التصفية هذا.

الرسائل وسلاسل الرسائل

{
  "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"
  }
}

{
  "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"
  }
}

{
  "name": "list_emails",
  "arguments": {
    "direction": "in",
    "unread": true,
    "limit": 25
  }
}

{
  "name": "get_email",
  "arguments": {
    "email_id": "em_123"
  }
}

{
  "name": "mark_email",
  "arguments": {
    "email_id": "em_123",
    "read": true
  }
}

{
  "name": "delete_email",
  "arguments": {
    "email_id": "em_123"
  }
}

{
  "name": "list_email_events",
  "arguments": {
    "email_id": "em_123"
  }
}

{
  "name": "get_thread",
  "arguments": {
    "thread_id": "em_123"
  }
}

التصنيفات وقواعد الفرز التلقائي

{
  "name": "list_labels",
  "arguments": {}
}

{
  "name": "get_label",
  "arguments": {
    "label_id": "Billing"
  }
}

{
  "name": "create_label",
  "arguments": {
    "name": "Agent/Orders",
    "skip_inbox": true,
    "rules": [
      {
        "from": "@stripe.com"
      }
    ]
  }
}

{
  "name": "update_label",
  "arguments": {
    "label_id": "lbl_123",
    "name": "Finance/Billing"
  }
}

{
  "name": "delete_label",
  "arguments": {
    "label_id": "lbl_123"
  }
}

{
  "name": "create_label_rule",
  "arguments": {
    "label_id": "Billing",
    "inbox_id": "inb_123",
    "skip_inbox": true
  }
}

{
  "name": "delete_label_rule",
  "arguments": {
    "label_id": "lbl_123",
    "rule_id": "lrule_123"
  }
}

{
  "name": "label_email",
  "arguments": {
    "email_id": "em_123",
    "add": [
      "Billing"
    ],
    "remove": [
      "Support"
    ]
  }
}

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

{
  "name": "list_sending_identities",
  "arguments": {}
}

{
  "name": "create_draft",
  "arguments": {
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice"
  }
}

{
  "name": "list_drafts",
  "arguments": {}
}

{
  "name": "get_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}

{
  "name": "update_draft",
  "arguments": {
    "draft_id": "dr_123",
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice (updated)",
    "text": "Attached."
  }
}

{
  "name": "delete_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}

{
  "name": "upload_attachment",
  "arguments": {
    "draft_id": "dr_123",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_path": "/tmp/invoice.pdf"
  }
}

{
  "name": "download_attachment",
  "arguments": {
    "attachment_id": "att_123",
    "save_to_path": "/tmp/invoice.pdf"
  }
}

{
  "name": "delete_attachment",
  "arguments": {
    "attachment_id": "att_123"
  }
}

القوالب المستضافة

{
  "name": "list_templates",
  "arguments": {
    "lifecycle": "active"
  }
}

{
  "name": "create_template",
  "arguments": {
    "name": "Account welcome",
    "key": "account-welcome",
    "starter": "welcome"
  }
}

{
  "name": "get_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

{
  "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"
    }
  }
}

{
  "name": "create_template_draft",
  "arguments": {
    "template_id": "account-welcome"
  }
}

{
  "name": "render_template",
  "arguments": {
    "template_id": "account-welcome",
    "data": {
      "first_name": "Asha"
    }
  }
}

{
  "name": "send_template_test",
  "arguments": {
    "template_id": "account-welcome",
    "to": [
      "owner@example.com"
    ]
  }
}

{
  "name": "publish_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

{
  "name": "archive_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

{
  "name": "restore_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

النطاقات وDNS

{
  "name": "list_domains",
  "arguments": {}
}

{
  "name": "get_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}

{
  "name": "add_domain",
  "arguments": {
    "name": "example.com"
  }
}

{
  "name": "verify_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}

{
  "name": "delete_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}

{
  "name": "get_dns_provider",
  "arguments": {
    "domain_id": "dom_123"
  }
}

{
  "name": "get_domain_connect_link",
  "arguments": {
    "domain_id": "dom_123"
  }
}

البريد الوارد

{
  "name": "setup_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}

{
  "name": "verify_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}

{
  "name": "list_inboxes",
  "arguments": {
    "domain_id": "dom_123"
  }
}

{
  "name": "get_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

{
  "name": "create_inbox",
  "arguments": {
    "domain_id": "dom_123",
    "local_part": "support",
    "name": "Support"
  }
}

{
  "name": "update_inbox",
  "arguments": {
    "inbox_id": "inb_123",
    "status": "disabled"
  }
}

{
  "name": "set_inbox_forwarding",
  "arguments": {
    "inbox_id": "inb_123",
    "forward_to": "team@example.net"
  }
}

{
  "name": "delete_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

قابلية التسليم والارتدادات وقوائم المنع

{
  "name": "deliverability_stats",
  "arguments": {}
}

{
  "name": "list_sender_reputation",
  "arguments": {}
}

{
  "name": "list_suppressions",
  "arguments": {}
}

{
  "name": "remove_suppression",
  "arguments": {
    "email": "fixed-mailbox@example.net"
  }
}

{
  "name": "list_blocked_recipients",
  "arguments": {}
}

الحساب والاستخدام والتحليلات والمفاتيح

{
  "name": "get_account",
  "arguments": {}
}

{
  "name": "get_analytics",
  "arguments": {
    "days": 30
  }
}

{
  "name": "list_api_keys",
  "arguments": {}
}

{
  "name": "get_service_health",
  "arguments": {}
}

جرد تغطية API

كل عملية في API العامة والأداة التي تغطيها. كل ما يمكن للمستخدم فعله في لوحة التحكم ولديه API مغطًّى؛ أما الاستثناءات أدناه فمقصودة.

غير متاحة عمدًا

الفهرس المقروء آليًا: /docs/mcp/tools.json (المخططات والتوصيفات وربط نقاط النهاية والاستثناءات). نسخة Markdown من هذه الصفحة: /docs/mcp.md. وعند تثبيت CLI، تطبع sendhq commands --format json الفهرس نفسه.