مرجع 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 رسالة مخصّصة

ترويسات اختيارية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`.

معلمات الاستعلامdirectionstatusdomaininbox_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
}