مفاتيح API
`keys->list` و`listAll` و`iterate` و`get` و`create` و`update` و`delete` و`rotate` و`revoke`، وقرّاء سجل الطلبات والنشاط والإحصاءات.
كل الدوالّ
use OpenEmail\Constants\ApiScopes; $key = $client->keys->create([ 'name' => 'Billing sender', 'scopes' => [ApiScopes::EMAILS_SEND], 'domainAllowlist' => ['billing.acme.com'], 'expiresInMinutes' => 60 * 24 * 90,]); file_put_contents('.openemail-billing-key', $key['token']); $client->keys->update($key['id'], ['enabled' => false]); $rotated = $client->keys->rotate($key['id']);file_put_contents('.openemail-billing-key', $rotated['token']); $client->keys->revoke($key['id'], ['reason' => 'Replaced']);$client->keys->delete($key['id']);create وrotate هما الاستدعاءان الوحيدان اللذان يعيدان سرًّا، في token، مرة واحدة. وتعيد كل قراءة maskedKey بدلًا منه. ويوقف update المفتاح ويشغّله عبر enabled، وهو البديل القابل للتراجع عن revoke، ولا يزيل delete إلا مفتاحًا أُبطل: فأي مفتاح آخر يعطي 409 not_revoked، يُرمى في صورة ConflictException. وتتطلب القراءة keys:read ويتطلب كل تغيير keys:manage.
يعيد list صفحة OpenEmail\Result\Page واحدة، ويعيد listAll كل المفاتيح في مصفوفة واحدة، ويعيد iterate كائن Generator يسلّم مفتاحًا واحدًا في كل مرة. ويأخذ create وupdate المتن في صورة مصفوفة واحدة بأسماء API، ويأخذ revoke مصفوفة اختيارية فيها reason. ولا يصل رمز وصول OAuth إلى هذه الاستدعاءات إلا حين يكون الشخص الذي ربط التطبيق مالك مساحة العمل. أما رمز أي شخص آخر فيحصل على PermissionException مع ضبط errorCode على owner_only.
لا تعيد الحزمة محاولة create أو rotate أبدًا. فإعادة المحاولة بعد استجابة ضائعة ستصنع مفتاحًا ثانيًا، أو تُبطل السر الذي أعادته المحاولة الأولى. وتُعاد محاولة update وrevoke بعد فشل في الشبكة، لأن تكرارهما يترك المفتاح نفسه، أما delete فلا.
لا يتجاوز المستدعي أبدًا
لا ينشئ المفتاح أبدًا مفتاحًا أوسع منه ولا يصل إليه. يجب أن تبقى النطاقات والدور وانتهاء الصلاحية والوضع ونطاق الإرسال كلها داخل المفتاح المستدعي، وإلا رمى الاستدعاء PermissionException مع ضبط errorCode على beyond_caller_authority، ويسمّي param المحور. والمفتاح المقيّد ببعض النطاقات أو العناوين لا يرى إلا المفاتيح الواقعة داخل نطاق إرساله. ويعمل rotate على المفتاح المستدعي نفسه أيضًا بـ keys:write، مثل $client->me->rotate().
لا يمكن تطبيق التحقق الإضافي على استدعاء يجري بمفتاح، لذا فإن keys:manage اعتماد يصنع اعتمادات. امنحه فقط لأتمتة تصدر المفاتيح، وامنح ذلك المفتاح دورًا ونطاق إرسال وانتهاء صلاحية، وراقب listWorkspaceActivity حيث يُسجَّل كل ما يفعله باسمه.
سجل الطلبات والنشاط
$failures = $client->keys->listRequests( '4c1b257a66287fd113bd89d0', failedOnly: true, since: new \DateTimeImmutable('-1 day'),);echo count($failures), PHP_EOL; foreach ($client->keys->iterateWorkspaceActivity() as $change) { echo $change['keyName'], ' ', $change['type'], ' ', $change['actor']['label'] ?? 'system', PHP_EOL;}يقرأ listRequests وlistActivity مفتاحًا واحدًا، ويقرأ listWorkspaceRequests وlistWorkspaceActivity كل المفاتيح أو تلك التي يسمّيها keyIds:، في صورة مصفوفة أو سلسلة نصية واحدة مفصولة بفواصل. ولكل منها توأما listAll وiterate إلى جانبه، مثل listAllRequests وiterateRequests. وتأخذ since: وuntil: بوصفهما DateTimeInterface أو سلسلة ISO 8601، ويأخذ قارئا الطلبات أيضًا failedOnly:.
يقرأ stats ما فعلته المفاتيح داخل نافذة زمنية واحدة: البريد الذي أرسلته وما آل إليه، والاستدعاءات المرفوضة، والطلبات التي قدّمتها، والمسارات التي استدعتها. ويأخذ keyIds: وsince: وuntil: نفسها، إضافة إلى grain: وoffsetMinutes:، ويغطي الأيام الثلاثين السابقة للحظة الحالية حين لا تحدد نافذة، ويحتاج إلى emails:read إلى جانب keys:read.
يجب أن يكون until: بعد since:، وإلا رمى الاستدعاء InvalidRequestException مع ضبط errorCode على invalid_parameter وparam على until. ويُرسَل DateTimeInterface بتوقيت UTC، وتُرسَل السلسلة النصية كما كُتبت، فيجب أن تكون طابعًا زمنيًا بصيغة ISO 8601 مثل 2026-09-01T00:00:00Z.