API कुंजियाँ
`keys->list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete`, `rotate` और `revoke`, और request log, activity और stats पढ़ने वाले मेथड।
हर मेथड
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 में, secret लौटाती हैं। हर read इसके बजाय maskedKey लौटाता है। update enabled से कुंजी को बंद और चालू करता है, जो revoke का पलटा जा सकने वाला विकल्प है, और delete सिर्फ़ उस कुंजी को हटाता है जो revoke हो चुकी है: कोई और कुंजी 409 not_revoked है, जो ConflictException के रूप में throw होता है। पढ़ने के लिए keys:read और हर बदलाव के लिए keys:manage चाहिए।
list एक OpenEmail\Result\Page लौटाता है, listAll हर कुंजी एक array में लौटाता है, और iterate एक Generator लौटाता है जो एक बार में एक कुंजी yield करता है। create और update बॉडी को API के नामों वाले एक array के रूप में लेते हैं, और revoke reason वाला एक वैकल्पिक array लेता है। OAuth access टोकन इन कॉल तक तभी पहुँचता है जब ऐप जोड़ने वाला व्यक्ति वर्कस्पेस का मालिक हो। किसी और के टोकन को errorCode में owner_only वाला PermissionException मिलता है।
पैकेज create या rotate को कभी retry नहीं करता। खोए हुए जवाब के बाद retry करने से दूसरी कुंजी बन जाती, या पहले प्रयास द्वारा लौटाया गया secret अमान्य हो जाता। update और revoke नेटवर्क विफलता के बाद retry किए जाते हैं, क्योंकि उन्हें दोहराने से वही कुंजी रहती है, और delete नहीं।
कभी कॉल करने वाले से ज़्यादा व्यापक नहीं
कोई कुंजी अपने से व्यापक कुंजी न कभी बनाती है न उस तक पहुँचती है। scopes, भूमिका, समाप्ति, mode और send scope सब कॉल करने वाली कुंजी के भीतर होने चाहिए, वरना कॉल errorCode में beyond_caller_authority वाला PermissionException throw करती है, और param उस धुरी का नाम देता है। कुछ डोमेन या पतों तक सीमित कुंजी सिर्फ़ अपने send scope के भीतर की कुंजियाँ देखती है। कॉल करने वाली कुंजी पर 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: देता है, array या कॉमा से अलग की गई एक स्ट्रिंग के रूप में। हर एक के साथ एक listAll और एक iterate जुड़वाँ है, जैसे listAllRequests और iterateRequests। ये since: और until: को DateTimeInterface या ISO 8601 स्ट्रिंग के रूप में लेते हैं, और रिक्वेस्ट पढ़ने वाले failedOnly: भी लेते हैं।
stats पढ़ता है कि कुंजियों ने एक अवधि में क्या किया: उन्होंने कौन-सी मेल भेजी और उसका क्या हुआ, कौन-सी कॉल अस्वीकार हुईं, उन्होंने कौन-सी रिक्वेस्ट कीं और कौन-से routes कॉल किए। यह वही keyIds:, since: और until: लेता है, साथ में grain: और offsetMinutes:, कोई अवधि न बताने पर अभी से पहले के 30 दिन कवर करता है, और इसे keys:read के साथ emails:read चाहिए।
until: का since: से बाद का होना ज़रूरी है, वरना कॉल errorCode में invalid_parameter और param में until वाला InvalidRequestException throw करती है। DateTimeInterface UTC में भेजा जाता है, और स्ट्रिंग जैसी लिखी है वैसी भेजी जाती है, इसलिए उसे 2026-09-01T00:00:00Z जैसा ISO 8601 timestamp होना चाहिए।