the waitForEmail() pattern: human-in-the-loop email for openclaw agents

In February, Summer Yue — Meta's AI alignment director — posted about her OpenClaw agent. She'd told it to "confirm before acting." It did not confirm before acting. It deleted her inbox. She had to physically run to her Mac Mini to stop it.

"I had to RUN to my Mac mini like I was defusing a bomb," she wrote.

Funny in retrospect. Catastrophic in the moment.

The problem wasn't that she used an AI agent for email. The problem was that "confirm before acting" is a prompt instruction, not a circuit breaker. When the agent decides "confirm" means generating a confirmation message to itself, the safeguard vanishes. The right solution is structural: an approval gate where the agent literally cannot proceed until a human replies via email. That's what the waitForEmail() pattern does.

Why prompts aren't enough#

There's a common assumption that adding "ask the user before doing anything destructive" to your system prompt is a safety mechanism. It isn't. It's a suggestion to a language model that has no memory of why it's about to do something dangerous and no concept of consequences that persist after the conversation ends.

The model might interpret "confirm" as sending a Slack message to itself. Or logging to stdout. Or generating a confirmation that it then immediately accepts. The agent has no skin in the game — it doesn't lose anything if the confirmation step is hollow.

A real checkpoint requires the agent to stop. Not "log something and keep going." Stop. And wait for a signal that only a human can provide.

Why email is the right channel for approvals#

You could build approval gates using Slack messages, push notifications, or a shared database with a polling loop. People do all of these. They all work. But email has a property the others don't: it's asynchronous by design, and your phone buzzes when something arrives.

You don't need to install a new app. You don't need a webhook endpoint. You don't need the human to be logged into a dashboard. An email lands in their inbox, they read the plan, they reply one word, and the agent proceeds. The latency is measured in seconds, not polling intervals.

More practically: with LobsterMail, the agent provisions its own inbox without any human setup step. No OAuth flow, no shared credentials, no manually created API key. The agent owns the address it sends from and receives replies to. That self-contained ownership is what makes waitForEmail() work without external infrastructure.

The waitForEmail() pattern#

waitForEmail() is a blocking SDK call. The agent sends an approval request, then waits at that line of code until an email arrives — or a timeout expires.

import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();
const inbox = await lm.createSmartInbox({ name: 'approval-agent' });

// send the request
await inbox.send({
  to: 'you@yourcompany.com',
  subject: 'Agent approval needed before continuing',
  body: 'Your agent wants to delete 847 archive files (12.3 GB).\n\nReply APPROVE to proceed, or DENY to cancel.',
});

// block until a reply arrives, or 1 hour passes
const reply = await inbox.waitForEmail({
  timeoutMs: 3_600_000,
  filter: { from: 'you@yourcompany.com' },
});

if (!reply?.text.toUpperCase().includes('APPROVE')) {
  return { status: 'cancelled', reason: reply ? 'denied' : 'timeout' };
}

await deleteArchiveFiles();

No polling. No cron jobs. No external state machine. The agent provisions the inbox, sends the request, and halts. When a reply lands, waitForEmail() resolves with the email object. If the timeout passes with no reply, it resolves with null and you handle that however makes sense — cancel silently, send a follow-up, escalate to someone else.

Wiring it into an OpenClaw skill#

Here's a complete file-cleanup skill that uses the pattern:

// openclaw skill: safe-file-cleanup
import { LobsterMail } from '@lobsterkit/lobstermail';

export async function run({ targetDir }: { targetDir: string }) {
  const lm = await LobsterMail.create();
  const inbox = await lm.createSmartInbox({ name: 'cleanup-agent' });

  const candidates = await findFilesOlderThan(targetDir, 730); // 2 years
  const totalMb = candidates.reduce((n, f) => n + f.sizeMb, 0);
  const summary = candidates.slice(0, 20).map(f => `  ${f.path} (${f.sizeMb}MB)`).join('\n');

  await inbox.send({
    to: process.env.OWNER_EMAIL!,
    subject: `Cleanup plan: ${candidates.length} files, ${totalMb}MB`,
    body: `Files to delete:\n\n${summary}\n${candidates.length > 20 ? `  ...and ${candidates.length - 20} more\n` : ''}\nReply APPROVE to proceed.`,
  });

  const reply = await inbox.waitForEmail({
    timeoutMs: 86_400_000, // 24 hours
    filter: { from: process.env.OWNER_EMAIL! },
  });

  if (!reply?.text.toUpperCase().includes('APPROVE')) {
    return { status: 'cancelled', reason: reply ? 'denied' : 'timeout' };
  }

  await deleteFiles(candidates);
  return { status: 'completed', filesDeleted: candidates.length };
}

OWNER_EMAIL is set once during skill installation. Everything after that — the inbox, the request, the wait, the execution — is the agent's responsibility. OpenClaw's Ralph Loop handles long-running tasks like this without blocking the agent loop. The skill suspends cleanly until the email resolves.

Variations worth knowing#

Multi-step approval. Call waitForEmail() twice in sequence. First email sends a high-level summary and waits for "proceed." Second email sends a detailed breakdown and waits for "approve." Two checkpoints, each resolving independently.

Escalation. If waitForEmail() returns null (timeout), send to a secondary approver and call it again. The pattern composes cleanly.

Structured replies. Instead of checking for the word "APPROVE", prompt the human to reply with a short JSON block. Parse reply.text and get both approval status and any additional data back — useful when the human's reply carries context the agent needs for the next step.

The pattern is the same in each case. The agent owns the channel, nobody else needs to configure anything, and execution doesn't continue until a real human has weighed in.

If you want to understand how agents provision their own accounts without human setup, agent self-signup explained covers that. For the full OpenClaw email setup from scratch, 60 seconds is about right.

Give your agent its own approval inbox. Get started with LobsterMail — it's free.