migrate from mailgun inbound to lobstermail for ai agents

Mailgun is a good email API. Solid deliverability, clean REST interface, battle-tested for transactional sending. Most teams already have it wired up, so when it's time to give an AI agent its own inbox, reaching for Mailgun feels natural.

It doesn't hold up.

Not because Mailgun is bad at inbound — it handles inbound fine for the use case it was built for. The problem is that use case: a human configures a domain, sets up MX records, writes a webhook receiver, and leaves it running. That works great for a support inbox. It completely breaks down when your agent needs to provision its own address autonomously, on demand, without touching a dashboard or waiting for DNS propagation.

This guide covers exactly how to move your inbound email handling from Mailgun to LobsterMail, including what to keep, what to delete, and where the two tools can coexist.

What Mailgun inbound actually costs you#

Before your first email lands through Mailgun inbound, you need five things in place:

1. A domain with MX records pointing at Mailgun's servers (10-48 hours for DNS)
2. A route configured via API or dashboard — filter expression, action, priority
3. A server endpoint that Mailgun POSTs to on delivery
4. Code that parses Mailgun's multipart form data: stripped-text, body-html, headers, attachments as separate fields, signature for verification
5. Ongoing maintenance when routes break, tokens rotate, or Mailgun's webhook format changes

That's reasonable for a backend service. It's a significant obstacle for an agent that needs a working inbox in the next 30 seconds.

The structural issue is deeper than setup friction. Mailgun's model assumes one team, one domain, one set of routes that a human administrator manages. Agents don't fit that shape. If you're running multiple agents — one handling customer inquiries, one signing up for services, one catching verification codes during automated workflows — each needs its own routing configuration. Routes don't self-provision. Someone with billing access has to create them.

That someone can't be your agent.

The LobsterMail model#

LobsterMail reverses the provisioning direction. The agent creates its own inbox. No domain setup, no route configuration, no webhook endpoint to write.

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

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

console.log(inbox.address); // onboarding-agent@lobstermail.ai

const emails = await inbox.receive();
for (const email of emails) {
  console.log(email.subject, email.preview);
}

LobsterMail.create() handles account provisioning automatically — no API key management, no human signup flow. If no token is present, it creates a free account and stores the token at ~/.lobstermail/token. createSmartInbox() generates a readable address from the name you provide and handles collisions automatically. receive() returns structured JSON with security metadata already attached.

The agent runs this on first boot. That's it.

The migration steps#

1. Install the SDK#

npm install @lobsterkit/lobstermail

2. Replace inbox provisioning#

Wherever you currently configure a Mailgun route — through the dashboard, the API, or a Terraform file — replace it with a createSmartInbox() call. Store the returned address in your agent's state however you already store persistent config.

// Mailgun: route configured externally, address hardcoded
const agentAddress = 'agent-inbox@yourdomain.com'; // set up manually

// LobsterMail: agent provisions its own
const inbox = await lm.createSmartInbox({ name: 'my-agent' });
const agentAddress = inbox.address; // persist this

If you want a random address rather than a name-derived one, createInbox() gives you something like lobster-a4f8@lobstermail.ai. For most agent workflows, the readable format from createSmartInbox() is easier to debug.

3. Delete the webhook handler#

This is the cleanest part of the migration. Mailgun pushes to your server; LobsterMail lets your agent pull when it needs to. If you had a webhook receiver endpoint, you can remove it entirely.

// Before: webhook handler your server had to keep running
app.post('/mailgun-inbound', (req, res) => {
  verifyMailgunSignature(req.body);
  const { sender, subject, 'stripped-text': body } = req.body;
  // ...
});

// After: agent polls when it needs email
const emails = await inbox.receive();

If your workflow genuinely needs push delivery — you want to react to email the moment it arrives rather than polling — webhooks are available. But most agent patterns work better with pull: check for a verification code after signing up, check for a reply after sending a message. Poll when you need it, not on every POST from an external service.

4. Drop the Mailgun parsing code#

Mailgun sends multipart form data with separate fields for every part of the message. You end up writing (and maintaining) a parser. LobsterMail returns clean, structured JSON.

// No multipart parsing needed
for (const email of emails) {
  const { subject, from, text, html, receivedAt } = email;
  // structured, ready to use
}

Each email also includes injection risk scoring. If you're passing email content into an agent's context, that matters — email is an attack surface for prompt injection, and LobsterMail flags suspicious content automatically before your agent ever sees it.

5. Keep Mailgun for outbound if you want#

LobsterMail handles both inbound and outbound from your agent's address. But if your team already uses Mailgun for customer-facing transactional email — receipts, notifications, password resets — there's no reason to touch that setup. The two tools don't conflict.

Your agent uses LobsterMail for its own inbox. Your backend keeps using Mailgun for your main domain. Different use cases, clean separation. See agent email APIs compared for a fuller breakdown of when each tool makes sense.

One thing to watch#

If you're currently receiving email on your own domain through Mailgun (agent@yourcompany.com), you'll need to decide whether to keep that Mailgun route or move to a custom domain in LobsterMail. LobsterMail's free tier uses @lobstermail.ai addresses. For most agent workflows — catching verification codes, receiving structured messages from other agents — that works without issue.

Custom domains are available if your agent needs to receive mail at your own domain. Worth considering if your agent's inbox is customer-visible or if you need continuity with an existing address. For internal agent-to-agent communication and external signups, @lobstermail.ai is fine.

Also worth reading before you go live: the security and injection guide. Email coming into your agent's context from arbitrary senders is an injection surface. LobsterMail's risk scoring gives you a signal. Webhooks vs polling covers the delivery model tradeoffs in more depth if you're on the fence about which approach fits your architecture.

For agents that need a custom domain from the start, custom domains for agent email walks through that setup.

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