From 82068eac082e0b27106c6a7cc1dff8bdadc606d9 Mon Sep 17 00:00:00 2001 From: Sidharth Reddy <70673367+sidharth0612@users.noreply.github.com> Date: Mon, 5 Oct 2026 16:01:52 -0700 Subject: [PATCH 1/2] Track AgentMail SDK TypeScript 0.5.36 and Python 2.0.9 Pin the SDK releases from 2026-10-05 in compatibility.json and extend the signature fixtures to the surface they add: inbox status (pause/resume on create and update) and the app category filter on apps.list plus App.categories. No packaged skill changes, so no plugin release. Co-Authored-By: Claude Opus 5.5 --- compatibility.json | 6 +++--- tests/sdk_typescript.ts | 9 +++++++++ tests/test_sdk_signatures.py | 4 +++- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/compatibility.json b/compatibility.json index aa77b47..aa332be 100644 --- a/compatibility.json +++ b/compatibility.json @@ -1,8 +1,8 @@ { - "verifiedAt": "2026-10-02", + "verifiedAt": "2026-10-05", "agentmail": { - "typescript": "0.5.35", - "python": "2.0.8" + "typescript": "0.5.36", + "python": "2.0.9" }, "cli": "1.8.0", "toolkit": { diff --git a/tests/sdk_typescript.ts b/tests/sdk_typescript.ts index d09218c..a053723 100644 --- a/tests/sdk_typescript.ts +++ b/tests/sdk_typescript.ts @@ -26,6 +26,15 @@ async function typecheckCurrentSdk(client: AgentMailClient): Promise { await client.inboxes.list({ limit: 20 }); await client.inboxes.get(inbox.inboxId); await client.inboxes.update(inbox.inboxId, { displayName: "Customer Support" }); + const paused = await client.inboxes.update(inbox.inboxId, { status: "paused" }); + void (paused.status === "paused"); + await client.inboxes.update(inbox.inboxId, { status: "active" }); + await client.inboxes.create({ username: "staging", status: "paused" }); + + const apps = await client.apps.list({ category: "search", limit: 20 }); + for (const app of apps.apps) { + void app.categories; + } const sent = await client.inboxes.messages.send(inbox.inboxId, { to: ["customer@example.com"], diff --git a/tests/test_sdk_signatures.py b/tests/test_sdk_signatures.py index b12e6e5..80dfc19 100644 --- a/tests/test_sdk_signatures.py +++ b/tests/test_sdk_signatures.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Check documented Python calls against agentmail 0.5.6 signatures.""" +"""Check documented Python calls against the agentmail version pinned in compatibility.json.""" import inspect @@ -16,6 +16,8 @@ def params(callable_object: object) -> set: assert "request" in create_params assert "username" not in create_params assert "client_id" not in create_params +assert {"inbox_id", "display_name", "status", "metadata"} <= params(client.inboxes.update) +assert {"limit", "page_token", "category"} <= params(client.apps.list) assert {"inbox_id", "to", "subject", "text"} <= params(client.inboxes.messages.send) assert {"inbox_id", "message_id"} <= params(client.inboxes.messages.get) From 6c41300b62f2de07cae760e0b8c61368e5eb7ca5 Mon Sep 17 00:00:00 2001 From: Sidharth Reddy <70673367+sidharth0612@users.noreply.github.com> Date: Mon, 5 Oct 2026 23:29:19 -0700 Subject: [PATCH 2/2] Release 0.6.0: app slugs and categories in the AgentID skill --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- .plugin/plugin.json | 2 +- CHANGELOG.md | 7 +++++++ compatibility.json | 10 +++++----- skills/agentid/SKILL.md | 14 ++++++++++---- skills/agentmail-mcp/SKILL.md | 3 ++- 8 files changed, 28 insertions(+), 14 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ca255b8..d5ca36c 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "agentmail", "displayName": "AgentMail", - "version": "0.5.0", + "version": "0.6.0", "description": "Email inboxes for agents. Create inboxes, send and receive emails, automate email workflows, and create accounts with AgentID.", "author": { "name": "AgentMail", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index ba2e368..3bf3b09 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmail", - "version": "0.5.0", + "version": "0.6.0", "description": "Email inboxes for agents. Create inboxes, send and receive emails, automate email workflows, and create accounts with AgentID.", "author": { "name": "AgentMail", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 9eebcfb..c1466b9 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmail", - "version": "0.5.0", + "version": "0.6.0", "description": "Email inboxes for agents. Create inboxes, send and receive emails, automate email workflows, and create accounts with AgentID.", "author": { "name": "AgentMail", diff --git a/.plugin/plugin.json b/.plugin/plugin.json index 25dcf80..276315e 100644 --- a/.plugin/plugin.json +++ b/.plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmail", - "version": "0.5.0", + "version": "0.6.0", "description": "Email inboxes for agents. Create inboxes, send and receive emails, automate email workflows, and create accounts with AgentID.", "author": { "name": "AgentMail", diff --git a/CHANGELOG.md b/CHANGELOG.md index 902ed5e..289d5d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ All notable changes to the AgentMail plugin are documented here. +## 0.6.0 - 2026-10-06 + +- The `agentid` skill finds a named app with `get_app` and the app's slug (`firecrawl`), falling back to `search_apps` when the slug 404s, as the hosted MCP's instructions now direct. Later steps pass the `appId` it returns; `list_accounts` and `connect_app` accept the slug too, but the ID is the permanent one to store. +- To find an app for a need, the `agentid` skill filters `list_apps` by `category` (such as `search`, `scraping`, or `payments`), pages until `nextPageToken` is absent since filtered pages can come back short, and falls back to the unfiltered list for apps without categories. +- The `agentmail-mcp` skill mentions slugs and the category filter, and explains that a session keeps the tool list it connected with: a tool or parameter missing from the session needs a new session or a connector reconnect. +- Track AgentMail SDK TypeScript 0.5.40 and Python 2.0.12, CLI 1.9.0, and AgentMail Toolkit TypeScript 0.11.0. The signature fixtures cover inbox `status` (pause and resume) and the `apps.list` category filter. + ## 0.5.0 - 2026-10-02 - AgentID calls the services an agent creates accounts at "apps" now, not "providers". The `agentid` and `agentmail-mcp` skills use the renamed hosted MCP tools: `list_apps`, `search_apps`, `get_app`, and `connect_app` replace `list_providers`, `search_providers`, `get_provider`, and `connect_provider`, with no aliases. They take `appId` and return `appId` and `appName`. `list_accounts` keeps its name. diff --git a/compatibility.json b/compatibility.json index aa332be..c98e036 100644 --- a/compatibility.json +++ b/compatibility.json @@ -1,12 +1,12 @@ { - "verifiedAt": "2026-10-05", + "verifiedAt": "2026-10-06", "agentmail": { - "typescript": "0.5.36", - "python": "2.0.9" + "typescript": "0.5.40", + "python": "2.0.12" }, - "cli": "1.8.0", + "cli": "1.9.0", "toolkit": { - "typescript": "0.10.0", + "typescript": "0.11.0", "python": "0.3.0" } } diff --git a/skills/agentid/SKILL.md b/skills/agentid/SKILL.md index d94b3d0..0c4c40f 100644 --- a/skills/agentid/SKILL.md +++ b/skills/agentid/SKILL.md @@ -21,7 +21,12 @@ The goal is almost never the sign-in itself. It is a working account the agent c ## Create an account -1. **Find the app.** Call `search_apps` with the name. One match: use it. Several: show name, description, and ID, and ask. Never pick between look-alike names yourself. No match and no ID: see [Not on AgentID](#not-on-agentid). If the user gave an app ID, skip search and call `get_app`; list and search show only the curated catalog, but any registered app resolves by ID and can be connected once it has a sign-in entry point. +1. **Find the app.** + - The user named the app: call `get_app` with its slug, the name lowercased without spaces or punctuation (`firecrawl`). A catalog app resolves in one call. + - The slug 404s: call `search_apps` with the name. One match: use it. Several: show name, description, and ID, and ask. Never pick between look-alike names yourself. No match: see [Not on AgentID](#not-on-agentid). + - The user gave an app ID: call `get_app` with it. List, search, and slugs cover only the curated catalog, but any registered app resolves by ID and can be connected once it has a sign-in entry point. + + From here on, pass the `appId` that `get_app` returned. `list_accounts` and `connect_app` also accept the slug, but the ID is permanent: use it in anything you store or report. 2. **Pick the inbox that will own the account.** The inbox is the agent's identity at the app. - The user named one: use it. - The organization has one inbox (`list_inboxes`): use it and say which. @@ -48,7 +53,7 @@ After the account exists, do what the user came for: ## Find an app for a need -`search_apps` matches names only, so a need like "web search" or "a database" will not match. Page through `list_apps` and match descriptions to the need. Offer the one to three best fits with a one-line description each, and any sign-up cap. Let the user choose, then [create an account](#create-an-account). +`search_apps` matches names only, so a need like "web search" or "a database" will not match. Call `list_apps` with the `category` that fits the need (such as `search`, `scraping`, `browser`, `data`, or `payments`; the tool schema lists every value), and match descriptions to the need. A filtered page can hold fewer apps than the limit while more remain: page until `nextPageToken` is absent, and reuse a `pageToken` only with the category it came from. Apps carry up to three `categories` and some carry none, so if the category comes up empty or close, page through `list_apps` without one before saying nothing fits. Offer the one to three best fits with a one-line description each, and any sign-up cap. Let the user choose, then [create an account](#create-an-account). ## Sign back in @@ -62,7 +67,7 @@ Signing in is the same call as creating an account: `connect_app` with the inbox ## Not on AgentID -If search and the full list both miss and the user has no app ID, say the service is not available through AgentID. Then offer: +If the slug, search, and the full list all miss and the user has no app ID, say the service is not available through AgentID. Then offer: - a catalog app that meets the same need, or - that the user signs up on the app's own site with the inbox address as the email. You can read the verification email for them with check-email. @@ -82,7 +87,8 @@ Do not fill in a third-party sign-up form on your own, and never solve a CAPTCHA - **403 `missing_permission`**: the credential lacks `app_connect`, or the organization is not verified yet. The user can enable `app_connect` on the API key in the AgentMail console; do not look for another key. - **404**: read which resource the error names before asking the user anything. - **Inbox**: the inbox is not in the organization, or not in the credential's scope. Check the inbox. - - **App** from `get_app`: no app is registered under that ID. Check the ID with the user; do not guess another. + - **App** from `get_app` with a slug: no catalog app has that slug. Fall back to `search_apps` with the name. + - **App** from `get_app` with an ID: no app is registered under that ID. Check the ID with the user; do not guess another. - **App** from `connect_app` for an app that `get_app` resolves: the app has no working sign-in entry point yet. Tell the user it cannot be connected right now. - With `acceptDisclosure: true`, the app may not support accepting the disclosure up front. Retry once without it. - To stop an inbox from signing in to an app, or to revoke a sign-in key, point the user to https://docs.agentmail.to/agentid-sign-in. The MCP server has no tool for either. diff --git a/skills/agentmail-mcp/SKILL.md b/skills/agentmail-mcp/SKILL.md index 263ba5f..ff290d5 100644 --- a/skills/agentmail-mcp/SKILL.md +++ b/skills/agentmail-mcp/SKILL.md @@ -86,7 +86,7 @@ MCP clients get the tool catalog and schemas live from the hosted runtime; do no The catalog covers more than mail. Point users at these groups when they ask what the connector can do: - **Inboxes, threads, messages, drafts, attachments, and allow/block lists** — the mail workflows in the sibling action skills. -- **AgentID apps and accounts** — `list_apps`, `search_apps`, `get_app`, `connect_app`, and `list_accounts` create accounts for an agent at third-party apps (for example "create an account at Firecrawl") and show where each inbox already has one. Use the `agentid` skill for that workflow. +- **AgentID apps and accounts** — `list_apps`, `search_apps`, `get_app`, `connect_app`, and `list_accounts` create accounts for an agent at third-party apps (for example "create an account at Firecrawl") and show where each inbox already has one. Catalog apps can be named by slug (`firecrawl`), and `list_apps` filters by category. Use the `agentid` skill for that workflow. - **Agent sign-up** — `agent_attach_human` and `agent_verify` lift an unverified agent organization's limits. ## Stdio Compatibility @@ -103,6 +103,7 @@ For a stdio-only client, use the supported npm or PyPI `agentmail-mcp` package. ## Troubleshoot - A 404 usually means the URL is missing `/mcp`. +- A tool or parameter in the published manifest is missing from the session (for example `list_apps` has no `category`): the hosted server does not announce catalog changes, so a session keeps the tool list it had at connect. Start a new session or reconnect the connector. - "Invalid API key" or a 401 with API-key auth usually means the key is wrong, revoked, lacks the necessary permissions, or `AGENTMAIL_API_KEY` was not available to the client process. - "Unauthorized" or a 401 with OAuth usually means the sign-in is incomplete or the session expired — drop any `apiKey` query param and let the client complete the browser-based OAuth flow instead. - Use the full `am_` key value and prefer the narrowest suitable organization, pod, or inbox scope.