how to migrate openclaw from gmail pub/sub to lobstermail webhooks

If you built OpenClaw email handling on Gmail Pub/Sub, you've been in at least one of these places: a half-configured Google Cloud project at 11pm, a gog gmail watch serve process that silently lapsed over the weekend, or an OAuth token refresh that broke something in production. The setup works when everything goes right. The problem is all the ways it can quietly go wrong without telling you.

This guide walks through replacing that whole chain with LobsterMail webhooks. The agent hatches its own inbox, you register one endpoint, and Google is completely out of the picture.

If you want the conceptual case for dropping Gmail entirely, this post covers it. This one is for people who have the Gmail setup running today and want concrete steps to switch.

What you're currently maintaining#

The standard OpenClaw Gmail setup is a chain of five dependencies:

1. A Gmail account (created by a human)
2. A Google Cloud project with Pub/Sub API enabled
3. A push subscription pointing at a public HTTPS endpoint
4. openclaw webhooks gmail run (or the underlying gog gmail watch serve) keeping the watch alive
5. OAuth tokens that expire and need renewal

When all five are working, your agent gets near-real-time email notifications. When any one breaks, you're diagnosing a chain. Was it the token? Did the watch lapse? Is the subscription still pointed at the right URL? Google's error messages won't tell you which link failed.

The structural issue is that this stack was designed for humans. You created the Gmail account. You enabled the API. You granted OAuth consent. Your agent is borrowing human infrastructure and calling it autonomous.

What the LobsterMail version looks like#

The agent provisions its own inbox. No Cloud Console, no OAuth flow, no human step.

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

const lm = await LobsterMail.create();

// Agent creates its own inbox — no human account required
const inbox = await lm.createInbox();
console.log(inbox.address); // agent_abc@lobstermail.ai

Then register a webhook:

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

That's the entire provisioning step. LobsterMail pushes to your endpoint when email arrives. No watch renewal cycle, no token refresh logic, no Google dependency.

The migration#

Step 1: Install the SDK

npm install lobstermail

Step 2: Provision an inbox

Run this once, or let your agent call it at startup:

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

const lm = await LobsterMail.create();
const inbox = await lm.createInbox();

// Persist inbox.id and inbox.address somewhere durable
// inbox.address is what external services will send to
console.log(inbox.address);

Step 3: Register your webhook

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

// Add to your env vars — won't be shown again
// LOBSTERMAIL_WEBHOOK_SECRET=webhook.secret

Step 4: Update your email handler

The LobsterMail webhook payload is simpler than the Gmail Pub/Sub format:

{
  "event": "email.received",
  "timestamp": "2026-03-02T09:00:00Z",
  "data": {
    "emailId": "em_abc123",
    "inboxId": "in_xyz789",
    "from": "sender@example.com",
    "subject": "Your verification code",
    "preview": "First 200 characters of the email body..."
  }
}

Always verify the signature before processing:

import { createHmac } from 'node:crypto';

function verifySignature(body: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return expected === signature;
}

// In your HTTP handler (Express, Hono, Fastify — whatever you're using)
app.post('/hooks/email', async (req, res) => {
  const signature = req.headers['x-lobstermail-signature'] as string;

  if (!verifySignature(req.rawBody, signature, process.env.LOBSTERMAIL_WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = req.body;

  if (event === 'email.received') {
    await handleEmail(data);
  }

  res.status(200).send('ok');
});

Step 5: Test it

Send a test email to your inbox.address. You should get a webhook delivery within a few seconds. Confirm your handler processes it correctly before moving on.

Step 6: Decommission the Gmail setup

Once LobsterMail is confirmed working:

• Stop gog gmail watch serve or openclaw webhooks gmail run
• Delete the Pub/Sub subscription and topic in Google Cloud Console
• Revoke the OAuth token from your Google account settings
• Archive or delete the Gmail account if it was created solely for the agent

What changes#

The inbox address changes. You'll have an @lobstermail.ai address instead of a Gmail one. Update any external services that send to the old address — your agent logic downstream stays the same.

One thing to watch: the webhook payload includes a 200-character preview, not the full body. If your existing handler relied on --include-body from the Pub/Sub setup, fetch the full email using the emailId:

if (event === 'email.received') {
  // Get the full body when you need it
  const email = await lm.getEmail(data.emailId);
  await handleEmail(email);
}

Everything else — how your agent processes, responds to, or routes email — stays exactly as it was.

Retry behavior#

LobsterMail retries failed webhook deliveries with exponential backoff, up to 10 attempts. If your endpoint is briefly unavailable, emails aren't lost. After 10 consecutive failures the webhook is auto-disabled. You can re-enable it:

// List webhooks to check status
const webhooks = await lm.listWebhooks();

// Re-enable via API if needed
await fetch('https://api.lobstermail.ai/v1/webhooks/wh_abc123', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${process.env.LOBSTERMAIL_API_KEY}` },
  body: JSON.stringify({ enabled: true }),
});

Compare that to a lapsed Gmail watch, which fails silently — your agent just stops receiving email and you find out when something downstream breaks.

What I didn't expect#

The mechanical migration is straightforward. What's less obvious until you've done it is how much the mental model simplifies. There's no watch renewal cron to monitor. No question of whether the OAuth token is still valid. No Google Cloud Console tab to keep bookmarked. The agent has an inbox. Email arrives. The webhook fires. That's the whole model.

If the Gmail setup is running smoothly and you're not actively touching it, there's no emergency. But if you're debugging a broken watch, starting a new project, or tired of the maintenance surface area, this is a reasonable morning to make the switch. The free tier covers 1,000 emails per month with no credit card required.

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