carlyemail-toolkit

CarlyEmail's email tools for the Vercel AI SDK, LangChain, and any other agent framework. A real inbox your agent can send, receive and reply from, without writing the tools yourself.

npm install carlyemail-toolkit
export CARLYEMAIL_API_KEY=ce_us_...

import { openai } from "@ai-sdk/openai";
import { ToolLoopAgent } from "ai";
import { CarlyEmailToolkit } from "carlyemail-toolkit/ai-sdk";

const agent = new ToolLoopAgent({
  model: openai("gpt-5-mini"),
  instructions: "Read the thread before replying. Draft when unsure.",
  tools: new CarlyEmailToolkit().getTools(),
});

import { createAgent } from "langchain";
import { CarlyEmailToolkit } from "carlyemail-toolkit/langchain";

const agent = createAgent({ model: "openai:gpt-5-mini", tools: new CarlyEmailToolkit().getTools() });

import { CarlyEmailToolkit } from "carlyemail-toolkit"; // no framework

for (const tool of new CarlyEmailToolkit().getTools()) {
  tool.name, tool.description, tool.inputSchema, tool.annotations.readOnlyHint;
  await tool.func({ thread_id: "..." }); // runs it
}

Plain ES modules with no build step; types ship with it. ai and @langchain/core are optional peers — install the one you use.

What is in it

The 25 tools the hosted MCP server serves — inboxes, threads, messages, drafts, attachments, labels, and account verification — with the same names, descriptions and parameter schemas, called over the REST API. Pass names to take only some:

const tools = new CarlyEmailToolkit().getTools(["list_messages", "get_thread", "reply_to_message"]);

A name that is not a tool throws rather than being dropped.

Which inbox

Every tool takes inbox_id, and most work without it. A key scoped to one inbox means that inbox. An organization with one inbox means that one. With several, the tools that read threads and drafts look across all of them, and every other tool refuses and names the inboxes so the agent can ask which — the same behaviour as the hosted server.

Errors

A failed call throws one bounded line carrying the API's message and the fix it suggests. The AI SDK reports that as a tool-error part; LangChain's tool node hands it back to the model as an error message.

See https://docs.carlyemail.com/integrations/toolkit.