SDK Bug: messages.list/threads.list fails with inboxId parameter

[ttomiczek]

Environment:

agentmail SDK v0.4.0
Node.js v22.22.0
Steps to reproduce:

const { AgentMailClient } = require('agentmail');
const client = new AgentMailClient({ apiKey: 'YOUR_KEY' });

// This fails
client.inboxes.messages.list({ inboxId: 'your-inbox@agentmail.to' })
// OR
client.inboxes.threads.list({ inboxId: 'your-inbox@agentmail.to' })
Expected: Return messages/threads for the specified inbox

Actual:

Error: JsonError: Expected string. Received object.
Workaround: Use org-level client.threads.list() (no inboxId) - works but returns all threads

Additional notes:

client.inboxes.list() works fine
client.inboxes.get({ inboxId: '...' }) works fine
The error occurs in the SDK's request serialization, likely passing the wrong type for the inboxId parameter

--

Prepared by my AI - sadky Silas has no github yet.

[unitypeaceproject]

I hit this same JsonError: Expected string. Received object. today while fixing an unrelated bug in the Attachments section of SKILL.md (PR coming). Digging into it, I think the root cause is in the docs, not the SDK — and it's wider than messages.list / threads.list.

The SDK is consistent; the docs are not

Every method on client.inboxes.* in the generated TypeScript SDK takes positional path params first, then an optional object for the body/query/options. Signatures from node_modules/agentmail/dist/esm/api/resources/inboxes/resources/messages/client/Client.d.mts (v0.4.18):

list(inbox_id, request?, requestOptions?)
get(inbox_id, message_id, requestOptions?)
getAttachment(inbox_id, message_id, attachment_id, requestOptions?)
update(inbox_id, message_id, request, requestOptions?)
delete(inbox_id, message_id, requestOptions?)
send(inbox_id, request, requestOptions?)
reply(inbox_id, message_id, request, requestOptions?)

This is the Fern convention — it's consistent across the whole SDK. Passing a single object ({ inboxId, ... }) throws JsonError: Expected string. Received object. because the first positional arg (the inbox id) arrives as an object where a string is expected.

Verification against a live inbox

inboxes.get(inbox_id)                                 → OK
inboxes.messages.list(inbox_id, {limit:2})            → OK: returned 2 messages
inboxes.messages.list({inboxId, limit})               → FAIL (expected): Expected string. Received object.
inboxes.messages.get(inbox_id, message_id)            → OK
inboxes.threads.list(inbox_id, {limit:2})             → OK: returned 2 threads
inboxes.list({limit:2})  // root list, no path param  → OK: returned 2 inboxes

5 OK + 1 expected-FAIL confirming the convention.

What this means for SKILL.md

Essentially every TypeScript example in agentmail/SKILL.md uses the object-style calling convention and will throw on first invocation. For example lines 47, 51, 73–80, 83–88, 90–91, 93–95, 99–104, 143–147, 150–153, 188–192, 222–227, 230–233 — the TS snippets for inboxes.get, inboxes.delete, messages.send, messages.reply, messages.list, messages.get, messages.update, threads.list, threads.get, getAttachment, drafts.create, drafts.send — all of them.

The Python section is fine — Python uses kwargs, which match the generated signatures (inbox_id=..., message_id=...). That's presumably why nobody's hit this until now: anyone picking up the skill and writing Python succeeds on the first try, while anyone writing Node hits an immediate JsonError.

Workaround for users today

Switch to positional path params and (where applicable) move the body/query into an object as the last arg:

// Broken
client.inboxes.messages.list({ inboxId: 'x@agentmail.to' })
// Works
client.inboxes.messages.list('x@agentmail.to')
client.inboxes.messages.list('x@agentmail.to', { limit: 20 })

Scope of the incoming PR

I'm sending a separate PR that fixes only the Attachments section (the specific bug I was tracking down). I'm deliberately not rewriting the entire TypeScript half of SKILL.md in that PR so it stays reviewable — leaving that to this issue for maintainer direction on preferred approach (full in-place rewrite vs docs-generated-from-SDK-types vs deprecate the TS snippets).

Happy to send a follow-up PR rewriting the rest of the TS examples if that's the direction the maintainers want.