للمطورين · الواجهة البرمجية

واجهة هيو ميل البرمجية (REST API)

أرسل البريد التشغيلي، واقرأ أحداث التسليم، وزامن جهات الاتصال والطلبات من أنظمتك عبر api.hyonova.com.

  • العنوان الأساسي https://api.hyonova.com
  • مفاتيح API بصيغة Bearer وبصلاحيات محددة
  • 600 طلب في الدقيقة لكل مفتاح
خادم وحاسوب محمول يتبادلان الطلبات، بحماية مفتاح واجهة برمجية.

نظرة سريعة

ما هي؟

الواجهة البرمجية العامة لهيو ميل. ترسل خوادمك البريد التشغيلي، وتقرأ سجل الرسائل، وتزامن جهات الاتصال والتحويلات بـJSON عبر HTTPS.

لمن هي؟

للمطورين الذين يرسلون الإيصالات والتأكيدات وتنبيهات الحسابات من منتجاتهم، وللفرق التي تزامن جهات الاتصال من نظام آخر.

كم تكلّف؟

الواجهة مشمولة في كل الخطط، وكل رسالة تستهلك رصيد بريد واحداً، ولا تفرض خطتك حصة شهرية ولا سقفاً يومياً.

نقاط النهاية

إرسال رسالة

POST /mail/v1/send يضع رسالة واحدة في الطابور من قالب بمتغيرات أو من موضوع وHTML، ويرد بـ202 مع معرّف الرسالة.

سجل الرسائل

GET /mail/v1/messages يعرض الرسائل من الأحدث، مع تصفية بالحالة أو المستلم أو الوسم أو التاريخ وتقسيم الصفحات بالمؤشر.

رسالة واحدة

GET /mail/v1/messages/{id} يعيد الرسالة مع أحداث تسليمها.

جهات الاتصال

GET وPOST على /mail/v1/contacts لعرض جهات الاتصال وإنشاء جهة أو تحديثها بالبريد مع موافقتها.

التحويلات

POST /mail/v1/conversions يسجّل طلباً أو تحويلاً آخر لإسناده إلى الحملات.

النماذج

GET /mail/v1/forms يعرض نماذج الاشتراك الفعّالة لديك.

فحص المفتاح

GET /mail/v1/me يعيد الشركة وصلاحيات المفتاح وحدودك.

OpenAPI

GET /mail/v1/openapi.json يعيد وثيقة OpenAPI 3.0 دون مفتاح.

أرسل أول رسالة

وثّق مُرسِلاً

وثّق نطاقك (DKIM وSPF وDMARC) وأضف مُرسِلاً في هيو ميل، ومن دونه ترفض الواجهة الإرسال برمز 409.

أنشئ مفتاحاً

من البريد › الأتمتة › مفاتيح API فعّل صلاحية الإرسال وانسخ المفتاح. يبدأ بـhnm_ ويُعرض مرة واحدة.

اتصل بالواجهة

أرسل طلب POST إلى https://api.hyonova.com/mail/v1/send مع مفتاحك بصيغة Bearer، والمستلم، وقالب أو HTML.

اجعل الإعادة آمنة

أرسل مفتاح تكرار آمن مع الطلب، فتكراره يعيد النتيجة الأولى بدل الإرسال مرتين.

مبنية للاستخدام الفعلي

أخطاء واضحة

أخطاء JSON برمز ومعرّف طلب، وحالات HTTP قياسية، مثل 402 حين تنفد الأرصدة.

ترويسات حدود المعدل

كل رد يبيّن الحد وعدد الطلبات المتبقية ووقت تجدد الحد.

أرصدة عادلة

الرسالة التي ترفضها خدمة البريد نهائياً يُعاد رصيدها.

أسئلة وأجوبة

ما الصلاحيات المتاحة؟

صلاحية للإرسال، وأخرى لقراءة الأحداث، واثنتان لقراءة جهات الاتصال وكتابتها، وواحدة لتسجيل التحويلات، وصلاحية خاصة بإضافة WordPress. أسماؤها الدقيقة في المرجع.

ماذا يحدث إذا نفدت الأرصدة؟

يرد الإرسال برمز 402 ولا يُوضع شيء في الطابور. أضف أرصدة وأرسل مجدداً بمفتاح تكرار جديد.

هل أستطيع إرسال HTML خاص بي؟

نعم. أرسل عنواناً وHTML بدل معرّف القالب، ويُزال المحتوى غير الآمن.

كيف أعرف أن الرسالة وصلت؟

اقرأها عبر GET /mail/v1/messages/{id}، أو اشترك في Webhooks التسليم والارتداد.

أرسل البريد من منتجك

ابدأ مجاناً، ووثّق نطاقك، وأنشئ أول مفتاح API.