How to Set Up a Catch-All Email Webhook

Overview

A catch-all email address (also called a wildcard address) receives email sent to any address at a domain that does not match a more specific mailbox. For example, if someone sends to [email protected] or [email protected], a catch-all address receives that message instead of bouncing it.

Catch-all webhooks are useful for:

• Capturing emails from customers who mistype your address — you can identify and follow up
• Building systems where any email to your domain is meaningful — e.g., per-customer addresses like [email protected]
• Auditing all inbound email traffic to your domain for analysis or compliance
• Single-address routing for prototyping — use one catch-all during development before splitting into specific addresses

With JsonHook and a custom domain, you can configure MX records to point your entire domain at JsonHook's mail servers. Every email to any address at your domain is received, parsed, and delivered to your webhook as JSON.

Prerequisites

Setting up a domain-level catch-all requires:

• A JsonHook Starter or Pro plan (custom domain feature)
• A domain you own with access to its DNS settings (Cloudflare, Route53, Porkbun, etc.)
• Ability to add MX records to your domain's DNS configuration
• A webhook endpoint to receive all inbound email for the domain

Note: Configuring your domain to use JsonHook's MX records means all inbound email for the domain goes through JsonHook. If you also use the domain for regular email (G Suite, Outlook), set up a forwarding rule instead of changing MX records.

Step-by-Step Instructions

Configure a catch-all inbound email webhook:

1. Create a catch-all JsonHook address via the dashboard or API, selecting "catch-all" mode and providing your domain.
2. Configure DNS MX records as instructed by JsonHook. Typically:

   Priority  Hostname
   10        mx1.in.jsonhook.com
   20        mx2.in.jsonhook.com

   These replace (or supplement) any existing MX records for your domain.
3. Wait for DNS propagation — typically 5–30 minutes for Cloudflare, up to 48 hours for other providers.
4. Test with a real email. Send an email to any address at your configured domain ([email protected]) and verify it appears in your delivery log.
5. In your webhook handler, use email.to[0] to determine which specific address the email was sent to — this lets you build recipient-based routing even within a single catch-all handler.

Code Example

A catch-all handler that routes based on the specific recipient address within your domain:

app.post("/webhooks/catchall", (req, res) => {
  // ... verify HMAC signature ...
  const { email, deliveryId } = JSON.parse(req.body.toString());

  const recipient = email.to[0]?.toLowerCase() ?? "";

  // Extract username from catch-all address
  const [username, domain] = recipient.split("@");

  // Route based on well-known usernames
  if (username === "support") {
    return createSupportTicket(email).then(() => res.sendStatus(200));
  }

  if (username === "orders") {
    return processOrder(email).then(() => res.sendStatus(200));
  }

  // Dynamic per-customer routing: customer-{id}@yourdomain.com
  const customerMatch = username.match(/^customer-(d+)$/);
  if (customerMatch) {
    const customerId = parseInt(customerMatch[1], 10);
    return routeToCustomer(customerId, email).then(() => res.sendStatus(200));
  }

  // Unknown address — log for analysis
  console.log(`Catch-all: unknown recipient ${recipient} — from: ${email.from}`);
  res.sendStatus(200);
});

Common Pitfalls

Catch-all webhook issues to avoid:

• Spam volume. A catch-all address attracts spam — spammers send to random addresses hoping for a valid mailbox. Implement spam scoring in your handler (check authentication headers, sender reputation) and consider rate-limiting processing of emails from unknown senders.
• Accidentally catching emails meant for other mailboxes. If your domain also has real mailboxes (Google Workspace, Microsoft 365), changing MX records will divert those emails to JsonHook. Use email forwarding from your existing provider to JsonHook addresses instead of changing MX records if coexistence is needed.
• Not handling the webhook volume increase. A catch-all can receive significantly more email than a specific address. Make sure your webhook endpoint scales appropriately or use a queuing layer to smooth out spikes.
• Forgetting to normalize the recipient address. Email addresses are case-insensitive. Always normalize email.to[0] to lowercase before routing decisions.
• No fallback for unrecognized addresses. Always have a catch-all branch in your routing logic that logs the email for manual review rather than silently dropping it.