واجهة Mail البرمجية

تتيح واجهة هيو ميل البرمجية لمنتجك إرسال البريد المعاملاتي — الإيصالات والتأكيدات وإشعارات الحساب — رسالةً واحدة في كل استدعاء، وقراءة حالة كل رسالة، ومزامنة جهات الاتصال. وهي جزء من هيو ميل، وتشملها كل الخطط.

العنوان الأساسي والمصادقة#

كل نقاط النهاية تحت عنوان أساسي واحد:

https://api.hyonova.com

أرسل مفتاح API كرمز حامل (bearer token) في كل استدعاء:

Authorization: Bearer YOUR_API_KEY

تبدأ المفاتيح بـ hnm_. احفظها على خوادمك فقط، ولا تضع مفتاح API في صفحة ويب أو تطبيق جوال أبداً.

يعرض البريد › الأتمتة › دليل API العنوان نفسه في حقل نقطة النهاية مع زر للنسخ.

قبل أن تبدأ#

• مرسِل موثّق. تتحقق شركتك من نطاق الإرسال الخاص بها (DKIM، وSPF عبر نطاق MAIL FROM مخصص، وDMARC) وتضيف عنوان مرسِل عليه. ومن دونه يردّ الإرسال بالرمز 409 SENDER_NOT_VERIFIED. راجع المرسلون والنطاقات والإعدادات.
• أرصدة البريد. تستهلك كل رسالة رصيد بريد واحداً. راجع الأرصدة أدناه.
• مفتاح API. يُنشئه شخص لديه صلاحية إدارة البريد — وهو افتراضياً المالك أو المدير العام.

مفاتيح API#

يعرض جدول المفاتيح بادئة كل مفتاح وصلاحياته وآخر استخدام. يوقف إلغاء المفتاح فوراً، فتردّ الاستدعاءات التي تستخدمه بالرمز 401 API_KEY_INVALID. ولا يخزّن HyoNova من كل مفتاح إلا قيمته المجزّأة (hash).

نقاط النهاية#

لتُبلَّغ بأحداث التسليم بدل أن تسأل عنها، استخدم Webhooks.

إرسال رسالة#

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

تستخدم القوالب متغيرات مثل {{ order_number }} مع قيمة بديلة اختيارية: {{ order_number | default:"—" }}. وتُدرج القيم دائماً كنص.

curl -X POST "https://api.hyonova.com/mail/v1/send" \
  -H "Authorization: Bearer $HYO_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001-confirmation" \
  -d '{
    "to": { "email": "name@example.com", "name": "Customer" },
    "templateId": "TEMPLATE_ID",
    "variables": { "order_number": "1001" }
  }'

const response = await fetch('https://api.hyonova.com/mail/v1/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HYO_MAIL_API_KEY}`, // YOUR_API_KEY
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1001-confirmation',
  },
  body: JSON.stringify({
    to: { email: 'name@example.com', name: 'Customer' },
    templateId: 'TEMPLATE_ID',
    variables: { order_number: '1001' },
  }),
});

const result = await response.json();
if (response.status !== 202) {
  throw new Error(`${result.error.code}: ${result.error.message}`);
}
console.log(result.id, result.status); // status is "queued"

<?php
$payload = json_encode([
    'to' => ['email' => 'name@example.com', 'name' => 'Customer'],
    'templateId' => 'TEMPLATE_ID',
    'variables' => ['order_number' => '1001'],
]);

$ch = curl_init('https://api.hyonova.com/mail/v1/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('HYO_MAIL_API_KEY'), // YOUR_API_KEY
        'Content-Type: application/json',
        'Idempotency-Key: order-1001-confirmation',
    ],
    CURLOPT_POSTFIELDS => $payload,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode((string) $body, true);
if ($status !== 202) {
    throw new RuntimeException($result['error']['code'] . ': ' . $result['error']['message']);
}
echo $result['id'];

الاستجابة:

{ "id": "6f1c2d4e-9a7b-4c1d-8e2f-3a4b5c6d7e8f", "status": "queued", "replayed": false }

