قاعدة المعرفة
REST API
واجهة HTTP API موثّقة بمفاتيح يمكن إصدارها وتحديد نطاقها وإبطالها.
التفاصيل
- مفعّلة في كل مكان. تقدّم API 104 عمليات موثّقة عبر 68 مسارًا (emails وthreads وdrafts وlabels وcontacts وaudiences وdomains وtemplates وrules وroles وmembers وsettings وcalendar وtracking وwebhooks والحساب) خلف مستند OpenAPI 3.1 ملتزَم به يمكنك قراءته من دون مفتاح عبر GET /openapi.json. ويُحدَّد الوصول بمفتاح مساحة العمل الذي تصدره في Settings.
- الاستدامة التي كان هذا ينتظرها صارت جاهزة. يكتب الإرسال سطرًا قبل إرسال أي شيء، بمعرّف عام على هيئة msg_ يتبعه 24 رمزًا ست عشريًا، وGET /emails/{id} يحلّه، إلى جانب /events لمسار كل مستلم و/tracking لعمليات الفتح والنقر. ويُطالَب بـ Idempotency-Key بطول 1–255 حرفًا مقابل فهرس فريد يجمع المفتاح ومفتاح API الخاص بك معًا، فتعيد المحاولة بعد انتهاء المهلة النتيجة الأولى مع Idempotency-Replayed: true بدل الإرسال مرتين. ويجيب الإرسال بمفتاح بـ 200 بعد استقراره وبـ 202 ما دام في الطابور أو مجدولًا.
- تُصدَر المفاتيح وتُحدَّد نطاقاتها وتُدوَّر وتُبطَل في Settings → API keys. وكل مفتاح تصدره وحدة التحكم هو مفتاح oe_live_. أما البادئة oe_test_ فيفهمها المُتحقِّق ومسار الإرسال، حيث يُسجَّل الإرسال في وضع الاختبار ويُجاب عنه كأنه أُرسل من دون أن يبلغ أي ناقل، لكن لا شيء يستطيع إصدار مفتاح كهذا بعد، وتقديم الخيار قبل أن يستقر الناقل غير الفاعل فوق Durable Object سيمنحك مفتاح اختبار يسلّم البريد فعليًا. ويحمل المفتاح نطاق إرسال يصل إلى 25 نطاقًا كاملًا و50 عنوانًا مفردًا، حيث يغطي النطاق الكامل أيضًا العناوين التي تُضاف إليه لاحقًا، ومدة صلاحية اختيارية بين 1 و3650 يومًا، ودورًا اختياريًا. والدور سقف لا منحة ثانية: يعيد GET /ping النطاقات الموجودة على المفتاح والنطاقات التي أبقاها الدور له، فيصير للرد 403 على نطاق يسمّيه مفتاحك صراحة سبب ظاهر. والإبطال تحديث لا حذف، فيُبلَّغ أي استدعاء لاحق بـ revoked_api_key بدل أن يفشل في المصادقة فحسب. والتدوير يبقي كل شيء في المفتاح عدا السر: المعرّف والنطاقات ونطاق الإرسال وسجل الطلبات كلها تستمر، ويموت السر القديم لحظة إصدار الجديد، ويستطيع مفتاح يحمل keys:write أن يدوّر نفسه عبر API. وإجراءات السرد والتدوير والإبطال والتفعيل نفسها متاحة على خادم MCP لكل من يسمح له دوره بإدارة المفاتيح.
- ما هو غائب فعلًا: ليس لـ API نقطة نهاية خاصة بالرفع. تذهب المرفقات المضمّنة بترميز base64 ضمن حد إجمالي قدره 5 MB، ويُرسل الملف الأكبر بتسمية ملف موجود في مساحة العمل بمعرّفه، فيسافر على هيئة رابط تنزيل. وتُعالَج الارتدادات في صندوق البريد لا في سجل الإرسال: يُحلَّل تقرير التسليم، ويُطابَق بالرسالة الأصلية عبر Message-ID، ويوسَم على المحادثة، ويُدفع بوصفه webhook من نوع email.bounced، لكن لا شيء يكتب عائدًا إلى سطر الإرسال الذي لا تتضمن حالته وضع bounced، ولذلك تبدو الرسالة المرتدة عبر GET /emails مرسَلة كما هي. كما أن البريد المُرسل من نافذة الإنشاء في التطبيق لا يظهر في GET /emails أيضًا، لأن نافذة الإنشاء لا تكتب عبر مسار الإرسال نفسه.