Send & Receive Emails with eve

eve is Vercel’s filesystem-first agent framework, where an agent is a directory of files. AgentMail plugs in as a single connection file in that directory. By the end of this page, your eve agent will create its own inbox, email you, and answer your reply in the same thread.

0. Get an API key and an eve project

Generate an API key from the AgentMail Console and set it as an environment variable:

export AGENTMAIL_API_KEY="<API_KEY>"

eve needs Node.js 24 or newer and a model credential. The scaffolded agent routes model calls through the Vercel AI Gateway, so set AI_GATEWAY_API_KEY or link a Vercel project.

Scaffold a project if you do not have one:

npx eve@latest init my-agent
cd my-agent

To add eve to an app that already has a package.json, run npx eve@latest init . from its root instead.

1. Connect AgentMail to your agent

Create one file at agent/connections/agentmail.ts. The filename becomes the connection’s name, so this file registers it as agentmail.

import { defineMcpClientConnection } from "eve/connections";

export default defineMcpClientConnection({
  url: "https://mcp.agentmail.to/mcp",
  description:
    "AgentMail, the agent's own email service. Create inboxes, send email, read incoming messages, and reply in the same thread.",
  headers: { "x-api-key": process.env.AGENTMAIL_API_KEY! },
});

eve connects to AgentMail’s hosted MCP server and discovers its tools. The model finds them through eve’s built-in connection_search tool and calls them by qualified name, such as agentmail__send_message. Write the description for the model, not for yourself: it is the main signal connection_search uses to pick this connection for email work.

The URL and the key stay out of the model’s context. eve itself sends the x-api-key header on every request, so keep the key in the environment rather than in the URL. The hosted server’s full catalog and the other ways to connect to it are on MCP and Skills.

2. Test sending emails

Start the development server:

npm run dev

This opens an interactive session with your agent in the terminal. Ask it to email you, with your real address in place of you@example.com:

Create an inbox for yourself, then send an email from it to you@example.com introducing yourself.

The email reaches that account moments later, from an @agentmail.to address that did not exist until you asked. The agent does the work with agentmail__create_inbox and agentmail__send_message.

A prompt like this one, without a username, always works: AgentMail generates an address. You can also name the inbox in your prompt, but usernames are first come, first served.

3. Test reading and replying

Reply to the agent’s email from your own mail client. Then ask the agent, in the same session:

Check your inbox and reply to the newest message.

You should find the answer in your mail client, in the same thread as the first email. The agent reads mail with tools like agentmail__list_threads and agentmail__get_thread, and answers with agentmail__reply_to_message, which replies to one specific received message so the answer stays in its thread.

The agent checks mail when you ask it to. To act the moment an email arrives, deliver inbound events to an endpoint you control with webhooks.

4. Gate email actions behind approval

The connection hands the model tools that send email on your behalf. Before this agent runs anywhere real, add an approval policy to the connection:

import { defineMcpClientConnection } from "eve/connections";
import { once } from "eve/tools/approval";

export default defineMcpClientConnection({
  url: "https://mcp.agentmail.to/mcp",
  description:
    "AgentMail, the agent's own email service. Create inboxes, send email, read incoming messages, and reply in the same thread.",
  headers: { "x-api-key": process.env.AGENTMAIL_API_KEY! },
  approval: once(),
});

The helpers come from eve/tools/approval:

• once() asks the first time each tool runs in a session, then allows it for the rest of the session.
• always() asks before every call.

A gated call pauses the session on an approval prompt. Approve and the run resumes from that exact step. Deny and eve skips the tool and tells the model why.

An approval policy covers every tool the connection serves. To shrink what the model can discover in the first place, set tools: { allow: [...] } on the connection with the tool names you allow, or write your own typed tools in agent/tools/ with the AgentMail SDKs.

Next Steps