پرش به مستندات
PHP

$client->keys

هر متد در این فضای نام: امضا، پارامترها، آنچه برمی‌گرداند و یک نمونه.

متدها

Every key in the workspace: list, create, change, rotate, switch off and revoke them, never wider than the calling key, and read their request log and activity.

keys->list

List one page of the workspace's API keys

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
list(?int $limit = null, ?string $cursor = null, ?string $apiKey = null): Page

Returns one page of the workspace's keys, newest first, with what the Settings, API keys page shows: status, scopes, role, send scope, when each was last used, how often, and who made and last changed it. Revoked and expired keys stay listed until somebody deletes them. No secret is ever returned; maskedKey is enough to tell two keys apart.

A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

پارامترها

limitint

Rows per page, a whole number from 1 to 100. The server defaults to 25.

cursorstring

The nextCursor from the previous page, passed back unchanged. Never build one yourself.

apiKeystring

Overrides the client API key for this call only.

خروجی

A Page of arrays with items, hasMore and nextCursor. Each item has id, name, mode, maskedKey, keyLast4, status, scopes, roleId, roleName, addressAllowlist, domainAllowlist, expiresAt, lastUsedAt, totalUses, rotatedAt, rotationCount, deactivatedAt, revokedAt, revokedReason, createdAt, createdBy, updatedAt, updatedBy, lastChangeAt and lastChangeType. Never a secret.

نمونه

$page = $client->keys->list(); foreach ($page as $key) {    echo $key['maskedKey'], ' ', $key['name'], ' ', $key['status'], ', last used ', $key['lastUsedAt'] ?? 'never', PHP_EOL;}

نکته‌ها

  • It needs keys:read, which no key holds unless somebody gave it one.

  • The cursor is opaque: pass nextCursor back as it came.

همچنین در دسترس در

API
GET /keys
TypeScript
keys.list()
Python
keys.list()
Ruby
keys.list
CLI
openemail keys list

keys->listAll

Collect every API key into one array

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
listAll(?int $limit = null, ?string $cursor = null, ?string $apiKey = null): array

Walks every page of list and returns every key the caller can see, newest first.

پارامترها

limitint

Page size for each request, 1 to 100. The server defaults to 25.

cursorstring

Starts the walk from this cursor instead of the newest row.

apiKeystring

Overrides the client API key for every page of this walk.

خروجی

A list of arrays, one per key with the fields list returns, newest first.

نمونه

$keys = $client->keys->listAll(); $idle = array_filter($keys, static fn(array $key): bool => $key['status'] === 'active' && $key['lastUsedAt'] === null); echo implode(PHP_EOL, array_column($idle, 'name')), PHP_EOL;

همچنین در دسترس در

API
GET /keys
TypeScript
keys.listAll()
Python
keys.list_all()
Ruby
keys.list_all

keys->iterate

Stream the workspace's API keys one at a time

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
iterate(?int $limit = null, ?string $cursor = null, ?string $apiKey = null): Generator

A Generator over list, fetching a page only when the one before is drained.

پارامترها

limitint

Page size per request, 1 to 100. The server defaults to 25.

cursorstring

Starts the walk from this cursor instead of the newest row.

apiKeystring

Overrides the client API key for every page of this walk.

خروجی

A Generator that yields one key array per step.

نمونه

$weekFromNow = new \DateTimeImmutable('+7 days'); foreach ($client->keys->iterate() as $key) {    if ($key['expiresAt'] !== null && new \DateTimeImmutable($key['expiresAt']) < $weekFromNow) {        echo $key['name'], ' expires ', $key['expiresAt'], PHP_EOL;    }}

همچنین در دسترس در

API
GET /keys
TypeScript
keys.iterate()
Python
keys.iterate()
Ruby
keys.iterate

keys->get

Read one API key, without its secret

محدوده‌های دسترسیkeys:read
امضای متد
get(string $id, ?string $apiKey = null): array

Returns one key as list shows it. A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

$client->me->get() describes the calling key itself and needs no scope; this reads any key the caller can see.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

apiKeystring

Overrides the client API key for this call only.

خروجی

An array with id, name, mode, maskedKey, keyLast4, status, scopes, roleId, roleName, addressAllowlist, domainAllowlist, expiresAt, lastUsedAt, totalUses, rotatedAt, rotationCount, deactivatedAt, revokedAt, revokedReason, createdAt, createdBy, updatedAt, updatedBy, lastChangeAt and lastChangeType. Never a secret.

