تخطَّ إلى المستندات
قاعدة المعرفة

واجهة API للبريد

أرسل رسالة واحدة أو مئة في كل استدعاء، الآن أو لاحقاً، وأعد المحاولة دون إرسال مرتين.

التفاصيل

  • يرسل POST /emails رسالة واحدة، ويرسل POST /emails/batch حتى 100 رسالة مستقلة. الدفعة لا تكون أبداً كل شيء أو لا شيء: العنوان الخاطئ في العنصر 7 يُفشل العنصر 7، ويذهب الباقي، ويبلغ الرد عن كل عنصر على حدة.
  • يأتي المحتوى من مصدر واحد فقط: html و/أو text، أو قالب محفوظ بالمعرّف أو الاسم المختصر (ثبّت نسخته إن كان النص لشخص آخر)، أو مسودة موجودة. ترافقه حتى 10 وسوم وتعود مع كل قراءة.
  • يمسك scheduledAt الرسالة حتى 365 يوماً، كلحظة بصيغة ISO 8601 أو كمدة مثل PT1H. ويمنح cancellableForSeconds الإرسال الفوري مهلة تراجع حتى 900 ثانية. يمكن إلغاء أيٍّ منهما، وإعادة جدولة الإرسال المجدول، حتى يغادر.
  • يحمل كل إرسال مفتاح Idempotency-Key يُحجز قبل إرسال أي شيء، لذا تعيد إعادة المحاولة بعد انتهاء المهلة النتيجة الأولى مع Idempotency-Replayed: true. والمفتاح نفسه مع محتوى مختلف يُرفض بالخطأ idempotency_key_reuse.
  • لكل إرسال معرّف msg_ منذ لحظة قبوله. يقرؤه GET /emails/{id}، ويعطي /events أثر كل مستلم، و/tracking مرات الفتح والنقر.
  • أضف translate فتُسلَّم الرسالة بلغة المستلم. تُترجم عند قبول الطلب، فيحمل الإرسال المجدول الصياغة التي وافقت عليها، والترجمة التي يتعذّر إنتاجها ترفض الإرسال بدل الرجوع إلى الأصل.
  • المرفقات: حتى 20 ملفاً، والمضمّنة منها حتى 5 ميغابايت إجمالاً. يُرسل الملف الأكبر بتسمية ملف في مساحة العمل بمعرّفه، فيسافر كرابط تنزيل.
  • ما ينقص: لا يوجد وضع اختبار بعد، لذا يسلّم كل مفتاح فعلاً، وسجل الإرسال بلا حالة ارتداد. يُوسَم الارتداد على المحادثة ويُطلق كـ webhook ‏email.bounced، بينما يظل GET /emails يعرض sent.
  • قائمة المنع، أي «العناوين المحظورة» في الإعدادات، متاحة في الواجهة البرمجية أيضًا. يقرؤها GET /suppressions مع بحث ومرشّح للسبب، ويحظر POST /suppressions عنوانًا يدويًا، ويسمح DELETE /suppressions/{id} بعنوان من جديد، إلا الارتداد الدائم فإنه يبقى. وتفعل حزمة SDK وخادم MCP الشيء نفسه، وكل تغيير يطلق خطاف الويب suppression.added أو suppression.removed.