---
title: "Account"
description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with."
url: "https://nextmail.sh/docs/api/reference/account"
area: "API"
category: "Reference"
---

# Account

Every operation in this group: what it accepts, what it returns and the errors it can answer with.

## Operations

What this key is and may do.

### `GET /addresses`

What this key may send as

The answer to an unexplained 403 or 409. `unrestricted` is true only on a key with neither allowlist set, and it means any local-part on a verified domain is accepted, including ones nobody has created. A key holding whole domains reads as `unrestricted: false` and still takes any local-part on those domains, so `GET /keys/self` is where you read which ones. `canSend` on an address is false when the address is disabled, when neither allowlist on the key covers it, or when the domain cannot sign yet, and `sendingVerified` on each domain is that last fact on its own.

Requires the `emails:send` scope.

- Scopes: `emails:send`.

**Query parameters**

- `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100.
- `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`.

**Returns**

- `200` `SendableAddressList`: A page of addresses, alphabetically, with `hasMore` and `nextCursor`, plus `unrestricted` and every sendable domain on each page.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.addresses.list()`](https://nextmail.sh/docs/sdk/reference/addresses#list), [`nextmail.addresses.listAll()`](https://nextmail.sh/docs/sdk/reference/addresses#listAll), [`nextmail.addresses.iterate()`](https://nextmail.sh/docs/sdk/reference/addresses#iterate); Python [`addresses.list()`](https://nextmail.sh/docs/python/reference/addresses#list), [`addresses.list_all()`](https://nextmail.sh/docs/python/reference/addresses#listAll), [`addresses.iterate()`](https://nextmail.sh/docs/python/reference/addresses#iterate); Ruby [`addresses.list`](https://nextmail.sh/docs/ruby/reference/addresses#list), [`addresses.list_all`](https://nextmail.sh/docs/ruby/reference/addresses#listAll), [`addresses.iterate`](https://nextmail.sh/docs/ruby/reference/addresses#iterate); PHP [`addresses->list`](https://nextmail.sh/docs/php/reference/addresses#list), [`addresses->listAll`](https://nextmail.sh/docs/php/reference/addresses#listAll), [`addresses->iterate`](https://nextmail.sh/docs/php/reference/addresses#iterate); Go [`Addresses.List`](https://nextmail.sh/docs/go/reference/addresses#list), [`Addresses.ListAll`](https://nextmail.sh/docs/go/reference/addresses#listAll), [`Addresses.Iterate`](https://nextmail.sh/docs/go/reference/addresses#iterate); Java [`addresses().list`](https://nextmail.sh/docs/java/reference/addresses#list), [`addresses().listAll`](https://nextmail.sh/docs/java/reference/addresses#listAll), [`addresses().iterate`](https://nextmail.sh/docs/java/reference/addresses#iterate); C# [`Addresses.ListAsync`](https://nextmail.sh/docs/csharp/reference/addresses#list), [`Addresses.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/addresses#listAll), [`Addresses.IterateAsync`](https://nextmail.sh/docs/csharp/reference/addresses#iterate); CLI [`nextmail addresses list`](https://nextmail.sh/docs/cli/reference/addresses#addresses-list); MCP [`whoAmI`](https://nextmail.sh/docs/mcp/tools/workspace#whoAmI).

### `GET /keys/self`

What this key is

Needs no scope: a key may always describe itself.

`scopes` is the EFFECTIVE list and the only one that authorises anything: the scopes on the key itself, intersected with the permissions of the role it was issued under. `grantedScopes` is what the key was created holding, and `roleId` names the ceiling that narrowed it, so anything in the first list and missing from the second was removed by that role.

That difference is the answer to the confusing 403. A key created with `emails:send` and capped by a viewer role is refused for lacking `emails:send`, which reads as a lie against the key the console is displaying; the fix is to change the role rather than to mint another key. `roleId` is null on a key with no ceiling, which is what every key issued before roles existed still has.

Two independent lists narrow what the key may send as. `domainAllowlist` holds whole domains, and the key may send as any address on one of them, including addresses created after the key was. `addressAllowlist` holds individual addresses. Both null or both empty means the key may send as any address the workspace owns. With either one set the key is narrowed, and reads of sent mail, tracking and calendar narrow to the same set. An address whose domain is already in `domainAllowlist` is dropped from `addressAllowlist` when the lists are written, so the two never overlap.

- Needs an API key or an OAuth access token, and no scope.

**Returns**

- `200` `KeySelf`: Id, mode, effective scopes, the role capping them, and both allowlists.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.me.get()`](https://nextmail.sh/docs/sdk/reference/me#get); Python [`me.get()`](https://nextmail.sh/docs/python/reference/me#get); Ruby [`me.get`](https://nextmail.sh/docs/ruby/reference/me#get); PHP [`me->get`](https://nextmail.sh/docs/php/reference/me#get); Go [`Me.Get`](https://nextmail.sh/docs/go/reference/me#get); Java [`me().get`](https://nextmail.sh/docs/java/reference/me#get); C# [`Me.GetAsync`](https://nextmail.sh/docs/csharp/reference/me#get); CLI [`nextmail me get`](https://nextmail.sh/docs/cli/reference/me#me-get); MCP [`whoAmI`](https://nextmail.sh/docs/mcp/tools/workspace#whoAmI).

### `POST /keys/self/rotate`

Replace this key's secret

Mints a new secret for the key making the call and returns it once. There is no body and no way to name another key here: this call rotates the caller and nothing else, and `POST /keys/{id}/rotate` is the one that reaches other keys, behind `keys:manage`.

The old secret stops working the instant this returns. There is no overlap window and no grace period, and the response is the only place the new secret ever appears, so a caller that drops it has locked itself out until somebody in the console rotates the key again.

Everything else about the key is unchanged: same id, same name, same mode, same scopes, same role, same allowlists and same expiry. Only the last four characters move, because they are part of the secret. The request history hangs off the id rather than off the secret, so it runs straight through a rotation and reads as one key on both sides of it rather than as two.

Weigh that before granting `keys:write`. A stolen key holding it can rotate itself and take the secret away from the person who owns the key. It cannot hide while doing so, because the id does not move and revoking it from the console still works.

Requires the `keys:write` scope.

- Scopes: `keys:write`.

**Returns**

- `200` `RotatedKeySelf`: The body of `GET /keys/self`, plus `token`, the new secret in full and for the only time, `rotationCount`, an integer counting every rotation this key has had, and `rotatedAt`, when this one landed, ISO-8601.

**Errors**

- `403`: `insufficient_scope`: the key lacks `keys:write`. `api_key_only`: the request carried an OAuth access token, which has no secret to rotate.
- `404`: `resource_not_found`: the key is gone. It authenticated this request and was deleted before the rotation landed, which is the only way to reach this.
- `409`: `revoked`: the key was revoked between authenticating this request and rotating it. `expired`: it passed its expiry in the same gap. Neither is rotatable, and a key in either state authenticates nothing afterwards, so the answer is a new key from the console.
- The errors every operation can return: `400`, `401`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.me.rotate()`](https://nextmail.sh/docs/sdk/reference/me#rotate); Python [`me.rotate()`](https://nextmail.sh/docs/python/reference/me#rotate); Ruby [`me.rotate`](https://nextmail.sh/docs/ruby/reference/me#rotate); PHP [`me->rotate`](https://nextmail.sh/docs/php/reference/me#rotate); Go [`Me.Rotate`](https://nextmail.sh/docs/go/reference/me#rotate); Java [`me().rotate`](https://nextmail.sh/docs/java/reference/me#rotate); C# [`Me.RotateAsync`](https://nextmail.sh/docs/csharp/reference/me#rotate); CLI [`nextmail me rotate`](https://nextmail.sh/docs/cli/reference/me#me-rotate).

### `GET /keys/self/requests`

List this key's requests

The request log of the key making the call, newest first: every authenticated call it made, with method, path, status, error code, duration, IP and user agent, never a body or a query string. Needs no scope: a key may always read its own log, and it reads no other key's here. `GET /keys/{id}/requests` and `GET /keys/requests` are the ones that reach other keys, behind `keys:read`.

`failedOnly`, `status`, `path`, `since` and `until` narrow it, and they combine. Nothing is pruned, so the log reaches back to the key's first call, and it runs straight through a rotation because it hangs off the key id. The call that reads the log is logged too.

- Needs an API key or an OAuth access token, and no scope.

**Query parameters**

- `failedOnly` (`boolean`, default `false`): Only calls answered with a status of 400 or more.
- `status` (`string`): Only calls answered with one of these HTTP status codes, comma-separated, such as `401,403`. At most 20 codes, each from 100 to 599. Anything else is a 422 `invalid_parameter`.
- `path` (`string`): Only calls to this route, whatever the method, such as `/emails` or `/emails/:id`. The log matches the route, not the exact path: an id in the path counts as `:id` and an email address as `:address`, so `/emails/4c1b257a66287fd113bd89d0` reads every call to `/emails/:id`. End it with `*` to read every route that starts with it, such as `/emails/*`. It takes no query string, and a value that is not a path is a 422 `invalid_parameter`.
- `since` (`string`, format `date-time`): Only rows at or after this instant, ISO 8601. One that does not parse is a 400 `invalid_parameter`.
- `until` (`string`, format `date-time`): Only rows before this instant. It has to be later than `since`.
- `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100.
- `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`.

**Returns**

- `200` `ApiKeyRequestList`: A page of calls, newest first.

**Errors**

- `403`: `api_key_only`: the request carried an OAuth access token. Calls made with one are not logged, so there is nothing to read.
- The errors every operation can return: `400`, `401`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.me.listRequests()`](https://nextmail.sh/docs/sdk/reference/me#listRequests), [`nextmail.me.listAllRequests()`](https://nextmail.sh/docs/sdk/reference/me#listAllRequests), [`nextmail.me.iterateRequests()`](https://nextmail.sh/docs/sdk/reference/me#iterateRequests); Python [`me.list_requests()`](https://nextmail.sh/docs/python/reference/me#listRequests), [`me.list_all_requests()`](https://nextmail.sh/docs/python/reference/me#listAllRequests), [`me.iterate_requests()`](https://nextmail.sh/docs/python/reference/me#iterateRequests); Ruby [`me.list_requests`](https://nextmail.sh/docs/ruby/reference/me#listRequests), [`me.list_all_requests`](https://nextmail.sh/docs/ruby/reference/me#listAllRequests), [`me.iterate_requests`](https://nextmail.sh/docs/ruby/reference/me#iterateRequests); PHP [`me->listRequests`](https://nextmail.sh/docs/php/reference/me#listRequests), [`me->listAllRequests`](https://nextmail.sh/docs/php/reference/me#listAllRequests), [`me->iterateRequests`](https://nextmail.sh/docs/php/reference/me#iterateRequests); Go [`Me.ListRequests`](https://nextmail.sh/docs/go/reference/me#listRequests), [`Me.ListAllRequests`](https://nextmail.sh/docs/go/reference/me#listAllRequests), [`Me.IterateRequests`](https://nextmail.sh/docs/go/reference/me#iterateRequests); Java [`me().listRequests`](https://nextmail.sh/docs/java/reference/me#listRequests), [`me().listAllRequests`](https://nextmail.sh/docs/java/reference/me#listAllRequests), [`me().iterateRequests`](https://nextmail.sh/docs/java/reference/me#iterateRequests); C# [`Me.ListRequestsAsync`](https://nextmail.sh/docs/csharp/reference/me#listRequests), [`Me.ListAllRequestsAsync`](https://nextmail.sh/docs/csharp/reference/me#listAllRequests), [`Me.IterateRequestsAsync`](https://nextmail.sh/docs/csharp/reference/me#iterateRequests); CLI [`nextmail me list-requests`](https://nextmail.sh/docs/cli/reference/me#me-list-requests).

### `GET /keys/self/activity`

List this key's activity

What happened to the key making the call, newest first: created, updated, rotated, deactivated, reactivated, and every attempt to authenticate with it that was refused. `actor` says who, a person as `@username` or a key as `API key <name>`, and `detail.source` where from. Needs no scope, and it reads no other key's history: `GET /keys/{id}/activity` and `GET /keys/activity` do that, behind `keys:read`. `since` and `until` narrow it.

- Needs an API key or an OAuth access token, and no scope.

**Query parameters**

- `since` (`string`, format `date-time`): Only rows at or after this instant, ISO 8601. One that does not parse is a 400 `invalid_parameter`.
- `until` (`string`, format `date-time`): Only rows before this instant. It has to be later than `since`.
- `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100.
- `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`.

**Returns**

- `200` `ApiKeyActivityList`: A page of changes, newest first.

**Errors**

- `403`: `api_key_only`: the request carried an OAuth access token, which is not a key and has no key history.
- The errors every operation can return: `400`, `401`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.me.listActivity()`](https://nextmail.sh/docs/sdk/reference/me#listActivity), [`nextmail.me.listAllActivity()`](https://nextmail.sh/docs/sdk/reference/me#listAllActivity), [`nextmail.me.iterateActivity()`](https://nextmail.sh/docs/sdk/reference/me#iterateActivity); Python [`me.list_activity()`](https://nextmail.sh/docs/python/reference/me#listActivity), [`me.list_all_activity()`](https://nextmail.sh/docs/python/reference/me#listAllActivity), [`me.iterate_activity()`](https://nextmail.sh/docs/python/reference/me#iterateActivity); Ruby [`me.list_activity`](https://nextmail.sh/docs/ruby/reference/me#listActivity), [`me.list_all_activity`](https://nextmail.sh/docs/ruby/reference/me#listAllActivity), [`me.iterate_activity`](https://nextmail.sh/docs/ruby/reference/me#iterateActivity); PHP [`me->listActivity`](https://nextmail.sh/docs/php/reference/me#listActivity), [`me->listAllActivity`](https://nextmail.sh/docs/php/reference/me#listAllActivity), [`me->iterateActivity`](https://nextmail.sh/docs/php/reference/me#iterateActivity); Go [`Me.ListActivity`](https://nextmail.sh/docs/go/reference/me#listActivity), [`Me.ListAllActivity`](https://nextmail.sh/docs/go/reference/me#listAllActivity), [`Me.IterateActivity`](https://nextmail.sh/docs/go/reference/me#iterateActivity); Java [`me().listActivity`](https://nextmail.sh/docs/java/reference/me#listActivity), [`me().listAllActivity`](https://nextmail.sh/docs/java/reference/me#listAllActivity), [`me().iterateActivity`](https://nextmail.sh/docs/java/reference/me#iterateActivity); C# [`Me.ListActivityAsync`](https://nextmail.sh/docs/csharp/reference/me#listActivity), [`Me.ListAllActivityAsync`](https://nextmail.sh/docs/csharp/reference/me#listAllActivity), [`Me.IterateActivityAsync`](https://nextmail.sh/docs/csharp/reference/me#iterateActivity); CLI [`nextmail me list-activity`](https://nextmail.sh/docs/cli/reference/me#me-list-activity).

### `GET /ping`

Auth smoke test

- Needs an API key or an OAuth access token, and no scope.

**Returns**

- `200` `Ping`: ok, with the effective scopes and the role that capped them.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.me.ping()`](https://nextmail.sh/docs/sdk/reference/me#ping); Python [`me.ping()`](https://nextmail.sh/docs/python/reference/me#ping); Ruby [`me.ping`](https://nextmail.sh/docs/ruby/reference/me#ping); PHP [`me->ping`](https://nextmail.sh/docs/php/reference/me#ping); Go [`Me.Ping`](https://nextmail.sh/docs/go/reference/me#ping); Java [`me().ping`](https://nextmail.sh/docs/java/reference/me#ping); C# [`Me.PingAsync`](https://nextmail.sh/docs/csharp/reference/me#ping); CLI [`nextmail me ping`](https://nextmail.sh/docs/cli/reference/me#me-ping).

### `GET /keys/self/stats`

Read this key's stats

What the key making the call did inside a window: the requests it made and how many failed, the calls refused because its secret was wrong, revoked or expired, the 8 routes it called most with the median time each took, and the status codes it got back. Needs no scope: a key may always read its own figures, and it reads no other key's here. `GET /keys/stats` is the one that reaches other keys.

`sends`, the mail the key sent and what became of it, is filled only when the key holds `emails:read`. Without that scope it is `null`, never zeros, so a missing permission cannot read as a quiet week.

- Needs an API key or an OAuth access token, and no scope.

**Query parameters**

- `since` (`string`, format `date-time`): The start of the window, an ISO 8601 instant. Left out, 30 days before `until`.
- `until` (`string`, format `date-time`): The end of the window, an ISO 8601 instant, not included. Left out, now.
- `grain` (`string`, one of `"minute"`, `"hour"`, `"day"`, default `"day"`): How wide one bucket of the series is. The bucket keys change shape with it: `YYYY-MM-DD` for a day, `YYYY-MM-DDTHH` for an hour, `YYYY-MM-DDTHH:MM` for a minute.
- `offsetMinutes` (`integer`, at least -840, at most 840, default `0`): Minutes to add to UTC before cutting the buckets, so a day starts at midnight where the reader is. 120 for UTC+2.

**Returns**

- `200` `KeySelfStats`: The figures for the window.

**Errors**

- `403`: `api_key_only`: the request carried an OAuth access token. Calls made with one are not logged, so there are no figures to read.
- The errors every operation can return: `400`, `401`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.me.stats()`](https://nextmail.sh/docs/sdk/reference/me#stats); Python [`me.stats()`](https://nextmail.sh/docs/python/reference/me#stats); Ruby [`me.stats`](https://nextmail.sh/docs/ruby/reference/me#stats); PHP [`me->stats`](https://nextmail.sh/docs/php/reference/me#stats); Go [`Me.Stats`](https://nextmail.sh/docs/go/reference/me#stats); Java [`me().stats`](https://nextmail.sh/docs/java/reference/me#stats); C# [`Me.StatsAsync`](https://nextmail.sh/docs/csharp/reference/me#stats); CLI [`nextmail me stats`](https://nextmail.sh/docs/cli/reference/me#me-stats).

### Objects

#### `ApiKeyActivityEntry`

`object`

- `object` (`string`, one of `"api_key_event"`)
- `id` (`string`)
- `keyId` (`string`)
- `keyName` (`string`): `Deleted key` once the key itself is gone.
- `type` (`string`, one of `"created"`, `"updated"`, `"rotated"`, `"revoked"`, `"deactivated"`, `"reactivated"`, `"auth_failed"`, `"deleted"`)
- `createdAt` (`string`, format `date-time`)
- `actor` (`AuditActor`)
- `detail` (`object`): What changed and where it was changed from (`source`: console, api, mcp or documentation). A refused authentication carries `reason`, and `via: smtp` when it was an SMTP sign-in.

#### `ApiKeyActivityList`

`object`

- `object` (`string`, one of `"list"`)
- `data` (`ApiKeyActivityEntry[]`)
- `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it.
- `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged.

#### `ApiKeyRequest`

`object`

One authenticated call a key made, or one message it handed over SMTP. Never a body or a query string.

- `object` (`string`, one of `"api_key_request"`)
- `id` (`string`)
- `keyId` (`string`)
- `keyName` (`string`): `Deleted key` once the key itself is gone.
- `requestId` (`string`, nullable): The `X-Request-Id` the call was answered with.
- `method` (`string`): The HTTP method, or `SMTP` for a message the key handed over SMTP.
- `path` (`string`): The path that was called. A message handed over SMTP is logged as `/emails`.
- `status` (`integer`): The HTTP status. A message handed over SMTP carries the status the same send would have had over REST.
- `errorCode` (`string`, nullable)
- `durationMs` (`integer`)
- `ip` (`string`, nullable)
- `userAgent` (`string`, nullable): `smtp` for a message handed over SMTP.
- `createdAt` (`string`, format `date-time`)

#### `ApiKeyRequestList`

`object`

- `object` (`string`, one of `"list"`)
- `data` (`ApiKeyRequest[]`)
- `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it.
- `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged.

#### `AuditActor`

`object`

Who made the change: a person, or a key acting over the API. Null when Nextmail made it on its own, such as switching a webhook off after 100 failed events in a row, and when the person or key has since been deleted.

nullable

- `kind` (`string`, one of `"user"`, `"apiKey"`)
- `id` (`string`): The account id of the person, or the id of the key.
- `name` (`string`): The name of the person, or `API key <name>` for a key.
- `username` (`string`, nullable)
- `label` (`string`): What the app shows: `@username` for a person who has a username, otherwise `name`.

#### `KeySelf`

`object`

- `object` (`string`, required, one of `"api_key"`, `"oauth_token"`)
- `kind` (`string`, required, one of `"apiKey"`, `"oauth"`)
- `id` (`string`, required, nullable): The key id. Null for an access token.
- `clientId` (`string`): The app the access token belongs to. Only on an access token.
- `mode` (`string`, required, one of `"live"`, `"test"`)
- `scopes` (`string[]`, required, one of `"emails:send"`, `"emails:read"`, `"drafts:read"`, `"drafts:write"`, `"threads:read"`, `"threads:write"`, `"files:read"`, `"files:write"`, `"labels:read"`, `"labels:write"`, `"contacts:read"`, `"contacts:write"`, `"audiences:read"`, `"audiences:write"`, `"calendar:read"`, `"calendar:write"`, `"templates:read"`, `"templates:write"`, `"domains:read"`, `"domains:write"`, `"webhooks:read"`, `"webhooks:write"`, `"rules:read"`, `"rules:write"`, `"connections:read"`, `"members:read"`, `"members:write"`, `"roles:read"`, `"roles:write"`, `"settings:read"`, `"settings:write"`, `"keys:write"`, `"keys:read"`, `"keys:manage"`, `"forms:read"`, `"forms:write"`, `"knowledge:read"`, `"knowledge:write"`, `"automations:read"`, `"automations:write"`, `"tasks:read"`, `"tasks:write"`, `"connectors:read"`, `"connectors:use"`, `"connectors:write"`, `"billing:read"`, `"billing:write"`, `"account:read"`, `"account:write"`): What this credential may do now: its own scopes held to the role it acts under.
- `roleId` (`string`, required, nullable): The role the credential acts under. Null for none.
- `grantedScopes` (`string[]`, required, one of `"emails:send"`, `"emails:read"`, `"drafts:read"`, `"drafts:write"`, `"threads:read"`, `"threads:write"`, `"files:read"`, `"files:write"`, `"labels:read"`, `"labels:write"`, `"contacts:read"`, `"contacts:write"`, `"audiences:read"`, `"audiences:write"`, `"calendar:read"`, `"calendar:write"`, `"templates:read"`, `"templates:write"`, `"domains:read"`, `"domains:write"`, `"webhooks:read"`, `"webhooks:write"`, `"rules:read"`, `"rules:write"`, `"connections:read"`, `"members:read"`, `"members:write"`, `"roles:read"`, `"roles:write"`, `"settings:read"`, `"settings:write"`, `"keys:write"`, `"keys:read"`, `"keys:manage"`, `"forms:read"`, `"forms:write"`, `"knowledge:read"`, `"knowledge:write"`, `"automations:read"`, `"automations:write"`, `"tasks:read"`, `"tasks:write"`, `"connectors:read"`, `"connectors:use"`, `"connectors:write"`, `"billing:read"`, `"billing:write"`, `"account:read"`, `"account:write"`): The scopes it was given, before the role narrows them.
- `workspaceId` (`string`, required)
- `addressAllowlist` (`string[]`, required, nullable): The single addresses it is limited to. Null when it is not limited to any.
- `domainAllowlist` (`string[]`, required, nullable): The domains it is limited to. Null when it is not limited to any.
- `expiresAt` (`string`, nullable, format `date-time`): When the approval behind the access token ends. Only on an access token.

#### `KeySelfStats`

`object`

- `object` (`string`, required, one of `"api_key_stats"`)
- `since` (`string`, required, format `date-time`)
- `until` (`string`, required, format `date-time`)
- `grain` (`string`, required, one of `"minute"`, `"hour"`, `"day"`)
- `keyIds` (`string[]`, required): The id of the key making the call, and nothing else.
- `sends` (`object`, required, nullable): The mail the key sent, with what became of it. `null` when the key does not hold `emails:read`, never zeros.
  - `days` (`object[]`)
    - `day` (`string`): The bucket, shaped by `grain`.
    - `sent` (`integer`)
    - `delivered` (`integer`)
    - `failed` (`integer`)
    - `bounced` (`integer`)
    - `complained` (`integer`)
  - `totals` (`object`)
    - `sends` (`integer`)
    - `testSends` (`integer`)
    - `recipients` (`integer`)
    - `delivered` (`integer`)
    - `failed` (`integer`)
    - `bounced` (`integer`)
    - `complained` (`integer`)
    - `uncertain` (`integer`)
    - `pending` (`integer`)
  - `statuses` (`object[]`): Sends by status.
    - `label` (`string`)
    - `count` (`integer`)
  - `sources` (`object[]`): Sends by where they came from.
    - `label` (`string`)
    - `count` (`integer`)
  - `senders` (`object[]`): Sends by the address they went out as.
    - `label` (`string`)
    - `count` (`integer`)
  - `suppressed` (`object[]`): Recipients skipped because they were suppressed, by reason.
    - `label` (`string`)
    - `count` (`integer`)
- `rejected` (`object[]`, required): Calls refused because the secret was wrong, revoked or expired, per bucket.
  - `bucket` (`string`)
  - `count` (`integer`)
- `requests` (`object[]`, required): Requests made and how many of them failed with a 4xx or 5xx, per bucket.
  - `bucket` (`string`)
  - `count` (`integer`)
  - `failed` (`integer`)
- `routes` (`object[]`, required): The routes called most, with how many failed and the median time in milliseconds.
  - `label` (`string`)
  - `count` (`integer`)
  - `failed` (`integer`)
  - `medianMs` (`integer`)
- `codes` (`object[]`, required): Requests by the HTTP status they got back.
  - `label` (`string`)
  - `count` (`integer`)

#### `Ping`

`object`

- `ok` (`boolean`, required, one of `true`)
- `kind` (`string`, required, one of `"apiKey"`, `"oauth"`)
- `keyId` (`string`, required, nullable): The key id. Null for an access token.
- `clientId` (`string`): The app the access token belongs to. Only on an access token.
- `mode` (`string`, required, one of `"live"`, `"test"`)
- `scopes` (`string[]`, required, one of `"emails:send"`, `"emails:read"`, `"drafts:read"`, `"drafts:write"`, `"threads:read"`, `"threads:write"`, `"files:read"`, `"files:write"`, `"labels:read"`, `"labels:write"`, `"contacts:read"`, `"contacts:write"`, `"audiences:read"`, `"audiences:write"`, `"calendar:read"`, `"calendar:write"`, `"templates:read"`, `"templates:write"`, `"domains:read"`, `"domains:write"`, `"webhooks:read"`, `"webhooks:write"`, `"rules:read"`, `"rules:write"`, `"connections:read"`, `"members:read"`, `"members:write"`, `"roles:read"`, `"roles:write"`, `"settings:read"`, `"settings:write"`, `"keys:write"`, `"keys:read"`, `"keys:manage"`, `"forms:read"`, `"forms:write"`, `"knowledge:read"`, `"knowledge:write"`, `"automations:read"`, `"automations:write"`, `"tasks:read"`, `"tasks:write"`, `"connectors:read"`, `"connectors:use"`, `"connectors:write"`, `"billing:read"`, `"billing:write"`, `"account:read"`, `"account:write"`): What this credential may do now: its own scopes held to the role it acts under.
- `roleId` (`string`, required, nullable): The role the credential acts under. Null for none.
- `grantedScopes` (`string[]`, required, one of `"emails:send"`, `"emails:read"`, `"drafts:read"`, `"drafts:write"`, `"threads:read"`, `"threads:write"`, `"files:read"`, `"files:write"`, `"labels:read"`, `"labels:write"`, `"contacts:read"`, `"contacts:write"`, `"audiences:read"`, `"audiences:write"`, `"calendar:read"`, `"calendar:write"`, `"templates:read"`, `"templates:write"`, `"domains:read"`, `"domains:write"`, `"webhooks:read"`, `"webhooks:write"`, `"rules:read"`, `"rules:write"`, `"connections:read"`, `"members:read"`, `"members:write"`, `"roles:read"`, `"roles:write"`, `"settings:read"`, `"settings:write"`, `"keys:write"`, `"keys:read"`, `"keys:manage"`, `"forms:read"`, `"forms:write"`, `"knowledge:read"`, `"knowledge:write"`, `"automations:read"`, `"automations:write"`, `"tasks:read"`, `"tasks:write"`, `"connectors:read"`, `"connectors:use"`, `"connectors:write"`, `"billing:read"`, `"billing:write"`, `"account:read"`, `"account:write"`): The scopes it was given, before the role narrows them.
- `workspaceId` (`string`, required)

#### `RotatedKeySelf`

`object`

- `object` (`string`, required, one of `"api_key"`)
- `id` (`string`, required)
- `mode` (`string`, required, one of `"live"`, `"test"`)
- `scopes` (`string[]`, required, one of `"emails:send"`, `"emails:read"`, `"drafts:read"`, `"drafts:write"`, `"threads:read"`, `"threads:write"`, `"files:read"`, `"files:write"`, `"labels:read"`, `"labels:write"`, `"contacts:read"`, `"contacts:write"`, `"audiences:read"`, `"audiences:write"`, `"calendar:read"`, `"calendar:write"`, `"templates:read"`, `"templates:write"`, `"domains:read"`, `"domains:write"`, `"webhooks:read"`, `"webhooks:write"`, `"rules:read"`, `"rules:write"`, `"connections:read"`, `"members:read"`, `"members:write"`, `"roles:read"`, `"roles:write"`, `"settings:read"`, `"settings:write"`, `"keys:write"`, `"keys:read"`, `"keys:manage"`, `"forms:read"`, `"forms:write"`, `"knowledge:read"`, `"knowledge:write"`, `"automations:read"`, `"automations:write"`, `"tasks:read"`, `"tasks:write"`, `"connectors:read"`, `"connectors:use"`, `"connectors:write"`, `"billing:read"`, `"billing:write"`, `"account:read"`, `"account:write"`): What this credential may do now: its own scopes held to the role it acts under.
- `roleId` (`string`, required, nullable): The role the credential acts under. Null for none.
- `grantedScopes` (`string[]`, required, one of `"emails:send"`, `"emails:read"`, `"drafts:read"`, `"drafts:write"`, `"threads:read"`, `"threads:write"`, `"files:read"`, `"files:write"`, `"labels:read"`, `"labels:write"`, `"contacts:read"`, `"contacts:write"`, `"audiences:read"`, `"audiences:write"`, `"calendar:read"`, `"calendar:write"`, `"templates:read"`, `"templates:write"`, `"domains:read"`, `"domains:write"`, `"webhooks:read"`, `"webhooks:write"`, `"rules:read"`, `"rules:write"`, `"connections:read"`, `"members:read"`, `"members:write"`, `"roles:read"`, `"roles:write"`, `"settings:read"`, `"settings:write"`, `"keys:write"`, `"keys:read"`, `"keys:manage"`, `"forms:read"`, `"forms:write"`, `"knowledge:read"`, `"knowledge:write"`, `"automations:read"`, `"automations:write"`, `"tasks:read"`, `"tasks:write"`, `"connectors:read"`, `"connectors:use"`, `"connectors:write"`, `"billing:read"`, `"billing:write"`, `"account:read"`, `"account:write"`): The scopes it was given, before the role narrows them.
- `workspaceId` (`string`, required)
- `addressAllowlist` (`string[]`, required, nullable): The single addresses it is limited to. Null when it is not limited to any.
- `domainAllowlist` (`string[]`, required, nullable): The domains it is limited to. Null when it is not limited to any.
- `token` (`string`, required): The new secret, shown this once. The old one stops working now.
- `rotationCount` (`integer`, required, at least 1)
- `rotatedAt` (`string`, required, format `date-time`)

#### `SendableAddress`

`object`

- `object` (`string`, required, one of `"address"`)
- `address` (`string`, required, format `email`)
- `enabled` (`boolean`, required)
- `canSend` (`boolean`, required)

#### `SendableAddressList`

`object`

- `object` (`string`, one of `"list"`)
- `data` (`SendableAddress[]`)
- `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it.
- `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged.
- `unrestricted` (`boolean`): True only on a key with neither allowlist set: any local-part on a verified domain is accepted.
- `domains` (`SendableDomain[]`)

#### `SendableDomain`

`object`

- `domain` (`string`, required)
- `receivingVerified` (`boolean`, required)
- `sendingVerified` (`boolean`, required)
- `catchAll` (`boolean`, required)