مرجع API

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

أرسل الرسائل واسترجعها وابحث فيها وردّ عليها وافحص أحداث التسليم.

POST/emails
مفتاح API

إرسال رسالة واحدة

أرسل محتوى معاملاتيًا بصيغة HTML أو نص عادي أو من قالب مستضاف، من نطاق موثَّق في مساحة العمل. يمكن للإرسال المباشر ضبط message_class على marketing عند تفعيله لنطاق المُرسِل الموثَّق. يضيف النوع marketing ترويسات إلغاء اشتراك مُدارة، ما لم يوفّر تكامل مضبوط من طرف أول عنوان 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 عن المُرسِل: إذا أبلغت عن رسالة كبريد مزعج فسيُحوَّل بريده المستقبلي إلى البريد المزعج، وتتجاوز «ليست بريدًا مزعجًا» فحوص البريد المزعج التلقائية لهذا المُرسِل، وتبقى الأهمية مرتبطة به. مرّر `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": []
}