🚧 Early Preview — Looking for developer feedback! Email Agent Kit is an open-source library that plugs directly into your existing infrastructure (Supabase, Postgres, Clerk/Auth0, etc.) and gives your AI agents the ability to send, receive, and manage real email conversations.
Think of it as Auth.js for agent email — Gmail/Outlook OAuth, thread state, context snapshots, guardrails, scheduling, and follow-ups — without rebuilding the plumbing yourself.
If you're building an AI agent that needs to talk over email, you'll quickly hit the same problems:
- Gmail/Outlook OAuth flows and token refresh
- Thread state, reply parsing, deduplication
- Guardrails so your agent doesn't overcommit
- Scheduling and follow-ups (e.g. only send during business hours, retry later, nudge after a few days)
- Context handoff so the agent knows what's already been said
Email Agent Kit makes this boring and reliable. One install, one send(), one onReply().
npm install @email-agent/kitimport { createEmailAgent } from "@email-agent/kit";
const agent = await createEmailAgent({
db: supabase, // or pg pool
provider: "gmail",
});
// Agent sends an email
await agent.send({
accountId: "acc_123",
to: ["recipient@example.com"],
subject: "Demo request",
compose: async () => ({
text: "Hi, are you available to chat about the demo?",
html: "<p>Hi, are you available to chat about the demo?</p>",
}),
context: { objective: "schedule demo", step: "outreach" },
// Scheduling
schedule: "Mon-Fri 09:00-17:00", // TBD
});
// Handle a reply (via webhook)
agent.onReply(async ({ threadId, incoming, snapshot }) => {
console.log("Got reply:", incoming.bodyText);
// Your agent logic here...
});Express:
app.post("/api/webhooks/email", agent.webhookHandler());Next.js (App Router):
// app/api/webhooks/email/route.ts
export async function POST(request: Request) {
return agent.handleWebhook(request);
}The kit ships with migrations that extend your database. You own your data — no hosted service required.
- email_accounts – linked to your users/auth
- email_oauth_tokens – encrypted provider tokens
- email_threads – conversations
- email_messages – inbound & outbound messages
- agent_context_snapshots – objectives & state for your agent
- outbound_queue – scheduled jobs (send/retry/follow-up)
- deliverability_events – delivered / bounced / opened
sequenceDiagram
participant Agent as Your AI Agent
participant Kit as Email Agent Kit
participant DB as Your Database
participant Provider as Gmail/Outlook
Agent->>Kit: send({...})
Kit->>DB: store message + agent_context_snapshot
Kit->>Provider: deliver email (via OAuth token)
Provider-->>Kit: delivery status / errors
Kit->>DB: log deliverability event
Note over Agent,Kit: Outbound flow complete
Provider-->>Kit: inbound reply webhook/poll
Kit->>DB: look up thread + last snapshot
Kit-->>Agent: hand back reply + restored context
Agent->>Kit: decide next action (respond / schedule follow-up)
Note over Agent,Kit: Inbound flow continues seamlessly
- ✅ Gmail support
- ⏳ Outlook / IMAP adapters
- ⏳ Drop-in React components:
<EmailConnectButton />,<ThreadViewer /> - ⏳ Guardrails: prevent AI from making binding commitments
- ⏳ Advanced scheduling & follow-ups
- ⏳ Deliverability events: sent / bounced / opened
- ⏳ Human-in-the-loop approval mode
We're in early preview and would love your input on:
- Your use case: What are you building? What would make this perfect for your needs?
- Scheduling API: What's the most intuitive way to define time windows and follow-up rules?
- Queue infrastructure: Database-backed queue (zero deps) or integrate with existing queue systems (BullMQ, Temporal)?
- Provider support: Beyond Gmail/Outlook, what providers are critical for your use case?
- Guardrails: How useful would guardrails be, and what should they look like?
- Context management: How much conversation history should agents retain between sessions?
- Multi-agent coordination: Should multiple agents be able to collaborate on the same thread?
- Beyond email: Should we expand to other channels (Slack, SMS, WhatsApp)?
Join the discussion: GitHub Issues
MIT