The Problem
- Giving AI agents access to a shared Gmail/Outlook inbox via IMAP creates race conditions between agents
- IMAP polling adds 30-60 second delays — too slow for real-time agent workflows
- OAuth tokens expire at the worst moments, breaking agent email triggers
- Agents can't distinguish which emails are "theirs" in a shared inbox
- Granting full mailbox access to an agent is a privacy and security risk
Why Existing Solutions Fall Short
Shared inbox IMAP access gives agents visibility into all email, not just their own
OAuth scope creep — you grant access to the entire mailbox just to trigger one workflow
IMAP polling wastes API calls and adds latency agents can't afford
Multiple agents reading the same inbox create race conditions and duplicate processing
Self-hosting email infrastructure (MX records, spam filtering, MIME parsing) takes weeks
You shouldn't have to build this yourself.
How Mailhooks Solves This
Dedicated Mailbox Per Agent
Each agent gets its own email address (e.g. [email protected]). Complete isolation — no shared inbox conflicts.
Instant Webhook Delivery
Email arrives, webhook fires within seconds. No polling, no delays. Your agent reacts in real time.
SSE Push for Firewalled Agents
Agents behind NAT or firewalls? Use Server-Sent Events — outbound-only connection, no exposed ports, no ngrok.
Pre-parsed JSON
Sender, subject, body, headers, attachments — all delivered as structured JSON. No MIME parsing required.
Thread Routing
Replies automatically thread to the originating agent. Full conversation context, zero manual routing.
Sender Filtering
Only forward emails from specific domains or addresses. Filter noise before the LLM ever sees it.
How It Works
Create agent mailbox
Set up a dedicated mailhook address for your agent (e.g. [email protected]).
Connect webhook or SSE
Point the mailhook at your agent's webhook endpoint, or use SSE for outbound-only connections.
Email arrives
An email hits the agent's address. Mailhooks parses and delivers structured JSON instantly.
Agent processes
Your agent receives the webhook, extracts the intent, and executes — no IMAP, no polling.
Reply or route
The agent responds, forwards to a human, or triggers downstream workflows. Thread context is preserved.
Code Example
Mailhooks delivers this JSON to your agent's webhook endpoint when an email arrives.
Webhook Payload
{
"id": "msg_agent_abc123",
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Issue with my subscription",
"text": "Hi, I was charged twice for this month...",
"html": "Hi, I was charged twice for this month...
",
"threadId": "thread_xyz789",
"attachments": [
{
"filename": "invoice.pdf",
"contentType": "application/pdf",
"size": 45678,
"url": "https://files.mailhooks.dev/..."
}
]
}Handler Code
// Agent webhook handler (Express)
app.post('/webhook/agent/email', async (req, res) => {
const { from, subject, text, threadId } = req.body;
// Pass to your agent with clear delimiting
// to prevent prompt injection
const response = await agent.process({
context: `Email from: ${from}
Subject: ${subject}
Body: ${text}`,
threadId,
});
// Agent can reply, escalate, or log
await handleAgentResponse(response, threadId);
res.sendStatus(200);
});
// Or use SSE for firewalled agents:
import { Mailhooks } from '@mailhooks/sdk';
const mailhooks = new Mailhooks({ apiKey: process.env.MAILHOOKS_API_KEY });
mailhooks.realtime.subscribe({
onEmailReceived: (email) => {
agent.process(email);
},
});Frequently Asked Questions
Every inbox can be configured with sender filtering rules. You can whitelist specific domains or email addresses, or use our webhook to implement your own spam filtering logic. Emails that don't match your rules are automatically rejected.
Webhooks are typically delivered within 100-500ms of email receipt. We process emails in real-time with no polling delays. For high-availability applications, we also offer webhook retries with exponential backoff.
Mailhooks is built specifically for inbound email. We offer simpler setup (no DNS changes required for testing), better attachment handling with direct download URLs, and a developer-first API for fetching emails programmatically—perfect for E2E testing.
Yes! You can connect your own domain with simple DNS configuration. We also provide free subdomains on inbox.mailhooks.dev for testing and development.
We automatically retry failed webhooks with exponential backoff for up to 24 hours. You can also use our API to fetch any missed emails. All emails are stored and accessible via the dashboard.
Get Started in 3 Steps
Takes ~2 minutes — no email infrastructure required.
Create a Mailhooks account
Sign up for free in seconds.
Create an inbox
Get a unique email address for your use case.
Add your webhook URL
Point to your endpoint and start receiving emails.