مرجع API

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

ارسال، دریافت، جستجو، پاسخ و بررسی رویدادهای تحویل.

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

POST/emails

کلید API

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

محتوای تراکنشی HTML، متنی یا مبتنی بر قالب میزبانی‌شده را از یک دامنه تأییدشده فضای کاری ارسال کنید. در ارسال مستقیم، اگر برای دامنه فرستنده تأییدشده فعال باشد، می‌توان message_class را روی marketing تنظیم کرد. در حالت marketing هدرهای مدیریت‌شده لغو اشتراک اضافه می‌شوند، مگر اینکه یک یکپارچه‌سازی first-party پیکربندی‌شده URL لغو اشتراک یک‌کلیکی HTTPS قابل‌مشاهده خودش را ارائه دهد.

هدرهای اختیاریIdempotency-Key

درخواست

curl https://sendhq.cc/api/v1/emails \
  -X POST \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"Acme <hello@example.com>","to":["customer@example.net"],"subject":"Welcome aboard","html":"<h1>Welcome</h1><p>Your workspace is ready.</p>","text":"Welcome. Your workspace is ready."}'

پاسخ 201

{
  "id": "em_…",
  "providerMessageId": "provider-id",
  "threadId": "em_…"
}

POST/emails/batch

کلید API

ارسال حداکثر 100 پیام شخصی‌سازی‌شده

هدرهای اختیاریIdempotency-Key

درخواست

curl https://sendhq.cc/api/v1/emails/batch \
  -X POST \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":[{"from":"Acme <hello@example.com>","to":["customer@example.net"],"subject":"Welcome aboard","html":"<h1>Welcome</h1><p>Your workspace is ready.</p>","text":"Welcome. Your workspace is ready."}]}'

پاسخ 201

{
  "data": [
    {
      "index": 0,
      "ok": true,
      "id": "em_…"
    }
  ],
  "count": 1,
  "successful": 1,
  "failed": 0
}

GET/emails

کلید API

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

فهرستی با ترتیب جدیدترین به قدیمی‌ترین همراه با فیلترها. `query` در موضوع‌ها، متن ایمیل‌ها، شرکت‌کنندگان و نام فایل پیوست‌ها جستجو می‌کند. `label`، `domain` و `category` یک مقدار یا فهرستی جداشده با کاما می‌پذیرند (تطابق با هر کدام)؛ برچسب‌ها می‌توانند شناسه یا نام باشند. `archived=false` نمای صندوق ورودی را برای ایمیل‌های دریافتی برمی‌گرداند. ایمیل‌های دریافتی به‌صورت `primary`، `updates` (خبرنامه‌ها، ایمیل‌های انبوه و خودکار) یا `spam` دسته‌بندی و با `important` علامت‌گذاری می‌شوند؛ اسپم کنار گذاشته می‌شود مگر اینکه `category=spam` یا `include_spam=true` باشد.

پارامترهای querydirectionstatusdomaininbox_idlabelarchivedcategoryimportantinclude_spamfromtounreadafterbeforequerylimitoffset

درخواست

curl https://sendhq.cc/api/v1/emails \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

پاسخ 200

{
  "data": [],
  "count": 0
}

GET/emails/:id

کلید API

دریافت یک ایمیل و پیوست‌های آن

درخواست

curl https://sendhq.cc/api/v1/emails/id_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

پاسخ 200

{
  "id": "em_…",
  "direction": "out",
  "status": "sent",
  "attachments": []
}

PATCH/emails/:id

کلید API

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

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

درخواست

curl https://sendhq.cc/api/v1/emails/id_value \
  -X PATCH \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"spam"}'

پاسخ 200

{
  "id": "em_…",
  "readAt": "2026-08-23T12:00:00.000Z",
  "archivedAt": null,
  "category": "spam",
  "important": false,
  "classification": "you moved it here"
}

DELETE/emails/:id

کلید API

حذف یک ایمیل نگهداری‌شده

درخواست

curl https://sendhq.cc/api/v1/emails/id_value \
  -X DELETE \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

پاسخ 200

{
  "ok": true
}

GET/emails/:id/events

کلید API

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

درخواست

curl https://sendhq.cc/api/v1/emails/id_value/events \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

پاسخ 200

{
  "data": [],
  "count": 0
}

GET/threads/:id

کلید API

دریافت یک مکالمه به ترتیب زمانی

درخواست

curl https://sendhq.cc/api/v1/threads/id_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

پاسخ 200

{
  "id": "em_…",
  "data": [],
  "count": 0
}