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

const client = createClient(); // reads MAILS_API_KEY

const result = await client.connected_apps.list({
  limit: 10,
});
console.log(result);
{
  "data": [
    {
      "id": "oag_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "client_id": "<client_id>",
      "client_name": "<client_name>",
      "first_party": false,
      "scope": "<scope>",
      "scopes": ["send"],
      "created_at": "2026-10-04T12:00:00.000Z",
      "approved_at": "2026-10-04T12:00:00.000Z",
      "last_used_at": "2026-10-04T12:00:00.000Z",
      "created_api_keys": 0,
      "created_webhooks": 0,
      "signing_secrets_known": 0
    }
  ],
  "has_more": false,
  "next_cursor": "<next_cursor>"
}

List connected apps

The apps connected to this workspace by signing in, whoever in it connected them: the mails CLI and apps such as Claude, ChatGPT or Cursor.
GET/v1/oauth/grantsscope · manage
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.connected_apps.list({
  limit: 10,
});
console.log(result);
{
  "data": [
    {
      "id": "oag_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "client_id": "<client_id>",
      "client_name": "<client_name>",
      "first_party": false,
      "scope": "<scope>",
      "scopes": ["send"],
      "created_at": "2026-10-04T12:00:00.000Z",
      "approved_at": "2026-10-04T12:00:00.000Z",
      "last_used_at": "2026-10-04T12:00:00.000Z",
      "created_api_keys": 0,
      "created_webhooks": 0,
      "signing_secrets_known": 0
    }
  ],
  "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.

Only those that can still act are listed, newest first: one revoked, or whose tokens have all expired or been signed out, is not. Settings › Connected apps in the dashboard shows the same apps to everyone in the workspace. There, a member can revoke the apps they connected, and an owner or admin can revoke any of them. Closed to apps connected by sign-in (403 connected_app_not_allowed), and to a key tied to one agent (403): use an API key with manage that is not tied to an agent, or the mails CLI.

Response

dataobject[]

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

Show propertiesHide properties
idstring

The sign-in's id (oag_…). Approving the same app again in the same workspace keeps it.

client_idstring

The app's OAuth client id: the id it registered with, or the address of its client-ID document. The mails CLI's is https://api.mails.ai/oauth/clients/cli.

client_namestring | null

The name the app gave itself; mails CLI for the mails CLI.

first_partyboolean

true for the mails CLI, false for an app somebody connected by signing in (Claude, ChatGPT, Cursor …).

scopestring

What the person approved: full_access, send or read.

scopesstring[]

What its tokens may do, in the API key scopes: full_access = send + read + manage, send = send + read, read = read. Never more than the role of the person who approved it gives an app now: a Member's apps never hold manage, and a Billing member's hold read only.

One of: send, read, manage

created_atstring

When it was first approved.

approved_atstring

When it was last approved.

last_used_atstring | null

When one of its tokens was last used.

created_api_keysinteger

API keys it created that still work (only the mails CLI, and keys it made, can create any). Revoking the app leaves them working: revoke them under API keys.

created_webhooksinteger

Webhook endpoints it created (only the mails CLI, and keys it made, can create any). Revoking the app leaves them in place.

signing_secrets_knowninteger

Other webhook endpoints still signing with a secret it was shown. Revoking the app leaves those secrets in use: rotate them (POST /v1/webhooks/{id}/rotate-secret).

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?