مرجع 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 پیام شخصی‌سازی‌شده

ارسال حداکثر 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

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

Newest-first list with filters. `query` searches subjects, bodies, participants, and attachment filenames. `label`, `domain`, and `category` accept one value or a comma-separated list (matches any); labels may be IDs or names. `outcome` filters sent mail to `bounced`, `complained`, `failed`, or `rejected` (comma-separated, matches any). `archived=false` returns the Inbox view for received mail. Received mail is classified as `primary`, `updates` (newsletters, bulk, and automated mail), or `spam`, and flagged `important`; spam is excluded unless `category=spam` or `include_spam=true`.

Query parametersdirectionstatusoutcomedomaininbox_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
}
GET/emails/:id/delivery
کلید API

Delivery timeline for one email, with bounce and complaint reasons

Delivery timeline for one email, with bounce and complaint reasons

درخواست
curl https://sendhq.cc/api/v1/emails/id_value/delivery \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
پاسخ 200
{
  "emailId": "em_123",
  "status": "bounced",
  "timeline": [],
  "count": 0,
  "limit": 50,
  "offset": 0
}
GET/threads/:id/delivery
کلید API

Per-thread delivery counts and per-message failure reasons

Per-thread delivery counts and per-message failure reasons

درخواست
curl https://sendhq.cc/api/v1/threads/id_value/delivery \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
پاسخ 200
{
  "threadId": "thr_123",
  "delivered": 0,
  "bounced": 0,
  "complained": 0,
  "failed": 0,
  "messages": []
}