نمونه

$key = $client->keys->get('4c1b257a66287fd113bd89d0'); echo $key['name'], ' is ', $key['status'], PHP_EOL;echo 'Scopes: ', implode(', ', $key['scopes']), PHP_EOL;echo 'Domains: ', implode(', ', $key['domainAllowlist'] ?? ['any the workspace owns']), PHP_EOL;

همچنین در دسترس در

API
GET /keys/{id}
TypeScript
keys.get()
Python
keys.get()
Ruby
keys.get
CLI
openemail keys get

keys->create

Mint a new API key and receive its secret once

محدوده‌های دسترسیkeys:manage
امضای متد
create(array $body, ?string $apiKey = null): array

Creates a live key and returns it plus token, the whole secret. That is the only time it appears, so store it before doing anything else.

Left out, scopes is ['emails:send'], the role is the caller's own or none, the send scope is the caller's own or none (none means every address the workspace owns), and the expiry is the caller's own or none. The workspace cap on live keys applies, as a 422 workspace_limit_reached.

A key never makes or reaches a key wider than itself. The target has to sit inside the caller on every axis: scopes the caller holds after its own role has narrowed them, the same role when the caller has one, an expiry no later than the caller's when the caller expires, the caller's mode, and a send scope inside the caller's own, where one address never covers its whole domain. Anything wider is 403 beyond_caller_authority, and param names the axis.

Step-up verification, which the app asks for before it mints a key, cannot apply to a call made with a key, so keys:manage is a credential that makes credentials. Give it only to automation that provisions keys, narrow that key to the role and send scope it needs, and give it an expiry.

پارامترها

namestringالزامی

A name, 1 to 60 characters.

scopesstring[]

The scopes the key holds, at least one, each held by the caller, as in OpenEmail\Constants\ApiScopes. Defaults to ['emails:send'].

roleId?string

A role to cap the key. Left out, the caller's own role. A caller with a role can only give its own, and null is refused for it.

addressAllowliststring[]

Single addresses the key may send as, at most 50, each owned by the workspace.

domainAllowliststring[]

Whole domains the key may send as, at most 25, including addresses added to them later. Leave both lists out to inherit the caller's own; send both empty for none.

expiresInMinutesint

Minutes until the key expires, 5 to 5,256,000 (ten years). Left out, the caller's own expiry.

apiKeystring

Overrides the client API key for this call only.

خروجی

An array with every field get returns: id, name, mode, maskedKey, keyLast4, status, scopes, roleId, roleName, addressAllowlist, domainAllowlist, expiresAt, lastUsedAt, totalUses, rotatedAt, rotationCount, deactivatedAt, revokedAt, revokedReason, createdAt, createdBy, updatedAt, updatedBy, lastChangeAt and lastChangeType, none of them a secret. Plus token, oe_live_ followed by the id, an underscore and the secret.

نمونه

use OpenEmail\Constants\ApiScopes; $key = $client->keys->create([    'name' => 'Billing sender',    'scopes' => [ApiScopes::EMAILS_SEND, ApiScopes::EMAILS_READ],    'domainAllowlist' => ['billing.acme.com'],    'expiresInMinutes' => 60 * 24 * 90,]); file_put_contents('.openemail-billing-key', $key['token']); echo 'Made ', $key['maskedKey'], ', expiring ', $key['expiresAt'], PHP_EOL;

نکته‌ها

  • Not retried automatically: a retry after a lost response would mint a second key.

  • The new key is recorded in the activity log as made by the calling key, with source set to api.

  • The success status is 201.

همچنین در دسترس در

API
POST /keys
TypeScript
keys.create()
Python
keys.create()
Ruby
keys.create
CLI
openemail keys create

keys->update

Rename a key, change its scopes or send scope, or switch it off and on

محدوده‌های دسترسیkeys:manage
امضای متد
update(string $id, array $patch, ?string $apiKey = null): array

Applies a partial change and returns the key as it now stands. scopes, addressAllowlist and domainAllowlist REPLACE what the key had, and a field left out stays as it was. 'enabled' => false switches the key off: every call with it is refused with inactive_api_key and it keeps its secret, scopes, role and send scope, so 'enabled' => true restores it exactly. That is the reversible alternative to revoke. A revoked key cannot be changed, and answers 409 revoked.

