Skip to navigation
Integrations

Vercel AI SDK

Give your Vercel AI SDK agent its own email inbox

Getting started

The Vercel AI SDK is the most widely used TypeScript toolkit for building AI agents. The agentmail-toolkit package exposes the full AgentMail API as AI SDK tools, so an agent built with generateText, streamText, or ToolLoopAgent can create inboxes, send, receive, reply, search, and manage threaded email with no glue code.

To give your AI SDK agent an email inbox, install agentmail-toolkit, import AgentMailToolkit from agentmail-toolkit/ai-sdk, and pass new AgentMailToolkit().getTools() as the tools option. The agent can then call create_inbox to provision its own address and use the other tools to send and read mail from it.

Use cases

  • Give agents their own inboxes: Provision a dedicated email address per agent so it can send and receive mail independently.
  • Triage and reply: Read recent threads and reply inside the same thread, with threading handled automatically.
  • Stage and send: Compose drafts iteratively and send them when they’re ready.
  • Inbound-driven agents: Pair the toolkit with AgentMail webhooks so your agent reacts the moment mail arrives.

Prerequisites

  1. An AgentMail account with an API key from the AgentMail Console.
  2. Node.js 18+ and the AI SDK (ai v6 or later).

Setup

Install the toolkit alongside the AI SDK and Zod:

npm install agentmail-toolkit ai zod

Set your API key:

export AGENTMAIL_API_KEY=your-api-key

Quickstart

Pass the toolkit’s tools to generateText and let the agent loop through tool calls:

TypeScript
import { generateText, isStepCount } from 'ai'
import { AgentMailToolkit } from 'agentmail-toolkit/ai-sdk'
const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  tools: new AgentMailToolkit().getTools(),
  stopWhen: isStepCount(5),
  prompt:
    'Create an inbox for yourself, then check it for new messages and reply to anything urgent.',
})
console.log(text)

On ai v6, import stepCountIs instead of isStepCount; it was renamed in v7.

Plain model strings such as 'anthropic/claude-sonnet-4-5' are routed through the Vercel AI Gateway. To call a provider directly instead, pass a model from its AI SDK provider package, for example openai('gpt-4o') from @ai-sdk/openai.

The same tools work with streamText and ToolLoopAgent:

TypeScript
import { ToolLoopAgent } from 'ai'
import { AgentMailToolkit } from 'agentmail-toolkit/ai-sdk'
const agent = new ToolLoopAgent({
  model: 'anthropic/claude-sonnet-4-5',
  instructions: 'You are an email agent that manages its own AgentMail inbox.',
  tools: new AgentMailToolkit().getTools(),
})
const { text } = await agent.generate({
  prompt: 'Summarize the latest thread in my-agent@agentmail.to.',
})
console.log(text)

Configuring the toolkit

Authentication

new AgentMailToolkit() reads AGENTMAIL_API_KEY from the environment. For custom configuration, pass your own AgentMailClient from the agentmail SDK:

TypeScript
import { AgentMailClient } from 'agentmail'
import { AgentMailToolkit } from 'agentmail-toolkit/ai-sdk'
const toolkit = new AgentMailToolkit(new AgentMailClient({ apiKey: process.env.AGENTMAIL_API_KEY }))

Selecting tools

getTools() returns an object keyed by tool name, ready for the tools option of generateText, streamText, or ToolLoopAgent. Pass an array of names to get only that subset:

TypeScript
const tools = new AgentMailToolkit().getTools(['send_message', 'list_messages'])

Production agents should usually pass only the tools they need. A smaller tool set keeps the model focused and limits what it can do, for example leaving out delete_inbox and delete_thread.

Tool names are snake_case (send_message), but tool parameters are camelCase (inboxId, threadId). An inboxId is the inbox’s full email address, such as my-agent@agentmail.to.

Error handling

A failed tool call throws, which the AI SDK surfaces as a native tool-error part. The model can distinguish it from a successful result and decide whether to retry or change course.

Available tools

The toolkit exposes more than 40 tools covering the AgentMail API. The main ones are below.

Inboxes

ToolDescription
create_inboxCreate an inbox, optionally choosing the username, domain, display name, and metadata
list_inboxesList the organization’s inboxes, newest first, paginated
search_inboxesFind inboxes by address or display name
get_inboxGet one inbox by its inboxId
update_inboxUpdate an inbox’s display name or metadata
delete_inboxPermanently delete an inbox and all of its threads, messages, and drafts

Messages

ToolDescription
send_messageSend an email from an inbox right away
reply_to_messageReply to a message in its thread, optionally to all original recipients
forward_messageForward a message, with its attachments, to new recipients
get_messageGet one message by ID with its full body
list_messagesList messages in an inbox, newest first, with previews and labels
search_messagesFull-text search over messages in an inbox, ranked by relevance
update_messageAdd or remove labels on one message, for example to mark it read

Threads

ToolDescription
list_threadsList threads in an inbox, most recently received first
search_threadsFull-text search over threads in an inbox, ranked by relevance
get_threadGet a thread by ID, including its messages
update_threadAdd or remove labels on every message in a thread
delete_threadPermanently delete a thread and all of its messages

Drafts

ToolDescription
create_draftCreate a draft, or schedule it for automatic sending with sendAt
update_draftUpdate a draft or reschedule its send time
send_draftSend a draft right away
list_draftsList drafts in an inbox, most recently updated first
get_draftGet a draft by ID, including its content and scheduled send time
delete_draftPermanently delete a draft, canceling its send if scheduled

Attachments

ToolDescription
get_attachmentGet an attachment’s metadata and download URL, plus extracted text for PDF and DOCX files

Additional tools cover files, allow and block lists, and the rest of the API. Call getTools() and inspect the returned keys for the full list.

Resources