client.Keys
Cada método deste espaço de nomes: a sua assinatura, os seus parâmetros, o que devolve e um exemplo.
Métodos
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
List(ctx context.Context, opts ...openemail.RequestOption) (*openemail.Page, error)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.
Parâmetros
openemail.WithLimitintRows per page, a whole number from 1 to 100. The server defaults to 25.
openemail.WithCursorstringThe
NextCursorfrom the previous page, passed back unchanged. Never build one yourself.openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
A *openemail.Page with Items, HasMore and NextCursor. Each item is an API key object: 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.
Exemplo
page, err := client.Keys.List(ctx)if err != nil { return err} for _, key := range page.Items { fmt.Println(key.String("maskedKey"), key.String("name"), key.String("status"), key.String("lastUsedAt"))} fmt.Println(page.HasMore, page.NextCursor)Notas
It needs
keys:read, which no key holds unless somebody gave it one.The cursor is opaque: pass
NextCursorback as it came.
Também disponível em
- API
GET /keys- TypeScript
keys.list()- Python
keys.list()- Ruby
keys.list- PHP
keys->list- Java
keys().list- C#
Keys.ListAsync- CLI
openemail keys list
Keys.ListAll
Collect every API key into one slice
ListAll(ctx context.Context, opts ...openemail.RequestOption) ([]openemail.Object, error)Walks every page of List and returns with every key the caller can see, newest first.
Parâmetros
openemail.WithLimitintPage size for each request, 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk from this cursor instead of the newest row.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Devolve
A []openemail.Object, newest first.
Exemplo
keys, err := client.Keys.ListAll(ctx)if err != nil { return err} for _, key := range keys { fmt.Println(key.String("status"), key.String("lastUsedAt"), key.String("name"))}Também disponível em
- API
GET /keys- TypeScript
keys.listAll()- Python
keys.list_all()- Ruby
keys.list_all- PHP
keys->listAll- Java
keys().listAll- C#
Keys.ListAllAsync
Keys.Iterate
Stream the workspace's API keys one at a time
Iterate(ctx context.Context, opts ...openemail.RequestOption) *openemail.IteratorAn iterator over List, fetching a page only when the one before is drained.
Parâmetros
openemail.WithLimitintPage size per request, 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk from this cursor instead of the newest row.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Devolve
An *openemail.Iterator yielding one key per step.
Exemplo
for key, err := range client.Keys.Iterate(ctx).All() { if err != nil { return err } fmt.Println(key.String("expiresAt"), key.String("name"))}Também disponível em
- API
GET /keys- TypeScript
keys.iterate()- Python
keys.iterate()- Ruby
keys.iterate- PHP
keys->iterate- Java
keys().iterate- C#
Keys.IterateAsync
Keys.Get
Read one API key, without its secret
Get(ctx context.Context, id string, opts ...openemail.RequestOption) (openemail.Object, error)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.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
An openemail.Object: 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.
Exemplo
key, err := client.Keys.Get(ctx, "4c1b257a66287fd113bd89d0")if err != nil { return err} fmt.Println(key.String("status"))Também disponível em
- API
GET /keys/{id}- TypeScript
keys.get()- Python
keys.get()- Ruby
keys.get- PHP
keys->get- Java
keys().get- C#
Keys.GetAsync- CLI
openemail keys get
Keys.Create
Mint a new API key and receive its secret once
Create(ctx context.Context, body openemail.Body, opts ...openemail.RequestOption) (openemail.Object, error)Creates a live key and returns with it plus token, the whole secret. That is the only time it appears, so store it before doing anything else.
Left out, scopes is []string{"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.
Parâmetros
namestringObrigatórioA name, 1 to 60 characters.
scopes[]stringThe scopes the key holds, at least one, each held by the caller. Defaults to
[]string{"emails:send"}.roleIdstring | nilA role to cap the key. Left out, the caller's own role. A caller with a role can only give its own, and
nullis refused for it.addressAllowlist[]stringSingle addresses the key may send as, at most 50, each owned by the workspace.
domainAllowlist[]stringWhole 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.
expiresInMinutesintMinutes until the key expires, 5 to 5,256,000 (ten years). Left out, the caller's own expiry.
openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
An openemail.Object: the API key object: 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. Plus token, oe_live_ followed by the id, an underscore and the secret.
Exemplo
key, err := client.Keys.Create(ctx, openemail.Body{ "name": "Billing sender", "scopes": []string{"emails:send", "emails:read"}, "domainAllowlist": []string{"billing.acme.com"}, "expiresInMinutes": 60 * 24 * 90,})if err != nil { return err} if err := os.WriteFile("billing.key", []byte(key.String("token")), 0o600); err != nil { return err}Notas
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,
source: 'api'.The success status is 201.
Também disponível em
- API
POST /keys- TypeScript
keys.create()- Python
keys.create()- Ruby
keys.create- PHP
keys->create- Java
keys().create- C#
Keys.CreateAsync- CLI
openemail keys create
Keys.Update
Rename a key, change its scopes or send scope, or switch it off and on
Update(ctx context.Context, id string, patch openemail.Body, opts ...openemail.RequestOption) (openemail.Object, error)Applies a partial change and returns with 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.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.namestringA new name, 1 to 60 characters.
scopes[]stringThe whole new list of scopes, at least one.
addressAllowlist[]stringThe whole new list of single addresses.
domainAllowlist[]stringThe whole new list of whole domains.
enabledboolFalse switches the key off, true switches it back on.
openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
An openemail.Object: 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.
Exemplo
key, err := client.Keys.Update(ctx, "4c1b257a66287fd113bd89d0", openemail.Body{"enabled": false})if err != nil { return err} fmt.Println(key.String("id"), key.String("status"))Notas
An empty patch is a 422. A PATCH is retried on network failure because applying the same patch twice leaves the same key.
Também disponível em
- API
PATCH /keys/{id}- TypeScript
keys.update()- Python
keys.update()- Ruby
keys.update- PHP
keys->update- Java
keys().update- C#
Keys.UpdateAsync- CLI
openemail keys update
Keys.Delete
Remove a revoked key from the list
Delete(ctx context.Context, id string, opts ...openemail.RequestOption) (openemail.Object, error)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.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
An openemail.Object with object set to api_key, id and deleted set to true.
Exemplo
key, err := client.Keys.Delete(ctx, "4c1b257a66287fd113bd89d0")if err != nil { return err} fmt.Println(key.String("id"), key.String("object"))Também disponível em
- API
DELETE /keys/{id}- TypeScript
keys.delete()- Python
keys.delete()- Ruby
keys.delete- PHP
keys->delete- Java
keys().delete- C#
Keys.DeleteAsync- CLI
openemail keys delete
Keys.Rotate
Give a key a new secret and receive it once
Rotate(ctx context.Context, id string, opts ...openemail.RequestOption) (openemail.Object, error)Mints a new secret for a key and returns with 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.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
An openemail.Object: the API key object: 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. Plus token, rotationCount and rotatedAt.
Exemplo
rotated, err := client.Keys.Rotate(ctx, "4c1b257a66287fd113bd89d0")if err != nil { return err} fmt.Println(rotated.String("token"), rotated.Int("rotationCount"), rotated.String("rotatedAt"))Notas
Not retried automatically. Repeating a rotation would invalidate the secret the first attempt returned.
Também disponível em
- API
POST /keys/{id}/rotate- TypeScript
keys.rotate()- Python
keys.rotate()- Ruby
keys.rotate- PHP
keys->rotate- Java
keys().rotate- C#
Keys.RotateAsync- CLI
openemail keys rotate
Keys.Revoke
Revoke a key for good
Revoke(ctx context.Context, id string, body openemail.Body, opts ...openemail.RequestOption) (openemail.Object, error)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 with 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.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.reasonstringWhy, at most 200 characters.
openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
An openemail.Object: 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.
Exemplo
key, err := client.Keys.Revoke(ctx, "4c1b257a66287fd113bd89d0", openemail.Body{"reason": "Contractor offboarded"})if err != nil { return err} fmt.Println(key.String("status"), key.String("revokedAt"))Notas
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.
Também disponível em
- API
POST /keys/{id}/revoke- TypeScript
keys.revoke()- Python
keys.revoke()- Ruby
keys.revoke- PHP
keys->revoke- Java
keys().revoke- C#
Keys.RevokeAsync- CLI
openemail keys revoke
Keys.ListRequests
List one page of one key's request log
ListRequests(ctx context.Context, id string, opts ...openemail.RequestOption) (*openemail.Page, error)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. openemail.WithFailedOnly, openemail.WithStatusCodes, openemail.WithPath, openemail.WithSince and openemail.WithUntil narrow it, and they combine.
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.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.openemail.WithFailedOnlyboolOnly calls answered with a status of 400 or more.
openemail.WithStatusCodes...intOnly calls answered with one of these HTTP status codes, such as
401and403. At most 20, each from 100 to 599, sent comma-separated asstatus.openemail.WithPathstringOnly calls to this route, whatever the method, such as
/emailsor/emails/:id. It matches the route, not the exact path: an id counts as:idand an email address as:address. End it with*to read every route that starts with it, such as/emails/*.openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintRows per page, a whole number from 1 to 100. The server defaults to 25.
openemail.WithCursorstringThe
NextCursorfrom the previous page, passed back unchanged. Never build one yourself.openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
A *openemail.Page with Items, HasMore and NextCursor. Each item has id, keyId, keyName, requestId, method, path, status, errorCode, durationMs, ip, userAgent and createdAt.
Exemplo
page, err := client.Keys.ListRequests(ctx, "4c1b257a66287fd113bd89d0", openemail.WithFailedOnly(true), openemail.WithLimit(50))if err != nil { return err} for _, request := range page.Items { fmt.Println(request.String("createdAt"), request.String("method"), request.String("path"), request.Int("status"))} fmt.Println(page.HasMore, page.NextCursor)Notas
The cursor is opaque and stays valid under the same filters. One this log did not hand out is a 400
invalid_cursor.openemail.WithPathmatches the route rather than the exact path, because the log folds ids and addresses: every call to/emails/<id>is the one route/emails/:id, and passing a real id reads that whole route. Each row still carries the exactpath, so filter the page yourself to follow one id.The key making the call reads its own log with no scope through
Me.ListRequests.
Também disponível em
Keys.ListAllRequests
Collect one key's whole request log into one slice
ListAllRequests(ctx context.Context, id string, opts ...openemail.RequestOption) ([]openemail.Object, error)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.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.openemail.WithFailedOnlyboolOnly calls answered with a status of 400 or more.
openemail.WithStatusCodes...intOnly calls answered with one of these HTTP status codes, such as
401and403. At most 20, each from 100 to 599, sent comma-separated asstatus.openemail.WithPathstringOnly calls to this route, whatever the method, such as
/emailsor/emails/:id. It matches the route, not the exact path: an id counts as:idand an email address as:address. End it with*to read every route that starts with it, such as/emails/*.openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintPage size for each request, 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk from this cursor instead of the newest row.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Devolve
A []openemail.Object, newest first.
Exemplo
today, err := client.Keys.ListAllRequests(ctx, "4c1b257a66287fd113bd89d0", openemail.WithSince(time.Now().Add(-24*time.Hour)), openemail.WithLimit(100))if err != nil { return err} for _, request := range today { fmt.Println(request.String("id"), request.Int("status"))}Notas
If any page fails the call fails and the rows already fetched are discarded.
Também disponível em
Keys.IterateRequests
Stream one key's request log one call at a time
IterateRequests(ctx context.Context, id string, opts ...openemail.RequestOption) *openemail.IteratorAn iterator over ListRequests under the same filters, fetching a page only when the one before is drained.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.openemail.WithFailedOnlyboolOnly calls answered with a status of 400 or more.
openemail.WithStatusCodes...intOnly calls answered with one of these HTTP status codes, such as
401and403. At most 20, each from 100 to 599, sent comma-separated asstatus.openemail.WithPathstringOnly calls to this route, whatever the method, such as
/emailsor/emails/:id. It matches the route, not the exact path: an id counts as:idand an email address as:address. End it with*to read every route that starts with it, such as/emails/*.openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintPage size per request, 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk from this cursor instead of the newest row.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Devolve
An *openemail.Iterator yielding one call per step.
Exemplo
for request, err := range client.Keys.IterateRequests(ctx, "4c1b257a66287fd113bd89d0", openemail.WithFailedOnly(true)).All() { if err != nil { return err } fmt.Println(request.String("errorCode"), request.String("createdAt"))}Também disponível em
Keys.ListActivity
List one page of what happened to one key
ListActivity(ctx context.Context, id string, opts ...openemail.RequestOption) (*openemail.Page, error)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.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintRows per page, a whole number from 1 to 100. The server defaults to 25.
openemail.WithCursorstringThe
NextCursorfrom the previous page, passed back unchanged. Never build one yourself.openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
A *openemail.Page with Items, HasMore and NextCursor. Each item has id, keyId, keyName, type, createdAt, actor and detail.
Exemplo
page, err := client.Keys.ListActivity(ctx, "4c1b257a66287fd113bd89d0")if err != nil { return err} for _, activity := range page.Items { fmt.Println(activity.String("createdAt"), activity.String("type"), activity.Object("actor").String("label"))} fmt.Println(page.HasMore, page.NextCursor)Também disponível em
Keys.ListAllActivity
Collect one key's whole audit log into one slice
ListAllActivity(ctx context.Context, id string, opts ...openemail.RequestOption) ([]openemail.Object, error)Walks every page of ListActivity under the same window and returns with every change, newest first.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintPage size for each request, 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk from this cursor instead of the newest row.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Devolve
A []openemail.Object, newest first.
Exemplo
history, err := client.Keys.ListAllActivity(ctx, "4c1b257a66287fd113bd89d0")if err != nil { return err} for _, activity := range history { fmt.Println(activity.String("type"))}Notas
If any page fails the call fails and the rows already fetched are discarded.
Também disponível em
Keys.IterateActivity
Stream one key's audit log one change at a time
IterateActivity(ctx context.Context, id string, opts ...openemail.RequestOption) *openemail.IteratorAn iterator over ListActivity under the same window, fetching a page only when the one before is drained.
Parâmetros
idstringObrigatórioKey id, the 24 hex characters after
oe_live_.openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintPage size per request, 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk from this cursor instead of the newest row.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Devolve
An *openemail.Iterator yielding one change per step.
Exemplo
for activity, err := range client.Keys.IterateActivity(ctx, "4c1b257a66287fd113bd89d0").All() { if err != nil { return err } fmt.Println(activity.String("type"), activity.Object("actor").String("label"), activity.String("createdAt"))}Também disponível em
Keys.ListWorkspaceRequests
List one page of the request log of every key
ListWorkspaceRequests(ctx context.Context, opts ...openemail.RequestOption) (*openemail.Page, error)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. openemail.WithKeyIDs, openemail.WithFailedOnly, openemail.WithStatusCodes, openemail.WithPath, openemail.WithSince and openemail.WithUntil narrow it, and they combine. 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.
Parâmetros
openemail.WithKeyIDs...stringKey ids to read, at most 50, sent comma-separated. Left out, every key the caller can see.
openemail.WithFailedOnlyboolOnly calls answered with a status of 400 or more.
openemail.WithStatusCodes...intOnly calls answered with one of these HTTP status codes, such as
401and403. At most 20, each from 100 to 599, sent comma-separated asstatus.openemail.WithPathstringOnly calls to this route, whatever the method, such as
/emailsor/emails/:id. It matches the route, not the exact path: an id counts as:idand an email address as:address. End it with*to read every route that starts with it, such as/emails/*.openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintRows per page, a whole number from 1 to 100. The server defaults to 25.
openemail.WithCursorstringThe
NextCursorfrom the previous page, passed back unchanged. Never build one yourself.openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
A *openemail.Page with Items, HasMore and NextCursor. Each item has id, keyId, keyName, requestId, method, path, status, errorCode, durationMs, ip, userAgent and createdAt.
Exemplo
page, err := client.Keys.ListWorkspaceRequests( ctx, openemail.WithFailedOnly(true), openemail.WithSince(time.Date(2026, time.September, 22, 0, 0, 0, 0, time.UTC)),)if err != nil { return err} for _, request := range page.Items { fmt.Println(request.String("keyName"), request.String("method"), request.String("path"), request.Int("status"))} fmt.Println(page.HasMore, page.NextCursor)Também disponível em
Keys.ListAllWorkspaceRequests
Collect the request log of every key into one slice
ListAllWorkspaceRequests(ctx context.Context, opts ...openemail.RequestOption) ([]openemail.Object, error)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.
Parâmetros
openemail.WithKeyIDs...stringKey ids to read, at most 50, sent comma-separated. Left out, every key the caller can see.
openemail.WithFailedOnlyboolOnly calls answered with a status of 400 or more.
openemail.WithStatusCodes...intOnly calls answered with one of these HTTP status codes, such as
401and403. At most 20, each from 100 to 599, sent comma-separated asstatus.openemail.WithPathstringOnly calls to this route, whatever the method, such as
/emailsor/emails/:id. It matches the route, not the exact path: an id counts as:idand an email address as:address. End it with*to read every route that starts with it, such as/emails/*.openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintPage size for each request, 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk from this cursor instead of the newest row.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Devolve
A []openemail.Object, newest first.
Exemplo
failures, err := client.Keys.ListAllWorkspaceRequests( ctx, openemail.WithFailedOnly(true), openemail.WithSince(time.Now().Add(-time.Hour)), openemail.WithLimit(100),)if err != nil { return err} for _, request := range failures { fmt.Println(request.String("id"), request.Int("status"))}Notas
If any page fails the call fails and the rows already fetched are discarded.
Também disponível em
Keys.IterateWorkspaceRequests
Stream the request log of every key one call at a time
IterateWorkspaceRequests(ctx context.Context, opts ...openemail.RequestOption) *openemail.IteratorAn iterator over ListWorkspaceRequests under the same filters, fetching a page only when the one before is drained.
Parâmetros
openemail.WithKeyIDs...stringKey ids to read, at most 50, sent comma-separated. Left out, every key the caller can see.
openemail.WithFailedOnlyboolOnly calls answered with a status of 400 or more.
openemail.WithStatusCodes...intOnly calls answered with one of these HTTP status codes, such as
401and403. At most 20, each from 100 to 599, sent comma-separated asstatus.openemail.WithPathstringOnly calls to this route, whatever the method, such as
/emailsor/emails/:id. It matches the route, not the exact path: an id counts as:idand an email address as:address. End it with*to read every route that starts with it, such as/emails/*.openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintPage size per request, 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk from this cursor instead of the newest row.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Devolve
An *openemail.Iterator yielding one call per step.
Exemplo
for request, err := range client.Keys.IterateWorkspaceRequests(ctx, openemail.WithFailedOnly(true)).All() { if err != nil { return err } fmt.Println(request.Int("status"), request.String("requestId"), request.String("path"))}Também disponível em
Keys.ListWorkspaceActivity
List one page of what happened to every key
ListWorkspaceActivity(ctx context.Context, opts ...openemail.RequestOption) (*openemail.Page, error)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.
Parâmetros
openemail.WithKeyIDs...stringKey ids to read, at most 50, sent comma-separated. Left out, every key the caller can see.
openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintRows per page, a whole number from 1 to 100. The server defaults to 25.
openemail.WithCursorstringThe
NextCursorfrom the previous page, passed back unchanged. Never build one yourself.openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
A *openemail.Page with Items, HasMore and NextCursor. Each item has id, keyId, keyName, type, createdAt, actor and detail.
Exemplo
page, err := client.Keys.ListWorkspaceActivity(ctx, openemail.WithSince(time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC)))if err != nil { return err} for _, activity := range page.Items { fmt.Println(activity.String("keyName"), activity.String("type"), activity.Object("actor").String("label"))} fmt.Println(page.HasMore, page.NextCursor)Também disponível em
Keys.ListAllWorkspaceActivity
Collect the audit log of every key into one slice
ListAllWorkspaceActivity(ctx context.Context, opts ...openemail.RequestOption) ([]openemail.Object, error)Walks every page of ListWorkspaceActivity under the same filters and returns with every change, newest first.
Parâmetros
openemail.WithKeyIDs...stringKey ids to read, at most 50, sent comma-separated. Left out, every key the caller can see.
openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintPage size for each request, 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk from this cursor instead of the newest row.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Devolve
A []openemail.Object, newest first.
Exemplo
changes, err := client.Keys.ListAllWorkspaceActivity(ctx, openemail.WithSince(time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC)))if err != nil { return err} for _, activity := range changes { fmt.Println(activity.String("id"), activity.String("object"))}Notas
If any page fails the call fails and the rows already fetched are discarded.
Também disponível em
Keys.IterateWorkspaceActivity
Stream the audit log of every key one change at a time
IterateWorkspaceActivity(ctx context.Context, opts ...openemail.RequestOption) *openemail.IteratorAn iterator over ListWorkspaceActivity under the same filters, fetching a page only when the one before is drained.
Parâmetros
openemail.WithKeyIDs...stringKey ids to read, at most 50, sent comma-separated. Left out, every key the caller can see.
openemail.WithSincetime.TimeOnly rows at or after this instant. A
time.Time, sent as an ISO 8601 instant.openemail.WithUntiltime.TimeOnly rows before this instant. It has to be later than
since, or the server answers 400invalid_parameter.openemail.WithLimitintPage size per request, 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk from this cursor instead of the newest row.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Devolve
An *openemail.Iterator yielding one change per step.
Exemplo
for activity, err := range client.Keys.IterateWorkspaceActivity(ctx).All() { if err != nil { return err } fmt.Println(activity.String("type"), activity.String("keyName"), activity.String("createdAt"))}Também disponível em
Keys.Stats
Read what the keys did inside a window
Stats(ctx context.Context, opts ...openemail.RequestOption) (openemail.Object, error)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.
Parâmetros
openemail.WithKeyIDs...stringOnly these keys, at most 50. Left out, every key you can see.
openemail.WithSincetime.TimeThe start of the window, a
time.Time. Defaults to 30 days beforeuntil.openemail.WithUntiltime.TimeThe end of the window, not included. Defaults to now.
openemail.WithGrainstringBucket width:
minute,hourorday, defaulting today.openemail.WithOffsetMinutesintMinutes east of UTC to bucket in, from -840 to 840, defaulting to 0.
openemail.WithAPIKeystringOverrides the client API key for this call only.
Devolve
An openemail.Object with the window it covered, sends, rejected, requests, routes and codes.
Exemplo
stats, err := client.Keys.Stats(ctx, openemail.WithGrain("day"))if err != nil { return err} fmt.Println(stats.Object("sends").Object("totals").Int("sends"))Notas
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_onlyunless 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.
Também disponível em
- API
GET /keys/stats- TypeScript
keys.stats()- Python
keys.stats()- Ruby
keys.stats- PHP
keys->stats- Java
keys().stats- C#
Keys.StatsAsync- CLI
openemail keys stats