A key never makes or reaches a key wider than itself. The target has to sit inside the caller on every axis: scopes the caller holds after its own role has narrowed them, the same role when the caller has one, an expiry no later than the caller's when the caller expires, the caller's mode, and a send scope inside the caller's own, where one address never covers its whole domain. Anything wider is 403 beyond_caller_authority, and param names the axis. A key changing itself may only narrow itself.

A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

namestring

A new name, 1 to 60 characters.

scopesstring[]

The whole new list of scopes, at least one.

addressAllowliststring[]

The whole new list of single addresses.

domainAllowliststring[]

The whole new list of whole domains.

enabledbool

False switches the key off, true switches it back on.

apiKeystring

Overrides the client API key for this call only.

خروجی

An array with id, name, mode, maskedKey, keyLast4, status, scopes, roleId, roleName, addressAllowlist, domainAllowlist, expiresAt, lastUsedAt, totalUses, rotatedAt, rotationCount, deactivatedAt, revokedAt, revokedReason, createdAt, createdBy, updatedAt, updatedBy, lastChangeAt and lastChangeType. Never a secret.

نمونه

$client->keys->update('4c1b257a66287fd113bd89d0', ['enabled' => false]); $key = $client->keys->update('4c1b257a66287fd113bd89d0', ['name' => 'Billing sender (paused)']); echo $key['name'], ' ', $key['status'], PHP_EOL;

نکته‌ها

  • An empty patch is a 422. A PATCH is retried on network failure because applying the same patch twice leaves the same key.

همچنین در دسترس در

API
PATCH /keys/{id}
TypeScript
keys.update()
Python
keys.update()
Ruby
keys.update
CLI
openemail keys update

keys->delete

Remove a revoked key from the list

محدوده‌های دسترسیkeys:manage
امضای متد
delete(string $id, ?string $apiKey = null): array

Deletes a key that has already been revoked. Its request log and activity stay, under Deleted key, so the history of what it did is not lost with it. A key that has not been revoked is refused with 409 not_revoked, so nothing still calling with it loses its credential without somebody deciding that first.

A key never makes or reaches a key wider than itself. The target has to sit inside the caller on every axis: scopes the caller holds after its own role has narrowed them, the same role when the caller has one, an expiry no later than the caller's when the caller expires, the caller's mode, and a send scope inside the caller's own, where one address never covers its whole domain. Anything wider is 403 beyond_caller_authority, and param names the axis.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

apiKeystring

Overrides the client API key for this call only.

خروجی

An array with object set to api_key, the id, and deleted set to true.

نمونه

$client->keys->revoke('4c1b257a66287fd113bd89d0', ['reason' => 'Leaked in a build log']); $deleted = $client->keys->delete('4c1b257a66287fd113bd89d0'); echo $deleted['id'], ' is off the list', PHP_EOL;

همچنین در دسترس در

API
DELETE /keys/{id}
TypeScript
keys.delete()
Python
keys.delete()
Ruby
keys.delete
CLI
openemail keys delete

keys->rotate

Give a key a new secret and receive it once

محدوده‌های دسترسیkeys:manage
امضای متد
rotate(string $id, ?string $apiKey = null): array

Mints a new secret for a key and returns the key plus token, rotationCount and rotatedAt. The id, name, scopes, role, send scope, expiry and request history all carry on; only the secret and keyLast4 change. There is no overlap window: the old secret stops working the instant this returns.

Rotating the calling key itself is what $client->me->rotate() does, and here it is allowed with keys:write as well as keys:manage. A revoked or expired key cannot be rotated, and answers 409 revoked or expired.

A key never makes or reaches a key wider than itself. The target has to sit inside the caller on every axis: scopes the caller holds after its own role has narrowed them, the same role when the caller has one, an expiry no later than the caller's when the caller expires, the caller's mode, and a send scope inside the caller's own, where one address never covers its whole domain. Anything wider is 403 beyond_caller_authority, and param names the axis. Rotation hands the caller a working secret for the key, which is why the ceiling is checked against the key as it stands.

A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

apiKeystring

Overrides the client API key for this call only.

خروجی

An array with every field get returns: id, name, mode, maskedKey, keyLast4, status, scopes, roleId, roleName, addressAllowlist, domainAllowlist, expiresAt, lastUsedAt, totalUses, rotatedAt, rotationCount, deactivatedAt, revokedAt, revokedReason, createdAt, createdBy, updatedAt, updatedBy, lastChangeAt and lastChangeType, none of them a secret. Plus token, rotationCount and rotatedAt.

