Tovanix
Tovanix

API لإرسال البريد

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

  • المصادقة: مفتاح API على مستوى المستخدم المستخدم في الواجهات المفتوحة ذات الصلة على المنصة
  • الإرسال: POST /api/v1/mail/send؛ تُجمع الاستجابة بحسب المستلم، ويمثل bounced_addrs أساس تنظيف القائمة
  • منع التكرار: مع ترويسة Idempotency-Key، تُرسل الطلبات المتكررة بالمفتاح نفسه مرة واحدة فقط، دون تسليم أوفوترة مكررة
  • سلاسل الردود: مرر in_reply_to وسلسلة references كاملةً لتصل الردود إلى محادثة المستلم الأصلية
  • الحصة والنطاقات: استعلم عن الحصة المتبقية اليوم ونطاقات الإرسال الصالحة لضبط معدل الإرسال في نظامك
  • أمثلة الكود: أمثلة دنيا عاملة لـcURL / Node.js / Python / Go / PHP، مع منع التكرار ومعالجة الارتداد الدائم

POST / GET /api/v1/mail/*

نظرة عامة

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

فعّل إرسال البريد في لوحة التحكم وأضف نطاقًا واحدًا على الأقل تظهر حالته Live. يُرفض الإرسال من نطاق غير مفعّل.

المصادقة

مفتاح الحساب نفسه كبقية المنصة؛ أنشئه في الأدوات والإعدادات → إدارة API.

لوحة التحكم ← الأدوات والإعدادات ← إدارة API ← إنشاء مفتاح. يعمل المفتاح نفسه مع واجهات الطاقة والبطاقات الافتراضية والبريد وأسعار الصرف؛ والنقاط التي يستطيع استدعاءها تعتمد على الصلاحيات الممنوحة له.

إرسال بريد إلكتروني

POST /api/v1/mail/send

يجب تطابق نطاق From تمامًا مع نطاق إرسال مضاف ومباشر.

حدود الإرسال

  • إجمالي to + cc + bcc لا يزيد عن 50
  • 5 MiB للرسالة والمرفقات بعد فك الترميز
  • 998 حرفًا لا بايت؛ لا يتأثّر غير ASCII
  • حتى 32 مرفقًا؛ يلزم content_id للضمني
  • ترويسات إجمالية 16 KB و2048 بايت لكل قيمة

الاستجابة

نتائج مجمّعة لكل مستلم لا نجاح إجمالي واحد.

قد يكون لخمسة: 2 delivered و1 queued و2 hard-bounced. bounced_addrs المصدر الوحيد لتنقية القائمة؛ لا Webhook ارتداد. إن تجاهلته، تفقده وتستمر بمراسلة العنوان الميت والدفع.

منع التكرار

مع الترويسة Idempotency-Key، إعادة الإرسال بالمفتاح نفسه ترسل الرسالة مرة واحدة فقط.

في كل موضع يمكن أن يعيد استدعاؤك المحاولة تلقائيًا — انتهاء المهلات، قوائم المهام، إعادة المحاولة على مستوى SDK. من دونها، أي تعثر في الشبكة يعني أن المستلم يتلقى نسختين وأنك تُحاسَب مرتين، ولا يمكن التراجع عن أيٍّ منهما. استخدم مفتاحًا من منطق عملك مثل رقم الطلب.

ترابط الرسائل

أرفق in_reply_to و references عند الرد لتصل الرسالة إلى المحادثة الأصلية؛ من دونهما يبدأ كل رد سلسلة جديدة في صندوق المستلم. أرسل سلسلة references كاملة — مع in_reply_to وحده تنقسم المحادثات الأطول من رسالتين في بعض العملاء.

الحصة والنطاقات

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

أمثلة الشيفرة

أمثلة عاملة لكل لغة تعالج منع التكرار والارتداد الدائم.

إرسال البريد مدفوع. مفاتيح API الجديدة تشترط افتراضيًا طلبات موقّعة للنقاط المدفوعة، لذلك يستخدم كل مثال أدناه التوقيع بالإصدار 2 (أرسل الترويسة X-Sign-Version: 2). السلسلة المطلوب توقيعها 7 أسطر تُجمع بـ \n دون سطر جديد في النهاية: NEXCORE-HMAC-SHA256-V2، ثم timestamp، ثم nonce، ثم الطريقة بأحرف كبيرة، ثم المسار، ثم سلسلة الاستعلام، ثم بصمة SHA-256 للجسم بصيغة سداسية عشرية بأحرف صغيرة. قيمة X-Signature هي الصيغة السداسية العشرية بأحرف صغيرة لـ HMAC-SHA256(Secret Key, السلسلة المطلوب توقيعها). timestamp بثواني Unix، و nonce لا يتجاوز 64 بايت، وسلسلة الاستعلام بلا «?» في أولها ويجب أن تطابق ما ترسله تمامًا (سطر فارغ إن لم توجد)، وتُحسب بصمة الجسم على البايتات نفسها التي ترسلها. إذا عطّلت «اشتراط توقيع الطلبات التي تفرض رسومًا أو تصل إلى بيانات حساسة» في إعدادات المفتاح، فإن X-API-Key + X-Secret-Key وحدهما يعملان أيضًا، لكن ذلك غير موصى به.

الأسئلة الشائعة

هل يعني HTTP 200 وصول البريد إلى جميع المستلمين؟

لا. تُجمع النتائج بحسب المستلم؛ قد تكون رسالة إلى خمسة أشخاص 2 مُسلمة و1 في قائمة الانتظار و2 مرتدة نهائيًا. لا توجد إشعارات ارتداد عبر Webhook، لذا يمثل bounced_addrs أساس تنظيف القائمة الوحيد؛ أوقف الإرسال إلى تلك العناوين فورًا.

متى تلزم Idempotency-Key؟

كلما أمكن إعادة محاولة الاستدعاء تلقائيًا، مثل انتهاء المهلة أوإعادة تسليم المهام أومحاولات SDK التلقائية. دونها، قد يؤدي انقطاع شبكي إلى رسالتين وفاتورتين، ولا يمكن التراجع عنهما. استخدم مفتاح عمل مثل معرّف الطلب.

صفحات ذات صلة: وثائق الواجهة البرمجية · واجهة API موحّدة لخدمات SMTP · استخدام API موحّدة لـ SMTP

جارٍ التحميل…