how inbound email webhook processing works for AI agents

Your agent needs to respond to an email from a customer. The email arrived six seconds ago. If you're polling an IMAP inbox every 30 seconds, your agent might not even know about it yet. If you're polling every five minutes, the customer has already moved on.

Polling is the default for most email integrations, and it's fine for humans who check their inbox a few times an hour. For an AI agent that needs to act on incoming messages in real time, it's the wrong model entirely. Inbound email webhook processing flips the flow: instead of your agent asking "anything new?" over and over, the email infrastructure pushes a structured payload to your agent the instant a message lands.

This is how you build agents that actually react to email, not agents that periodically glance at it.

How inbound email webhook processing works#

The mechanics are simpler than most people expect. Here's what happens when someone sends an email to your agent's address:

1. The email arrives at your domain and the MX record routes it to your email infrastructure provider.
2. The provider receives the raw MIME message (headers, body, attachments, all of it).
3. The provider parses that raw message into a structured JSON payload with clean fields: sender, subject, body text, HTML, attachments as URLs.
4. The provider sends an HTTP POST request to the webhook URL you registered.
5. Your handler validates the request signature to confirm it's authentic.
6. Your agent's logic runs with full email context: who sent it, what they said, any files they attached.
7. Your handler returns a 200 response to acknowledge receipt.

That's it. No IMAP connections to manage, no credentials to rotate, no polling intervals to tune. The email shows up, your agent gets a structured notification, and it acts.

Why agents need webhooks instead of polling#

The practical difference between polling and webhooks goes beyond latency. With IMAP polling, your agent maintains a persistent connection (or reconnects constantly), tracks which messages it has already seen, handles connection timeouts, and parses raw MIME data itself. That's a lot of code for something that isn't your agent's actual job.

With webhooks, your agent exposes a single HTTP endpoint. The email arrives pre-parsed, pre-structured, and ready to process. Your agent doesn't need to know anything about email protocols. It receives JSON, does its work, and moves on.

For multi-agent systems, this matters even more. A triage agent can receive the webhook, classify the email, and fan it out to specialized sub-agents: one handles support requests, another processes invoices, a third logs everything for audit trails. Each agent gets exactly the data it needs without any of them touching an IMAP library.

Setting up an inbound email webhook#

The setup has three parts: getting an inbox, registering a webhook URL, and writing a handler.

With LobsterMail, the first two steps collapse into almost nothing. Your agent provisions its own inbox and registers a webhook in a few lines:

import { LobsterMail } from "lobstermail";

const lm = new LobsterMail();

// Agent creates its own inbox
const inbox = await lm.createInbox({ name: "support-agent" });

// Register a webhook for inbound emails
const webhook = await lm.createWebhook({
  url: "https://your-agent.example.com/hooks/email",
  events: ["email.received"],
});

No human had to sign up for anything. No DNS records to configure. The agent did it itself.

For the handler side, here's what a basic Next.js webhook endpoint looks like:

import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";

export async function POST(request: NextRequest) {
  const body = await request.text();
  const signature = request.headers.get("x-lobstermail-signature");

  // Verify the webhook signature
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
    .update(body)
    .digest("hex");

  if (signature !== expected) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }

  const payload = JSON.parse(body);
  const { from, subject, preview, threadId } = payload.data;

  // Your agent logic here
  console.log(`Email from ${from}: ${subject}`);

  return NextResponse.json({ received: true }, { status: 200 });
}

The signature verification step is not optional. Without it, anyone who discovers your webhook URL can send fake payloads and trick your agent into acting on fabricated emails. Always validate the HMAC signature against the secret you received when you created the webhook.

Keeping conversations coherent with thread context#

One thing most webhook guides skip: how does your agent maintain context across a multi-turn email conversation?

Every inbound email payload includes a threadId. When a customer replies to your agent's response, that reply carries the same thread ID as the original message. Your agent can use this to pull the full conversation history before composing its next reply.

// Fetch the full thread for context
const thread = await lm.getThread(payload.data.threadId);

// thread.messages contains every email in the conversation
const conversationHistory = thread.messages.map((msg) => ({
  role: msg.direction === "inbound" ? "user" : "assistant",
  content: msg.textBody,
}));

// Pass the history to your LLM for a context-aware response
const reply = await generateAgentResponse(conversationHistory);

Without thread tracking, your agent treats every inbound email as a brand-new conversation. That's how you get agents that ask "How can I help you?" to someone who's been going back and forth for three days.

Handling failures and retries#

Your webhook endpoint will go down. Deployments happen, servers restart, cloud providers hiccup. The question is whether you lose emails when it does.

Good email infrastructure retries failed webhook deliveries with exponential backoff. LobsterMail retries for up to 24 hours with increasing delays between attempts. If your endpoint returns a 5xx error or times out, the payload gets queued and retried automatically.

On your side, the key principle is idempotency. Your handler should produce the same result whether it processes a given email once or three times. The simplest approach: store the emailId from each payload and skip processing if you've seen it before.

const { emailId } = payload.data;

// Check if we already processed this email
if (await hasBeenProcessed(emailId)) {
  return NextResponse.json({ received: true }, { status: 200 });
}

// Process the email
await processEmail(payload.data);
await markAsProcessed(emailId);

Return a 200 status code quickly, even if your agent's actual processing takes a while. Accept the webhook, queue the work internally, and respond. If your handler takes 30 seconds to reply while your LLM generates a response, the webhook delivery system might assume it failed and retry, creating duplicate processing.

Security considerations for agent webhook endpoints#

Exposing a public HTTP endpoint for your agent creates a real attack surface. Beyond signature verification, here are the practical defenses:

Replay prevention. Include a timestamp check. If the webhook payload's timestamp is more than five minutes old, reject it. This prevents an attacker from capturing a valid signed payload and replaying it later.

IP allowlisting. If your infrastructure provider publishes their webhook source IPs, restrict your endpoint to only accept requests from those addresses. This is a simple network-level filter that blocks most noise.

Injection scanning. Inbound emails can contain prompt injection attempts, especially if your agent feeds email content directly into an LLM. LobsterMail scans every inbound email for injection patterns and includes a risk score in the webhook payload. If injectionRiskScore is above your threshold, quarantine the email instead of processing it blindly.

That last point is unique to agent email infrastructure. Traditional email services don't scan for prompt injection because they were built before LLMs existed. If your agent processes email content with AI, this isn't a theoretical risk. People will try it.

Testing webhooks locally#

You don't need to deploy to production to test your webhook handler. Tools like ngrok or cloudflared create a tunnel from a public URL to your local development server:

ngrok http 3000

Use the generated URL as your webhook endpoint during development. Send a test email to your agent's inbox and watch the payload arrive in your local terminal. Once everything works, swap the URL to your production endpoint.

When webhooks aren't enough#

Webhooks work well for real-time, event-driven processing. But some agent workflows need to batch-process emails, search across historical messages, or access emails that arrived before the webhook was registered. For those cases, you'll still want the API for fetching and searching. Webhooks handle the "something just happened" signal. The API handles "let me look at what happened before."

Most production agent deployments use both: webhooks for real-time triggers, API calls for context and history.

If you want your agent to have its own inbox with webhook support out of the box, set up LobsterMail in about 30 seconds. Your agent provisions the inbox and registers its webhook. No human signup required.