نمونه

$rotated = $client->keys->rotate('4c1b257a66287fd113bd89d0'); file_put_contents('.openemail-billing-key', $rotated['token']); echo 'Rotation ', $rotated['rotationCount'], ' at ', $rotated['rotatedAt'], PHP_EOL;

نکته‌ها

  • Not retried automatically. Repeating a rotation would invalidate the secret the first attempt returned.

همچنین در دسترس در

API
POST /keys/{id}/rotate
TypeScript
keys.rotate()
Python
keys.rotate()
Ruby
keys.rotate
CLI
openemail keys rotate

keys->revoke

Revoke a key for good

محدوده‌های دسترسیkeys:manage
امضای متد
revoke(string $id, ?array $body = null, ?string $apiKey = null): array

Revokes a key: every later call with it is refused with revoked_api_key, and it can never be switched back on, rotated or changed. reason is kept on the key and in the activity log. Revoking a key that is already revoked changes nothing and returns it as it is. A key may revoke itself, which is how an integration that believes its secret leaked retires it at once.

A key never makes or reaches a key wider than itself. The target has to sit inside the caller on every axis: scopes the caller holds after its own role has narrowed them, the same role when the caller has one, an expiry no later than the caller's when the caller expires, the caller's mode, and a send scope inside the caller's own, where one address never covers its whole domain. Anything wider is 403 beyond_caller_authority, and param names the axis.

A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

reasonstring

Why, at most 200 characters.

apiKeystring

Overrides the client API key for this call only.

خروجی

An array with id, name, mode, maskedKey, keyLast4, status, scopes, roleId, roleName, addressAllowlist, domainAllowlist, expiresAt, lastUsedAt, totalUses, rotatedAt, rotationCount, deactivatedAt, revokedAt, revokedReason, createdAt, createdBy, updatedAt, updatedBy, lastChangeAt and lastChangeType. Never a secret. status is revoked.

نمونه

$key = $client->keys->revoke('4c1b257a66287fd113bd89d0', ['reason' => 'Contractor offboarded']); echo $key['status'], ' at ', $key['revokedAt'], PHP_EOL;

نکته‌ها

  • Retried on network failure, because revoking twice leaves the same key. Prefer update($id, ['enabled' => false]) while you find out whether anything still depends on a key.

همچنین در دسترس در

API
POST /keys/{id}/revoke
TypeScript
keys.revoke()
Python
keys.revoke()
Ruby
keys.revoke
CLI
openemail keys revoke

keys->listRequests

List one page of one key's request log

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
listRequests(    string $id,    ?bool $failedOnly = null,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): Page

Returns one page of the calls one key made, newest first, the Requests tab of the key in the app. The request log records every authenticated call a key made: method, path, status, error code, duration, IP and user agent, and never a body or a query string. A call refused before a key could be identified is not in it, and neither is a call made with an OAuth access token. Nothing is pruned, so the log reaches back to a key's first call. failedOnly:, since: and until: are the filters the app offers.

A deleted key's log stays readable to a key that is not narrowed. A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

failedOnlybool

Only calls answered with a status of 400 or more.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Rows per page, a whole number from 1 to 100. The server defaults to 25.

cursorstring

The nextCursor from the previous page, passed back unchanged. Never build one yourself.

apiKeystring

Overrides the client API key for this call only.

خروجی

A Page of arrays with items, hasMore and nextCursor. Each item has id, keyId, keyName, requestId, method, path, status, errorCode, durationMs, ip, userAgent and createdAt.

نمونه

$page = $client->keys->listRequests('4c1b257a66287fd113bd89d0', failedOnly: true, limit: 50); foreach ($page as $call) {    echo $call['createdAt'], ' ', $call['method'], ' ', $call['path'], ' ', $call['status'], ' ', $call['errorCode'] ?? '', PHP_EOL;}

نکته‌ها

  • The cursor is opaque and stays valid under the same filters. One this log did not hand out is a 400 invalid_cursor.

همچنین در دسترس در

API
GET /keys/{id}/requests
TypeScript
keys.listRequests()
Python
keys.list_requests()
Ruby
keys.list_requests
CLI
openemail keys list-requests

keys->listAllRequests

Collect one key's whole request log into one array

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
listAllRequests(    string $id,    ?bool $failedOnly = null,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): array

