@sperax/tool-gmail

Read, compose, search, and manage Gmail emails

Gmail is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-gmail

Usage

Call it directly

import { gmailExecutor } from '@sperax/tool-gmail';

const result = await gmailExecutor.invoke('listEmails', {"labelIds":"<labelIds>","maxResults":"<maxResults>"}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { GmailManifest, gmailExecutor } from '@sperax/tool-gmail';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: GmailManifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await gmailExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

GmailManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-gmail

API reference

listEmails

List recent emails from the inbox with optional filters.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | labelIds | array | no | Filter by label IDs (e.g., INBOX, SENT, DRAFT) | | maxResults | integer | no | Maximum number of emails to return (default: 10) | | query | string | no | Optional Gmail search query to filter results |

getEmail

Get a specific email by its ID, including full body and headers.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | emailId | string | yes | The unique ID of the email to retrieve |

searchEmails

Search emails using Gmail search syntax (from:, to:, subject:, has:attachment, etc.).

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | maxResults | integer | no | Maximum number of results to return | | query | string | yes | Gmail search query string |

composeEmail

Compose and send a new email. Requires user confirmation before sending.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | bcc | string | no | BCC recipients (comma-separated) | | body | string | yes | Email body content (plain text or HTML) | | cc | string | no | CC recipients (comma-separated) | | subject | string | yes | Email subject line | | to | string | yes | Recipient email addresses (comma-separated) |

createDraft

Create a draft email without sending it.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | bcc | string | no | BCC recipients (comma-separated) | | body | string | yes | Email body content | | cc | string | no | CC recipients (comma-separated) | | subject | string | yes | Email subject line | | to | string | yes | Recipient email addresses (comma-separated) |

replyToEmail

Reply to an existing email thread. Requires user confirmation.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | body | string | yes | Reply body content | | emailId | string | yes | The ID of the email to reply to |

deleteEmail

Move an email to trash. Requires user confirmation.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | emailId | string | yes | The ID of the email to delete |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-gmail is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0