Agentmail

Copy codenpm install @agentmail/convex

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import agentmail from "@agentmail/convex/convex.config";

const app = defineApp();
app.use(agentmail);
export default app;

Copy codenpx convex env set AGENTMAIL_API_KEY your_api_key
npx convex env set AGENTMAIL_WEBHOOK_SECRET whsec_...
# Optional: EU residency
npx convex env set AGENTMAIL_BASE_URL https://api.agentmail.eu/v0

Copy code// convex/email.ts
import { query } from "./_generated/server";
import { components } from "./_generated/api";
import { v } from "convex/values";

export const listThread = query({
  args: { threadId: v.string() },
  handler: (ctx, { threadId }) =>
    ctx.runQuery(components.agentmail.lib.listInboundMessages, { threadId }),
});

export const listInbox = query({
  args: { inboxId: v.string() },
  handler: (ctx, { inboxId }) =>
    ctx.runQuery(components.agentmail.lib.listInboundMessages, { inboxId }),
});

Copy code// React
const messages = useQuery(api.email.listThread, { threadId });

Copy codeimport { AgentMail } from "@agentmail/convex";
const agentmail = new AgentMail(components.agentmail);

await agentmail.listThreads(ctx, inboxId, { labels: ["urgent"] });
await agentmail.getThread(ctx, inboxId, threadId);
await agentmail.getMessage(ctx, inboxId, messageId);

Copy codeimport { mutation } from "./_generated/server";
import { components } from "./_generated/api";
import { AgentMail } from "@agentmail/convex";
import { v } from "convex/values";

const agentmail = new AgentMail(components.agentmail);

export const sendHello = mutation({
  args: { inboxId: v.string(), to: v.string() },
  handler: async (ctx, args) => {
    return await agentmail.sendMessage(ctx, args.inboxId, {
      to: args.to,
      subject: "Hello from my Convex agent",
      text: "Hi! This was sent from a Convex mutation.",
      labels: ["support-agent", "auto-reply"],
    });
  },
});

Copy codeconst status = useQuery(api.email.sendStatus, { outboundId });
// → { status: "sent" | "delivered" | "bounced" | ..., agentmailMessageId, threadId, errorMessage }

Copy codeimport { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { components } from "./_generated/api";
import { AgentMail } from "@agentmail/convex";

const agentmail = new AgentMail(components.agentmail);
const http = httpRouter();

http.route({
  path: "/agentmail/webhook",
  method: "POST",
  handler: httpAction(async (ctx, req) => agentmail.handleWebhook(ctx, req)),
});

export default http;

Copy codeimport { internalMutation } from "./_generated/server";
import { components, internal } from "./_generated/api";
import { AgentMail } from "@agentmail/convex";
import { v } from "convex/values";

const agentmail = new AgentMail(components.agentmail, {
  onMessageReceived: internal.email.onMessageReceived,
});

export const onMessageReceived = internalMutation({
  args: { message: v.any(), thread: v.any(), eventId: v.string() },
  handler: async (ctx, args) => {
    // Your LLM agent runs here.
    await ctx.scheduler.runAfter(0, internal.email.autoReply, {
      inboxId: args.message.inbox_id,
      messageId: args.message.message_id,
      threadId: args.message.thread_id,
      text: args.message.text ?? "",
    });
  },
});