Walks every page of listRequests under the same filters. The log is never pruned, so give it a window unless you mean to read a busy key's whole history, or use iterateRequests to stop early.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

failedOnlybool

Only calls answered with a status of 400 or more.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Page size for each request, 1 to 100. The server defaults to 25.

cursorstring

Starts the walk from this cursor instead of the newest row.

apiKeystring

Overrides the client API key for every page of this walk.

خروجی

A list of arrays, one per call with the fields listRequests returns, newest first.

نمونه

$today = $client->keys->listAllRequests('4c1b257a66287fd113bd89d0', since: new \DateTimeImmutable('-1 day'), limit: 100); $failed = array_filter($today, static fn(array $call): bool => $call['status'] >= 400); echo 'Failed today: ', implode(', ', array_column($failed, 'requestId')), PHP_EOL;

نکته‌ها

  • If any page fails the call throws and the rows already fetched are discarded.

همچنین در دسترس در

API
GET /keys/{id}/requests
TypeScript
keys.listAllRequests()
Python
keys.list_all_requests()
Ruby
keys.list_all_requests

keys->iterateRequests

Stream one key's request log one call at a time

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
iterateRequests(    string $id,    ?bool $failedOnly = null,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): Generator

A Generator over listRequests under the same filters, fetching a page only when the one before is drained.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

failedOnlybool

Only calls answered with a status of 400 or more.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Page size per request, 1 to 100. The server defaults to 25.

cursorstring

Starts the walk from this cursor instead of the newest row.

apiKeystring

Overrides the client API key for every page of this walk.

خروجی

A Generator that yields one call array per step.

نمونه

foreach ($client->keys->iterateRequests('4c1b257a66287fd113bd89d0', failedOnly: true) as $call) {    if ($call['errorCode'] === 'from_address_forbidden') {        echo 'Latest refused send at ', $call['createdAt'], PHP_EOL;         break;    }}

همچنین در دسترس در

API
GET /keys/{id}/requests
TypeScript
keys.iterateRequests()
Python
keys.iterate_requests()
Ruby
keys.iterate_requests

keys->listActivity

List one page of what happened to one key

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
listActivity(    string $id,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): Page

Returns one page of one key's audit log, newest first, the Activity tab of the key in the app. Every change to a key is a row: created, updated, rotated, deactivated, reactivated, revoked and deleted, plus auth_failed for every call that presented the key and was refused. actor names who made the change, a person as @username or a key as API key <name> in label, and detail.source says where it came from: console, api, mcp or documentation.

A deleted key keeps its history, readable to a key that is not narrowed. A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Rows per page, a whole number from 1 to 100. The server defaults to 25.

cursorstring

The nextCursor from the previous page, passed back unchanged. Never build one yourself.

apiKeystring

Overrides the client API key for this call only.

خروجی

A Page of arrays with items, hasMore and nextCursor. Each item has id, keyId, keyName, type, createdAt, actor and detail.

نمونه

$page = $client->keys->listActivity('4c1b257a66287fd113bd89d0'); foreach ($page as $change) {    echo $change['createdAt'], ' ', $change['type'], ' by ', $change['actor']['label'], ' from ', $change['detail']['source'] ?? 'unknown', PHP_EOL;}

همچنین در دسترس در

API
GET /keys/{id}/activity
TypeScript
keys.listActivity()
Python
keys.list_activity()
Ruby
keys.list_activity
CLI
openemail keys list-activity

keys->listAllActivity

Collect one key's whole audit log into one array

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
listAllActivity(    string $id,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): array

Walks every page of listActivity under the same window and returns every change, newest first.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Page size for each request, 1 to 100. The server defaults to 25.

cursorstring

Starts the walk from this cursor instead of the newest row.

apiKeystring

Overrides the client API key for every page of this walk.

خروجی

A list of arrays, one per change with the fields listActivity returns, newest first.

نمونه

$history = $client->keys->listAllActivity('4c1b257a66287fd113bd89d0'); $refused = array_filter($history, static fn(array $change): bool => $change['type'] === 'auth_failed'); echo 'Refused attempts: ', implode(', ', array_column($refused, 'createdAt')), PHP_EOL;

نکته‌ها

  • If any page fails the call throws and the rows already fetched are discarded.

همچنین در دسترس در

API
GET /keys/{id}/activity
TypeScript
keys.listAllActivity()
Python
keys.list_all_activity()
Ruby
keys.list_all_activity

keys->iterateActivity

