@pidgeon-ai/ai-sdk weekly downloads statistics

@pidgeon-ai/ai-sdk

Pidgeon as Vercel AI SDK tools: a real inbox your agent can create addresses in, send from, read, and wait on. Pidgeon is the email inbox API for AI agents. It gives agents their own inboxes so they can work with emails just like a human.

npm install @pidgeon-ai/ai-sdk ai zod

Sending, and waiting for the answer

import { generateText, isStepCount } from 'ai';
import { pidgeonTools } from '@pidgeon-ai/ai-sdk';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-5.5',
  tools: pidgeonTools({
    apiKey: process.env.PIDGEON_API_KEY,
    identityId: process.env.PIDGEON_ADDRESS_ID,
  }),
  stopWhen: isStepCount(10),
  prompt:
    'Email ops@yourdomain.com from agent@yourdomain.com and ask for the staging access code. ' +
    'Wait for the reply and tell me the code.',
});

The model calls send_message, then await_message, which holds one request open until mail arrives and returns it with extracted.codes and extracted.links already pulled out. There is no polling loop to write.

identityId is the address a tool uses when the model names none. Without it, the model has to pass identity_id itself, and list_addresses is how it finds one.

Options

Option	Default	What it is
apiKey	PIDGEON_API_KEY	A Pidgeon API key. Required one way or the other.
baseUrl	https://pidgeon.ai/api/v1	Where the API is.
identityId	none	The address a tool uses when the model names none
client	built from the above	A client from createClient in @pidgeon-ai/sdk

Tools

The same tools as @pidgeon-ai/mcp, with the same names and the same descriptions, because the descriptions are read from that server's list rather than copied. Each one calls one operation in @pidgeon-ai/sdk.

<!-- tools:start -->

Tool	What it does
list_addresses	The addresses this credential can reach.
create_address	Create an address for an agent to use.
get_address	One address, by id.
list_threads	Conversations in one address, newest first.
get_thread	One conversation, by id.
list_messages	The messages of one conversation, oldest first — the text to read before replying.
search_messages	Full-text search across every address this credential can reach, ranked by relevance.
send_message	Send from an address this credential may send as.
get_message	One message, by id, with its body, the headers we keep, and what the sending domain’s records proved — authentication.spf, .dkim, .dmarc, where null means not reported rather than failed.
await_message	Waits until a message arrives at an address — after you submit a sign-up form, say — and returns it with extracted.codes and extracted.links: verification codes and confirm links, most likely first.
reply_to_message	The recipients, the subject and the thread are read off the message being answered, so you bring the words and nothing else.
forward_message	Sends one message on to somebody it was not addressed to, with its attachments, from the address that received it.
create_draft	Writes a message without…