Skip to main content
Get Started
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.api_keys.list({ limit: 10 });
console.log(result);
{
  "data": [
    {
      "id": "key_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "prefix": "<prefix>",
      "name": "<name>",
      "mode": "live",
      "scopes": ["send"],
      "agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "last_used_at": "<last_used_at>",
      "expires_at": "<expires_at>",
      "revoked_at": "<revoked_at>",
      "created_at": "<created_at>"
    }
  ],
  "has_more": false,
  "next_cursor": "<next_cursor>"
}

List API keys

Lists the workspace's API keys, newest first, without their plaintext.
GET/v1/api-keysscope · read
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.api_keys.list({ limit: 10 });
console.log(result);
{
  "data": [
    {
      "id": "key_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "prefix": "<prefix>",
      "name": "<name>",
      "mode": "live",
      "scopes": ["send"],
      "agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "last_used_at": "<last_used_at>",
      "expires_at": "<expires_at>",
      "revoked_at": "<revoked_at>",
      "created_at": "<created_at>"
    }
  ],
  "has_more": false,
  "next_cursor": "<next_cursor>"
}

Query Parameters

limitinteger

Page size (1–100).

Default: 25

cursorstring

Opaque cursor from a previous page's next_cursor.

A key tied to one agent lists only the keys tied to that same agent.

Response

dataobject[]

The items on this page, at most limit of them.

Show propertiesHide properties
idstring

API key id (key_…); DELETE /v1/api-keys/{id} revokes the key.

prefixstring

The key's first 12 characters (e.g. mk_live_a1b2): the only part ever shown after creation.

namestring | null

The label given when the key was created, or null.

modestring

live or test, set when the key was created. A test key's sends are stored but never transmitted or billed.

One of: live, test

scopesstring[]

The scopes the key holds, set when it was created; * passes every scope check.

One of: send, read, manage, draft, *

agent_idstring | null

The agent the key is tied to (agt_…), or null for a key that reaches every agent.

last_used_atstring | null

When the key last authenticated a request. Null until its first use.

expires_atstring | null

When the key stops working (401 expired_api_key after that). Null for a key that never expires; an expired key stays in the list.

revoked_atstring | null

When the key was revoked, or null. Revoked keys stay in the list.

created_atstring

When the key was created.

has_moreboolean

True when more items follow this page: pass next_cursor as cursor to get them.

next_cursorstring

Pass as cursor to fetch the next page. Absent on the last page.

Was this page helpful?