Stream one key's audit log one change at a time

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
iterateActivity(    string $id,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): Generator

A Generator over listActivity under the same window, fetching a page only when the one before is drained.

پارامترها

idstringالزامی

Key id, the 24 hex characters after oe_live_.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Page size per request, 1 to 100. The server defaults to 25.

cursorstring

Starts the walk from this cursor instead of the newest row.

apiKeystring

Overrides the client API key for every page of this walk.

خروجی

A Generator that yields one change array per step.

نمونه

foreach ($client->keys->iterateActivity('4c1b257a66287fd113bd89d0') as $change) {    if ($change['type'] === 'rotated') {        echo 'Last rotated by ', $change['actor']['label'], ' at ', $change['createdAt'], PHP_EOL;         break;    }}

همچنین در دسترس در

API
GET /keys/{id}/activity
TypeScript
keys.iterateActivity()
Python
keys.iterate_activity()
Ruby
keys.iterate_activity

keys->listWorkspaceRequests

List one page of the request log of every key

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
listWorkspaceRequests(    array|string|null $keyIds = null,    ?bool $failedOnly = null,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): Page

Returns one page of every call the workspace's keys made, newest first, the Requests tab of Settings, API keys. The request log records every authenticated call a key made: method, path, status, error code, duration, IP and user agent, and never a body or a query string. A call refused before a key could be identified is not in it, and neither is a call made with an OAuth access token. Nothing is pruned, so the log reaches back to a key's first call. keyIds:, failedOnly:, since: and until: are the filters the app offers, and keyIds: may name a deleted key.

A narrowed key reads only the log of the keys it can see, so naming another key in keyIds: matches nothing.

پارامترها

keyIdsstring|string[]

Key ids to read, at most 50, as an array or one comma-separated string, sent comma-separated. Left out, every key the caller can see.

failedOnlybool

Only calls answered with a status of 400 or more.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Rows per page, a whole number from 1 to 100. The server defaults to 25.

cursorstring

The nextCursor from the previous page, passed back unchanged. Never build one yourself.

apiKeystring

Overrides the client API key for this call only.

خروجی

A Page of arrays with items, hasMore and nextCursor. Each item has id, keyId, keyName, requestId, method, path, status, errorCode, durationMs, ip, userAgent and createdAt.

نمونه

$page = $client->keys->listWorkspaceRequests(failedOnly: true, since: '2026-09-22T00:00:00Z'); foreach ($page as $call) {    echo $call['keyName'], ' ', $call['method'], ' ', $call['path'], ' ', $call['status'], PHP_EOL;}

همچنین در دسترس در

API
GET /keys/requests
TypeScript
keys.listWorkspaceRequests()
Python
keys.list_workspace_requests()
Ruby
keys.list_workspace_requests
CLI
openemail keys list-workspace-requests

keys->listAllWorkspaceRequests

Collect the request log of every key into one array

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
listAllWorkspaceRequests(    array|string|null $keyIds = null,    ?bool $failedOnly = null,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): array

Walks every page of listWorkspaceRequests under the same filters. The log is never pruned, so give it a window, or use iterateWorkspaceRequests to stop early.

پارامترها

keyIdsstring|string[]

Key ids to read, at most 50, as an array or one comma-separated string, sent comma-separated. Left out, every key the caller can see.

failedOnlybool

Only calls answered with a status of 400 or more.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Page size for each request, 1 to 100. The server defaults to 25.

cursorstring

Starts the walk from this cursor instead of the newest row.

apiKeystring

Overrides the client API key for every page of this walk.

خروجی

A list of arrays, one per call with the fields listWorkspaceRequests returns, newest first.

نمونه

$failures = $client->keys->listAllWorkspaceRequests(failedOnly: true, since: new \DateTimeImmutable('-1 hour'), limit: 100); foreach ($failures as $call) {    echo $call['keyName'], ' ', $call['path'], ' ', $call['errorCode'] ?? $call['status'], PHP_EOL;}

نکته‌ها

  • If any page fails the call throws and the rows already fetched are discarded.

همچنین در دسترس در

API
GET /keys/requests
TypeScript
keys.listAllWorkspaceRequests()
Python
keys.list_all_workspace_requests()
Ruby
keys.list_all_workspace_requests

keys->iterateWorkspaceRequests

Stream the request log of every key one call at a time

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
iterateWorkspaceRequests(    array|string|null $keyIds = null,    ?bool $failedOnly = null,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): Generator

