The Problem
- You need real-time email notifications but can't expose a webhook endpoint
- Browser apps and local dev environments can't receive incoming HTTP requests
- Client-side apps (browser, mobile) have no way to receive webhooks
- Firewalls block inbound traffic but allow outbound connections
- Local development requires tunneling tools like ngrok to test webhooks
Why Existing Solutions Fall Short
Webhooks require exposing a public endpoint that accepts inbound requests
Polling the email API is slow, inefficient, and wastes resources
Setting up ngrok or tunnels for local development is tedious
Worker processes need complex queue infrastructure to coordinate
You shouldn't have to build this yourself.
How Mailhooks Solves This
Outbound Only
SSE uses outbound connections. No need to expose endpoints or configure firewalls.
Instant Delivery
Notifications arrive within milliseconds of email receipt. No polling delays.
Worker Distribution
Distributed mode load-balances notifications across workers automatically.
Works Everywhere
Browsers, long-running workers, local dev — anywhere that can maintain connections.
How It Works
Install SDK
Add the Mailhooks SDK to your project.
Subscribe to events
Call realtime.subscribe() with your handlers.
Receive notification
Your handler fires instantly when emails arrive.
Process email
Use the email metadata or fetch full content via API.
Auto-reconnect
SDK handles reconnection automatically on network issues.
Code Example
Subscribe to real-time push notifications with just a few lines of code.
Webhook Payload
{
"type": "email.received",
"timestamp": "2025-01-15T10:30:00.000Z",
"data": {
"id": "email_abc123",
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "New order #12345",
"domain": "yourapp.mailhooks.dev",
"hasAttachments": true,
"attachmentCount": 1,
"createdAt": "2025-01-15T10:30:00.000Z"
}
}Handler Code
import { Mailhooks } from '@mailhooks/sdk';
const mailhooks = new Mailhooks({ apiKey: 'mh_xxx' });
// Subscribe to push notifications
const subscription = mailhooks.realtime.subscribe({
// Choose mode: 'broadcast' (all clients) or 'distributed' (load balance)
mode: 'broadcast',
onConnected: (payload) => {
console.log('Connected!', payload.connectionId);
},
onEmailReceived: async (email) => {
console.log(`New email from ${email.from}: ${email.subject}`);
// Fetch full email content if needed
const content = await mailhooks.emails.getContent(email.id);
processEmail(content);
},
onError: (error) => {
console.error('Connection error:', error);
},
autoReconnect: true, // Auto-reconnect on disconnect
});
// Later, disconnect when done
subscription.disconnect();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.