سرور MCP ‏SendHQ

این سرور چیست

سرور MCP ‏SendHQ به یک ایجنت هوش مصنوعی اجازه می‌دهد یک فضای کاری SendHQ را از طریق Model Context Protocol اداره کند: ارسال ایمیل (تکی، دسته‌ای، مبتنی بر قالب، پاسخ، پیوست، تلاش مجدد idempotent)، خواندن و جستجوی ایمیل‌های ارسالی و دریافتی (موضوع، متن و نام پیوست‌ها) و رویدادهای تحویل آن‌ها، سازمان‌دهی ایمیل‌ها در برچسب‌ها با قوانین بایگانی خودکار، مدیریت پیش‌نویس‌ها و پیوست‌های خصوصی، نوشتن و انتشار قالب‌های میزبانی‌شده، افزودن و تأیید دامنه‌ها و DNS آن‌ها، راه‌اندازی دریافت ایمیل ورودی و نشانی‌های ورودی، بررسی تحویل‌پذیری، برگشت‌ها، گزارش‌های اسپم و فهرست توقف ارسال، و خواندن میزان مصرف حساب، وضعیت صورتحساب، analytics و فراداده کلیدهای API.

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

• 59 ابزار در 8 گروه، تولیدشده از یک کاتالوگ واحد که به‌صورت tools.json نیز منتشر شده است.
• JSON Schemaهای سخت‌گیرانه: آرگومان‌های ناشناخته، نوع‌های اشتباه و فیلدهای الزامی جاافتاده پیش از رسیدن هر چیزی به SendHQ، به‌صورت محلی رد می‌شوند.
• خطاهای ساختاریافته با یک code پایدار، status ‏HTTP، یک explanation، یک remedy مشخص و اینکه آیا تلاش مجدد کمکی می‌کند یا نه.
• هر ابزاری که ایمیل واقعی ارسال می‌کند یا داده‌ای را از بین می‌برد، این موضوع را در نخستین کلمات توضیح خود اعلام می‌کند و annotationهای ایمنی 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، برای این ابزارها در Settings → Connectors → SendHQ گزینه Needs approval را انتخاب کنید.
• connector کلید API مخصوص خود را دریافت می‌کند که به نام دستیار نام‌گذاری می‌شود (برای مثال “Claude (AI connector)”). برای قطع فوری اتصال، آن را در بخش API Keys حذف کنید.
• این connector نمی‌تواند کلید API بسازد یا باطل کند یا صورتحساب را تغییر دهد. پیوست‌ها به‌صورت base64 ارسال و بازگردانده می‌شوند؛ هیچ دسترسی‌ای به فایل‌های محلی وجود ندارد.
• فضاهای کاری پرداخت‌نشده (دوره آزمایشی یکپارچه‌سازی) فقط می‌توانند به ایمیل حساب یا یک نشانی شبیه‌ساز AWS SES تحویل دهند.

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

نصب

فایل اجرایی sendhq را نصب کنید (Linux، macOS و Windows روی x86-64 و arm64). نصب‌کننده checksum نسخه را بررسی می‌کند و فایل اجرایی را به‌طور پیش‌فرض در ~/.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 مشترک، به‌جای commit کردن کلید، از متغیر محیطی به آن ارجاع دهید؛ Claude Code عبارت ${VAR} را در .mcp.json جایگذاری می‌کند.

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

OpenAI Codex

[mcp_servers.sendhq]
command = "sendhq"
args = ["mcp"]
env = { SENDHQ_API_KEY = "re_your_key" }

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

Claude Desktop

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

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

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

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

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_service_health","arguments":{}}}

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

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

کلید فقط به‌صورت هدر 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 می‌رسند. هرگز ادعا نکنید ایمیل به صندوق ورودی رسیده یا شخصی پیام را خوانده است.
• برای دور زدن توقف 423 به نشانی From دیگری تغییر ندهید و هرگز گیرندگانی را که لغو اشتراک کرده یا گزارش اسپم داده‌اند دوباره اضافه نکنید.

کلیدهای 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 است (CNAMEهای DKIM، تأیید SES، SPF، DMARC پیشنهادی).
2. get_dns_provider با domain_id ارائه‌دهنده DNS معتبر (authoritative) را تشخیص می‌دهد و host نسبی دقیقی را که باید برای هر رکورد نزد آن ارائه‌دهنده وارد شود برمی‌گرداند.
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 می‌رسد. هر 30 تا 60 ثانیه verify_domain یا get_domain را فراخوانی کنید؛ 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. وب‌هوک‌ها و اعلان رویدادها

SendHQ در حال حاضر وب‌هوک قابل‌پیکربندی برای مشتری ارائه نمی‌کند، بنابراین ابزاری برای وب‌هوک وجود ندارد. اعلان‌های ارائه‌دهنده درون 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. مالکیت یک bucket کاری (برچسب‌ها)

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