A Generator over listWorkspaceRequests under the same filters, fetching a page only when the one before is drained.

پارامترها

keyIdsstring|string[]

Key ids to read, at most 50, as an array or one comma-separated string, sent comma-separated. Left out, every key the caller can see.

failedOnlybool

Only calls answered with a status of 400 or more.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Page size per request, 1 to 100. The server defaults to 25.

cursorstring

Starts the walk from this cursor instead of the newest row.

apiKeystring

Overrides the client API key for every page of this walk.

خروجی

A Generator that yields one call array per step.

نمونه

foreach ($client->keys->iterateWorkspaceRequests(failedOnly: true) as $call) {    if ($call['status'] >= 500) {        echo $call['requestId'], ' ', $call['path'], PHP_EOL;    }}

همچنین در دسترس در

API
GET /keys/requests
TypeScript
keys.iterateWorkspaceRequests()
Python
keys.iterate_workspace_requests()
Ruby
keys.iterate_workspace_requests

keys->listWorkspaceActivity

List one page of what happened to every key

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
listWorkspaceActivity(    array|string|null $keyIds = null,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): Page

Returns one page of the audit log of every key in the workspace, newest first, the Activity tab of Settings, API keys. Every change to a key is a row: created, updated, rotated, deactivated, reactivated, revoked and deleted, plus auth_failed for every call that presented the key and was refused. actor names who made the change, a person as @username or a key as API key <name> in label, and detail.source says where it came from: console, api, mcp or documentation.

keyIds: narrows it, deleted keys included, and since: and until: keep a window. A narrowed key reads only the activity of the keys it can see.

پارامترها

keyIdsstring|string[]

Key ids to read, at most 50, as an array or one comma-separated string, sent comma-separated. Left out, every key the caller can see.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Rows per page, a whole number from 1 to 100. The server defaults to 25.

cursorstring

The nextCursor from the previous page, passed back unchanged. Never build one yourself.

apiKeystring

Overrides the client API key for this call only.

خروجی

A Page of arrays with items, hasMore and nextCursor. Each item has id, keyId, keyName, type, createdAt, actor and detail.

نمونه

$page = $client->keys->listWorkspaceActivity(since: '2026-09-01T00:00:00Z'); foreach ($page as $change) {    echo $change['keyName'], ' ', $change['type'], ' by ', $change['actor']['label'], PHP_EOL;}

همچنین در دسترس در

API
GET /keys/activity
TypeScript
keys.listWorkspaceActivity()
Python
keys.list_workspace_activity()
Ruby
keys.list_workspace_activity
CLI
openemail keys list-workspace-activity

keys->listAllWorkspaceActivity

Collect the audit log of every key into one array

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
listAllWorkspaceActivity(    array|string|null $keyIds = null,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): array

Walks every page of listWorkspaceActivity under the same filters and returns every change, newest first.

پارامترها

keyIdsstring|string[]

Key ids to read, at most 50, as an array or one comma-separated string, sent comma-separated. Left out, every key the caller can see.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Page size for each request, 1 to 100. The server defaults to 25.

cursorstring

Starts the walk from this cursor instead of the newest row.

apiKeystring

Overrides the client API key for every page of this walk.

خروجی

A list of arrays, one per change with the fields listWorkspaceActivity returns, newest first.

نمونه

$changes = $client->keys->listAllWorkspaceActivity(since: new \DateTimeImmutable('2026-09-01')); $overApi = array_filter($changes, static fn(array $change): bool => ($change['detail']['source'] ?? null) === 'api'); echo implode(PHP_EOL, array_column($overApi, 'keyName')), PHP_EOL;

نکته‌ها

  • If any page fails the call throws and the rows already fetched are discarded.

همچنین در دسترس در

API
GET /keys/activity
TypeScript
keys.listAllWorkspaceActivity()
Python
keys.list_all_workspace_activity()
Ruby
keys.list_all_workspace_activity

keys->iterateWorkspaceActivity

Stream the audit log of every key one change at a time

محدوده‌های دسترسیkeys:readنتایج را صفحه‌به‌صفحه مرور می‌کند
امضای متد
iterateWorkspaceActivity(    array|string|null $keyIds = null,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?int $limit = null,    ?string $cursor = null,    ?string $apiKey = null,): Generator

A Generator over listWorkspaceActivity under the same filters, fetching a page only when the one before is drained.

پارامترها

