how to handle ai agent inbound email webhook processing

Your agent gets an email. A customer replied, a form submitted, or an OTP just landed. What happens next depends entirely on how you've wired up your inbound email webhook processing. Get it right and your agent reacts in seconds. Get it wrong and emails pile up unread, duplicates trigger double actions, or worse, a spoofed payload tricks your agent into doing something you didn't authorize.

Most guides on AI agent inbound email webhook processing cover the happy path: receive POST, parse JSON, do thing. That's table stakes. The real work is in verification, idempotency, async execution, and failure recovery. This is the stuff that separates a demo from a production system.

How to process inbound email webhooks for AI agents#

AI agent inbound email webhook processing is the pattern where your email provider sends an HTTP POST to your agent's endpoint every time a new message arrives, replacing the need for polling. Here's the full sequence:

1. Provision an API inbox so your agent has its own email address.
2. Register a webhook URL pointing to your agent's HTTP endpoint.
3. Receive the POST payload when an inbound email arrives.
4. Return a 200 OK response immediately, before doing any processing.
5. Verify the webhook signature using HMAC to confirm authenticity.
6. Parse the payload fields (sender, subject, body, thread ID, attachments).
7. Run your agent logic asynchronously and send a reply via API.

Each of these steps has failure modes worth understanding. Let's walk through the ones that trip people up.

Return 200 first, process second#

This is the single most common mistake in webhook handler design. Your agent receives the POST, starts parsing the email, builds a prompt, calls an LLM, generates a reply, sends it, and then returns 200. The whole round trip takes 8 seconds. Your email provider waited 5 seconds, got no response, and queued a retry.

Now your agent processes the same email twice. If it's a payment confirmation, your agent might credit the account twice. If it's a support request, the customer gets two identical replies.

The fix is simple in concept: acknowledge the webhook instantly and process everything in a background job.

app.post('/webhook/email', async (req, res) => {
  // Acknowledge immediately
  res.status(200).send('ok');

  // Process asynchronously
  setImmediate(async () => {
    const verified = verifySignature(req);
    if (!verified) return;

    const { emailId, from, subject, preview, threadId } = req.body.data;
    await agentProcessEmail({ emailId, from, subject, preview, threadId });
  });
});

On serverless platforms like AWS Lambda or Cloudflare Workers, you can't easily run logic after returning a response. In those environments, push the payload to a queue (SQS, Kafka, or even a simple Redis list) and have a separate worker consume it.

Verify webhook signatures#

Every webhook payload should be signed by your email provider. If you skip verification, anyone who discovers your endpoint URL can send fake payloads. Imagine a spoofed email.received event with a from field set to your CEO's address and a body that says "approve the wire transfer." Your agent would process it as a legitimate instruction.

LobsterMail signs every webhook with an HMAC-SHA256 signature using the secret returned at creation time. Verification looks like this:

import crypto from 'crypto';

function verifySignature(req: Request, secret: string): boolean {
  const signature = req.headers['x-lobstermail-signature'];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(req.body))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Use timingSafeEqual instead of === to prevent timing attacks. Store the webhook secret in environment variables, not in code.

Handle idempotency#

Webhook providers retry on failure. Sometimes they retry even on success (network hiccup, ambiguous timeout). Your handler needs to be safe to call multiple times with the same payload.

The simplest approach: store every processed emailId in a set (Redis, a database table, even an in-memory Map for prototypes) and skip duplicates at the top of your handler.

async function agentProcessEmail(data: EmailPayload) {
  const already = await redis.sismember('processed_emails', data.emailId);
  if (already) return;

  await redis.sadd('processed_emails', data.emailId);

  // Your actual agent logic here
  const response = await generateAgentReply(data);
  await sendReply(data.threadId, response);
}

Set a TTL on your dedup keys (72 hours is usually plenty) so the set doesn't grow forever.

Route emails to the right agent logic#

Not every inbound email should trigger the same behavior. A password reset OTP needs extraction and submission. A customer question needs a thoughtful reply. A newsletter should be ignored entirely.

Route based on recipient address, subject patterns, or sender domain:

function routeEmail(data: EmailPayload) {
  const { to, subject, from } = data;

  if (to.includes('support@')) return handleSupportRequest(data);
  if (subject.match(/OTP|verification|code/i)) return extractOTP(data);
  if (from.endsWith('.noreply.com')) return archive(data);

  return handleGeneral(data);
}

With LobsterMail, each agent can have its own dedicated inbox and webhook URL, which means routing happens at the infrastructure level rather than inside your handler code. One inbox for support, another for notifications, a third for outbound campaign replies. Each points to a different endpoint.

Threading and conversation context#

When your agent replies to an email, the reply needs to land in the same thread. This isn't just a UX nicety. If your agent starts a new thread for every response, the human on the other end sees disconnected messages with no context, and their replies back won't correlate to your agent's conversation state.

LobsterMail's webhook payload includes a threadId field. Store it alongside your conversation history and use it when sending replies:

const reply = await lm.sendEmail({
  inboxId: 'ibx_xyz789',
  threadId: data.threadId,
  to: [data.from],
  subject: `Re: ${data.subject}`,
  body: agentResponse,
});

This keeps the entire conversation threaded on both sides.

Testing webhooks locally#

You can't receive webhooks on localhost. During development, use a tunneling tool to expose your local server:

npx cloudflared tunnel --url http://localhost:3000

This gives you a public HTTPS URL you can register as your webhook endpoint. Send a test email to your agent's inbox and watch the payload hit your local handler. Once you've confirmed the flow works, swap the URL for your production endpoint.

For CI environments, save a few real webhook payloads as JSON fixtures and replay them against your handler in tests. This catches parsing regressions without needing a live email provider in the loop.

What about polling?#

IMAP polling still works. It's simpler to set up and doesn't require a public endpoint. But it comes with real tradeoffs: you're either polling too often (wasting resources, hitting rate limits) or too infrequently (your agent takes minutes to respond instead of seconds). For agents that need to react to inbound email in near-real-time, webhooks are the right choice.

If your agent checks email once an hour to summarize a daily digest, polling is fine. If it's handling support tickets, processing inbound leads, or extracting OTPs for multi-step workflows, you want webhooks.

Where to go from here#

If your agent doesn't have its own inbox yet, that's the first step. Get your agent its own email address here, paste the instructions to your agent, and it handles provisioning and webhook registration itself. From there, wire up your handler with the patterns above: instant 200, signature verification, idempotency, and async processing. That's the whole stack.