احتفظ بقيمة id: فهي تعرّف الرسالة في سجل الرسائل وفي GET /mail/v1/messages/{id} وفي أحداث Webhooks.

منع التكرار#

أعطِ كل رسالة منطقية مفتاحها الخاص — مثل order-1001-confirmation — وأرسل المفتاح نفسه عند إعادة المحاولة بعد انتهاء المهلة أو خطأ في الشبكة.

• الترويسة Idempotency-Key تعمل مع كل نقاط النهاية من نوع POST. يُحفظ أول رد تحت المفتاح لمدة 24 ساعة لمفتاح API ذاته. وإعادة المحاولة بالمفتاح نفسه والمحتوى نفسه تعيد الرد نفسه مع الترويسة Idempotent-Replayed: true. أما المفتاح نفسه مع محتوى مختلف فيردّ بالرمز 409 IDEMPOTENCY_CONFLICT. ويصل طول مفتاح الترويسة إلى 200 حرف.
• في POST /mail/v1/send يسمّي المفتاح الرسالةَ أيضاً على مستوى شركتك كلها: أي استدعاء لاحق بالمفتاح نفسه يعيد الرسالة الأصلية مع "replayed": true ولا يرسل شيئاً جديداً. اجعل مفاتيح الإرسال في حدود 160 حرفاً.

قراءة رسالة#

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

curl "https://api.hyonova.com/mail/v1/messages/MESSAGE_ID" \
  -H "Authorization: Bearer $HYO_MAIL_API_KEY"

{
  "id": "6f1c2d4e-9a7b-4c1d-8e2f-3a4b5c6d7e8f",
  "recipient": "name@example.com",
  "subject": "Your order 1001",
  "templateId": "TEMPLATE_ID",
  "status": "delivered",
  "providerMessageId": "…",
  "errorCode": null,
  "createdAt": "2026-10-18T09:30:00.000Z",
  "sentAt": "2026-10-18T09:30:02.000Z",
  "lastEventAt": "2026-10-18T09:30:05.000Z",
  "events": [
    { "type": "sent", "at": "2026-10-18T09:30:02.000Z" },
    { "type": "delivery", "at": "2026-10-18T09:30:05.000Z" }
  ]
}

يعرض GET /mail/v1/messages الرسائل من الأحدث إلى الأقدم بالشكل { "items": [...], "nextCursor": "…" }. معاملات الاستعلام: limit (من 1 إلى 100، والافتراضي 25)، وcursor (قيمة nextCursor السابقة)، وstatus، وq (جزء من عنوان المستلم أو الموضوع)، وsince (تاريخ ووقت بصيغة ISO)، وtag (مفتاح وسم).

حالات الرسالة#

إلغاء الاشتراك من البريد التسويقي لا يوقف البريد المعاملاتي، أما الارتداد النهائي أو الشكوى فيوقفانه.

الحساب: GET /mail/v1/me#

استخدمه لفحص مفتاح. يعيد organization (id وname)، وkey (id وname وprefix وscopes وexpiresAt)، وentitlements (api وsmtp)، وlimits (requestsPerMinute وidempotencyWindowHours وkeyRotationGraceHours)، وapiVersion.

جهات الاتصال#

يعرض GET /mail/v1/contacts جهات الاتصال بالشكل { "items": [...], "nextCursor": "…" } مع المعاملات limit وcursor وstatus وq وtag وlistId. ويقبل GET /mail/v1/contacts/{id} معرّف جهة الاتصال أو عنوان بريدها.

ينشئ POST /mail/v1/contacts جهة اتصال أو يحدّثها حسب email. الحقول: email (مطلوب)، وfirstName، وlastName، وcompany، وphone، وlocale، وattributes، وtags، وlistIds (حتى 20)، وstatus (subscribed أو pending أو unsubscribed)، وconsent.

الموافقة صادقة بطبيعة التصميم:

• لا تصبح جهة الاتصال subscribed إلا إذا أرسلت معها consent — مثل { "source": "checkout opt-in", "at": "2026-10-18T09:30:00Z", "reference": "order-1001" }. ومن دونها تكون جهة الاتصال الجديدة pending ولا تتلقى بريداً تسويقياً.
• لا تستبدل الواجهة حالة أقوى أبداً: تبقى جهة الاتصال الملغى اشتراكها أو المحجوبة أو المرتدة أو المشتكية على حالها.

يكون الرد جهة الاتصال، مع created (‏true لجهة اتصال جديدة) وmarketable (‏true فقط للحالة subscribed).

curl -X POST "https://api.hyonova.com/mail/v1/contacts" \
  -H "Authorization: Bearer $HYO_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-name@example.com" \
  -d '{
    "email": "name@example.com",
    "firstName": "Sam",
    "status": "subscribed",
    "consent": { "source": "website newsletter form" }
  }'

النماذج والتحويلات#

• يعرض GET /mail/v1/forms نماذج الاشتراك النشطة مع publicId وname وfields وconsentText وdoubleOptIn وlanguage ورابط النموذج المستضاف url. وتستخدمه إضافة WordPress.
• يسجّل POST /mail/v1/conversions طلب شراء أو تحويلاً آخر، لتنسب تقارير الحملات الإيرادات إلى آخر نقرة موثّقة. الحقول: eventId (معرّفك الثابت — إرساله مرة أخرى لا يضيف الإيراد مرتين)، وeventType (purchase أو order_confirmed أو registration أو lead أو booking)، وأحد الحقول contactId أو email أو customerRef، وrevenue، وcurrency (ثلاثة أحرف، والافتراضي USD)، وstatus (completed أو refunded أو cancelled)، وrefundedAmount، وoccurredAt، وmetadata. ويردّ بالحالة 202 مع conversion وoutcome. تقبل نقطة النهاية هذه حتى 300 طلب في الدقيقة لكل مفتاح.

الأخطاء#

تأتي الأخطاء بهذا الشكل. اعتمد على code لا على نص الرسالة. وتحمل كل استجابة الترويسة X-Request-Id؛ أرفقها عند التواصل مع HyoNova.

{ "error": { "code": "SENDER_NOT_VERIFIED", "message": "Add and verify a sender before sending." } }

الأرصدة#

تستهلك كل رسالة رصيد بريد واحداً، يُحتسب مرة واحدة عند تسليم الرسالة إلى خدمة البريد:

• لا تُحتسب إعادة المحاولة مرة أخرى.
• الرسالة التي ترفضها خدمة البريد رفضاً نهائياً يُعاد رصيدها. أما الارتداد بعد قبول الرسالة فلا يُعاد رصيده.
• عندما تفرغ المحفظة يردّ POST /mail/v1/send بالرمز 402 INSUFFICIENT_CREDITS. وإذا نفدت الأرصدة بين وضع الرسالة في الطابور وإرسالها، تُعلَّم الرسالة failed مع MAIL_CREDITS_EXHAUSTED. أضف أرصدة ثم أرسلها مجدداً بمفتاح منع تكرار جديد.

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

الحدود#

• الطلبات. 600 طلب في الدقيقة لكل مفتاح API (و300 لـ POST /mail/v1/conversions). تحمل كل استجابة x-ratelimit-limit وx-ratelimit-remaining وx-ratelimit-reset، وتحمل الاستجابة 429 أيضاً retry-after.
• إيقاع التسليم. يضبط HyoNova إيقاع كل الإرسال ليبقى ضمن حدود مزوّد البريد، لذلك قد تنتظر الرسالة قليلاً بالحالة queued أو deferred قبل إرسالها.
• الحجم. html حتى 400,000 حرف، وsubject حتى 500.

سجل الرسائل#

تعرض البريد › الأتمتة › الرسائل كل رسالة أُرسلت عبر الواجهة، مع المستلم والحالة وآخر حدث. افتح أي رسالة لترى الأحداث ومعرّف الرسالة لدى المزوّد. يستطيع كل من لديه وصول إلى البريد قراءة السجل، أما تبويبا مفاتيح API وWebhooks فلمديري البريد.

ترحيل SMTP#

الحالة#