keyIdsstring|string[]

Key ids to read, at most 50, as an array or one comma-separated string, sent comma-separated. Left out, every key the caller can see.

sincestring|DateTimeInterface

Only rows at or after this instant. A DateTimeInterface is sent as ISO 8601 in UTC, and a string must already be ISO 8601.

untilstring|DateTimeInterface

Only rows before this instant. It has to be later than since, or the server answers 400 invalid_parameter.

limitint

Page size per request, 1 to 100. The server defaults to 25.

cursorstring

Starts the walk from this cursor instead of the newest row.

apiKeystring

Overrides the client API key for every page of this walk.

خروجی

A Generator that yields one change array per step.

نمونه

foreach ($client->keys->iterateWorkspaceActivity() as $change) {    if ($change['type'] === 'auth_failed') {        echo $change['keyName'], ' ', $change['detail']['reason'] ?? 'refused', ' ', $change['createdAt'], PHP_EOL;    }}

همچنین در دسترس در

API
GET /keys/activity
TypeScript
keys.iterateWorkspaceActivity()
Python
keys.iterate_workspace_activity()
Ruby
keys.iterate_workspace_activity

keys->stats

Read what the keys did inside a window

محدوده‌های دسترسیkeys:reademails:read
امضای متد
stats(    array|string|null $keyIds = null,    DateTimeInterface|string|null $since = null,    DateTimeInterface|string|null $until = null,    ?string $grain = null,    ?int $offsetMinutes = null,    ?string $apiKey = null,): array

Returns the numbers behind the Analytics tab of the API keys page: the mail the keys sent and what became of it, the calls refused because a secret was wrong, revoked or expired, the requests they made and how many failed, the routes they called most with the median time each took, and the status codes they got back.

It covers every key you can see, or the ones keyIds: names. The window runs from since: to until:, and left out it is the 30 days before now. grain: sets the bucket width of the series and offsetMinutes: shifts the boundaries so days break where the reader's day does.

پارامترها

keyIdsstring|string[]

Only these keys, at most 50, as an array or one comma-separated string. Left out, every key you can see.

sincestring|DateTimeInterface

The start of the window, a DateTimeInterface or an ISO 8601 instant. Defaults to 30 days before until.

untilstring|DateTimeInterface

The end of the window, not included. Defaults to now.

grainstring

Bucket width: minute, hour or day, defaulting to day.

offsetMinutesint

Minutes east of UTC to bucket in, from -840 to 840, defaulting to 0.

apiKeystring

Overrides the client API key for this call only.

خروجی

An array with the window it covered, sends, rejected, requests, routes and codes.

نمونه

$stats = $client->keys->stats(grain: 'day'); echo $stats['sends']['totals']['sends'], ' sent from ', $stats['since'], ' to ', $stats['until'], PHP_EOL; foreach ($stats['routes'] as $route) {    echo $route['label'], ': ', $route['count'], ' calls, median ', $route['medianMs'], ' ms', PHP_EOL;}

نکته‌ها

  • A key narrowed to some domains or addresses only counts the keys whose send scope sits inside its own, and an access token is refused with 403 owner_only unless it acts for the owner of the workspace.

  • The series are sparse: a bucket with nothing in it has no entry, so a chart must fill the gaps.

  • Retried automatically on network failure, since it only reads.

همچنین در دسترس در

API
GET /keys/stats
TypeScript
keys.stats()
Python
keys.stats()
Ruby
keys.stats
CLI
openemail keys stats

صندوق ورودی شما،
با شرایط خودتان.

باز کردن نامهشروع کنید
محصولات
کسب‌وکارتوسعه‌دهندگانهوش مصنوعی و ایجنت‌هاشخصی
OpenEmail
قیمت‌گذاریویژگی‌هادانلودمقایسهمهاجرتمشتریانامنیت و مقیاسدرباره ماتماسسیاست حریم خصوصیشرایط خدمات
منابع
مستنداتمرجع APITypeScript SDKPython SDKRuby SDKPHP SDKخط فرمانسرور MCPقالب‌های ایمیلموارد استفادهوضعیت
ابزارها
سازندهٔ قالب با هوش مصنوعیبررسی‌کننده تحویل‌پذیریبررسی‌کننده لوگوی BIMIنشانی ایمیل موقتتولیدکننده رکورد DMARCماشین‌حساب هزینه ایمیل
© 2026 OpenEmail. همه حقوق محفوظ است.