کلیدهای 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 تنها فراخوانی‌هایی هستند که یک secret را، در token، یک بار برمی‌گردانند. هر خواندنی به‌جای آن maskedKey را برمی‌گرداند. update با enabled کلید را خاموش و روشن می‌کند، که جایگزین برگشت‌پذیرِ revoke است، و delete فقط کلیدی را حذف می‌کند که باطل شده باشد: هر کلید دیگری یک 409 not_revoked است که به‌صورت ConflictException پرتاب می‌شود. خواندن به keys:read و هر تغییری به keys:manage نیاز دارد.
list یک OpenEmail\Result\Page برمی‌گرداند، listAll همهٔ کلیدها را در یک آرایه برمی‌گرداند، و iterate یک Generator برمی‌گرداند که هر بار یک کلید را yield می‌کند. create و update بدنه را به‌صورت یک آرایه با نام‌های API می‌گیرند، و revoke یک آرایهٔ اختیاری با reason می‌گیرد. توکن دسترسی OAuth فقط وقتی به این فراخوانی‌ها می‌رسد که کسی که اپ را وصل کرده مالک فضای کاری باشد. توکن هر کس دیگری یک PermissionException می‌گیرد که errorCode آن برابر owner_only است.
بسته هرگز create یا rotate را دوباره امتحان نمی‌کند. تلاش دوباره پس از پاسخی گم‌شده کلید دومی می‌ساخت، یا secretی را که تلاش نخست برگردانده بود باطل می‌کرد. 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:، وقتی بازه‌ای تعیین نکنید 30 روزِ پیش از اکنون را پوشش می‌دهد، و در کنار keys:read به emails:read نیاز دارد.
until: باید دیرتر از since: باشد، وگرنه فراخوانی یک InvalidRequestException پرتاب می‌کند که errorCode آن برابر invalid_parameter و param آن برابر until است. یک DateTimeInterface به وقت UTC فرستاده می‌شود و یک رشته همان‌طور که نوشته شده فرستاده می‌شود، پس رشته باید یک مهر زمانی ISO 8601 مانند 2026-09-01T00:00:00Z باشد.