{
  "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 اضافه می‌کنند. تا زمانی که has_more برابر true است، با offset: pagination.next_offset به فراخوانی ادامه دهید.

{
  "data": [
    "…"
  ],
  "count": 50,
  "pagination": {
    "offset": 0,
    "limit": 50,
    "returned": 50,
    "total": 180,
    "has_more": true,
    "next_offset": 50
  }
}

فراخوانی ناموفق isError: true را همراه با یک خطای ساختاریافته برمی‌گرداند. به‌جای تلاش مجدد کورکورانه، از remedy پیروی کنید؛ فقط وقتی retryable برابر true است دوباره تلاش کنید.

{
  "error": {
    "code": "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 (فهرست موارد نقض schema برای invalid_arguments) و idempotent_replayed (بخش idempotency را ببینید).

idempotency

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

• تلاش مجدد باید از همان کلید و بدنه درخواست کاملاً یکسان استفاده کند. همان کلید با هر تغییری (گیرنده، موضوع، متن، هدر، داده قالب، حتی مقادیر آرگومان‌ها) 409 idempotency_conflict برمی‌گرداند.
• همان کلید، همان بدنه و درخواست اصلی تمام‌شده: SendHQ نتیجه ذخیره‌شده را بدون ارسال مجدد برمی‌گرداند. این روش امن تلاش مجدد پس از timeout یا network_error است.
• همان کلید در حالی که درخواست اصلی هنوز در حال اجراست: 409 idempotency_in_progress که پس از کمی صبر قابل تلاش مجدد است.
• یک پیام منطقی جدید به کلید جدید نیاز دارد.
• شکست‌های ذخیره‌شده نیز بازپخش می‌شوند. اگر تلاش اول شکست خورده باشد، تلاش مجدد با همان کلید همان شکست را با idempotent_replayed: true و retryable: false برمی‌گرداند. با list_emails (direction: out) مطمئن شوید چیزی ارسال نشده، علت را برطرف کنید و سپس با یک کلید جدید ارسال کنید.
• سرور هرگز به‌طور خودکار یک POST را دوباره تلاش نمی‌کند. فقط فراخوانی‌های فقط‌خواندنی GET به‌طور خودکار دوباره تلاش می‌شوند (حداکثر 3 تلاش در خطاهای شبکه، 429 و 5xx).
• send_email با attachments درون‌خطی نمی‌تواند idempotency_key بگیرد، چون چند درخواست را اجرا می‌کند. برای ارسال پیوست به‌صورت امن برای تلاش مجدد: create_draft → upload_attachment → send_email با draft_id و idempotency_key.

{
  "name": "send_email",
  "arguments": {
    "from": "Acme <billing@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "Receipt #4812",
    "text": "Thanks for your payment.",
    "idempotency_key": "receipt-4812"
  }
}

محدودیت نرخ و سهمیه‌ها

SendHQ محدودیت ثابتی برای تعداد درخواست در ثانیه API اعلام نمی‌کند. محدودیت‌هایی که ایجنت در عمل با آن‌ها روبه‌رو می‌شود، محدودیت‌های مصرف هستند که به‌صورت 429 برگردانده می‌شوند:

• تحویل ماهانه به گیرندگان برای هر پلن. هر نشانی To، Cc و Bcc یک تحویل حساب می‌شود. get_account → usage.recipientDeliveries را در برابر usage.emailQuotaMonth ببینید.
• تعداد گیرندگان روزانه برای هر نشانی From مشخص که وضعیت اعتبار آن فرستنده تعیین می‌کند (list_sender_reputation → dailyLimit، به‌طور پیش‌فرض 2,000 در پلن‌های پولی).
• دوره آزمایشی یکپارچه‌سازی: در مجموع 100 گیرنده، فقط به ایمیل حساب یا نشانی‌های شبیه‌ساز SES.
• پیوست‌ها: حداکثر 10 فایل و 10 MB برای هر پیام؛ در پلن‌های پولی 10 GB انتقال پیوست وزن‌دهی‌شده بر اساس گیرنده در ماه.
• برای هر درخواست: To + Cc + Bcc حداکثر 100 نشانی؛ send_batch حداکثر 100 پیام.
• قطع‌کننده مدار اعتبار: در یک بازه متحرک 7 روزه، برگشت‌ها یا گزارش‌های اسپم بیش از آستانه، یک نشانی From را محدود یا متوقف می‌کنند (423 sender_paused). پس از کاهش نرخ‌ها، به‌طور خودکار بازیابی می‌شود.

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

فهرست خطاها

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

مرجع ابزارها

هر ابزار همراه با کلاس ایمنی، endpoint ‏REST که فراخوانی می‌کند، پارامترها، ساختار خروجی و یک شیء params نمونه برای 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
حساب، میزان مصرف، analytics و کلیدها: 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": {}
}

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

{
  "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 (schemaها، annotationها، نگاشت endpointها، موارد مستثنا). نسخه Markdown این صفحه: /docs/mcp.md. با نصب CLI، دستور sendhq commands --format json همین کاتالوگ را چاپ می‌کند.