AgenticEmail agent starter

A minimal, deployable starter that gives an AI agent its own email inbox. One click:

1. Creates a real, addressable inbox at runtime.
2. Sends a welcome email from that inbox.
3. Lists the messages the inbox holds.

Everything runs server-side against the AgenticEmail REST API using your AGENTICEMAIL_API_KEY. Built with Next.js (App Router, TypeScript), zero runtime dependencies beyond the framework, and ready to deploy to Vercel, Cloudflare Workers, or Railway.

Deploy

After deploying, set the AGENTICEMAIL_API_KEY environment variable to a key from app.agenticemail.dev/keys.

Quickstart (local)

git clone https://github.com/AgenticEmail/agent-starter
cd agent-starter
npm install
cp .env.example .env.local   # then paste your API key into AGENTICEMAIL_API_KEY
npm run dev

Open http://localhost:3000 and click the button.

You need an AgenticEmail API key and at least one verified sending domain on your account. Grab a key at app.agenticemail.dev/keys; the starter uses your default verified domain, so a fresh inbox can send right away.

How it works

The button posts to a single API route, app/api/run/route.ts, which runs three calls in order:

const client = agenticEmail(process.env.AGENTICEMAIL_API_KEY!);

const inbox = await client.createInbox({ display_name: "Agent Starter" });
const address = `${inbox.username}@${inbox.domain}`;

await client.sendMessage(inbox.id, {
  to: [address],
  subject: "Your agent inbox is live",
  text: "Sent by the AgenticEmail agent starter.",
});

const messages = await client.listMessages(inbox.id);

Those helpers live in lib/agenticemail.ts: a tiny typed wrapper over fetch and the AgenticEmail REST endpoints (POST /v1/inboxes, POST /v1/inboxes/{id}/messages/send, GET /v1/inboxes/{id}/messages). No dependencies, so it runs unchanged on Node and on the Cloudflare Workers runtime.

The API key is read from the server environment and never reaches the browser.

Prefer the official SDK?

There is also an official TypeScript SDK:

npm install agenticemail

import { AgenticEmail } from "agenticemail";

const client = new AgenticEmail({ apiKey: process.env.AGENTICEMAIL_API_KEY! });
const inbox = await client.inboxes.create({ display_name: "Agent Starter" });
await client.messages.send(inbox.id, {
  to: [`${inbox.username}@${inbox.domain}`],
  subject: "Your agent inbox is live",
  text: "Sent by the AgenticEmail agent starter.",
});

This starter uses fetch directly so the example stays dependency-free and portable, but either approach works.

Cloudflare Workers

The repo is preconfigured for Cloudflare via @opennextjs/cloudflare (wrangler.jsonc, open-next.config.ts). To build and deploy from the CLI:

npm run deploy

Set the secret first with npx wrangler secret put AGENTICEMAIL_API_KEY.

Learn more

• agenticemail.dev
• Docs

License

MIT. See LICENSE.