EmailCatchAll

Configure a catch-all email routing rule that handles emails not matched by other routing rules. This rule is processed last and typically matches all unhandled emails.

Minimal Example

Forward all unmatched emails to an admin address:

import { EmailCatchAll } from "alchemy/cloudflare";

await EmailCatchAll("default-catchall", {
  zone: "example.com",
  enabled: true,
  actions: [
    {
      type: "forward",
      value: ["admin@company.com"],
    },
  ],
});

Drop Unmatched Emails

Configure catch-all to drop any emails that don’t match specific rules:

import { EmailCatchAll } from "alchemy/cloudflare";

await EmailCatchAll("drop-catchall", {
  zone: "example.com",
  enabled: true,
  actions: [
    {
      type: "drop",
    },
  ],
});

Process with Worker

Use a Worker to handle all unmatched emails for custom processing:

import { EmailCatchAll } from "alchemy/cloudflare";

await EmailCatchAll("worker-catchall", {
  zone: "example.com",
  enabled: true,
  name: "Worker processing",
  actions: [
    {
      type: "worker",
      value: ["email-processor"],
    },
  ],
});

Forward to Multiple Addresses

Send unmatched emails to multiple destinations:

import { EmailCatchAll } from "alchemy/cloudflare";

await EmailCatchAll("multi-forward-catchall", {
  zone: "example.com",
  enabled: true,
  name: "Multi-destination catch-all",
  actions: [
    {
      type: "forward",
      value: ["admin@company.com", "backup@company.com"],
    },
  ],
});

Multiple Actions

Perform multiple actions on unmatched emails:

import { EmailCatchAll } from "alchemy/cloudflare";

await EmailCatchAll("multi-action-catchall", {
  zone: "example.com",
  enabled: true,
  name: "Forward and log all emails",
  actions: [
    {
      type: "forward",
      value: ["admin@company.com"],
    },
    {
      type: "worker",
      value: ["email-logger"],
    },
  ],
});

Custom Matchers

Use custom matchers instead of the default “all” matcher:

import { EmailCatchAll } from "alchemy/cloudflare";

await EmailCatchAll("custom-catchall", {
  zone: "example.com",
  enabled: true,
  name: "Custom catch-all",
  matchers: [
    {
      type: "literal",
      field: "to",
      value: "*@example.com",
    },
  ],
  actions: [
    {
      type: "forward",
      value: ["admin@company.com"],
    },
  ],
});

Disable Catch-All

Disable the catch-all rule when not needed:

import { EmailCatchAll } from "alchemy/cloudflare";

await EmailCatchAll("disabled-catchall", {
  zone: "example.com",
  enabled: false,
  actions: [
    {
      type: "drop",
    },
  ],
});

Use with Zone Resource

Reference an existing Zone resource:

import { EmailCatchAll, Zone } from "alchemy/cloudflare";

const zone = await Zone("my-zone", {
  name: "example.com",
});

await EmailCatchAll("zone-ref-catchall", {
  zone: zone,
  enabled: true,
  actions: [
    {
      type: "forward",
      value: ["admin@company.com"],
    },
  ],
});

Properties

Input Properties

zone (string | Zone): Zone ID or Zone resource where the catch-all rule will be configured
enabled (boolean, optional): Whether the catch-all rule is enabled. Defaults to true
name (string, optional): Name for the catch-all rule. Defaults to “Catch All”
matchers (EmailMatcher[], optional): Matchers for the catch-all rule. Defaults to [{ type: "all" }]
actions (EmailAction[]): Actions to take for emails that don’t match other rules

Output Properties

zoneId (string): Zone ID where the catch-all rule is configured
enabled (boolean): Whether the catch-all rule is enabled
name (string): Rule name
matchers (EmailMatcher[]): Matchers for the catch-all rule
actions (EmailAction[]): Actions for the catch-all rule
tag (string): Rule tag

How Catch-All Works

The catch-all rule works differently from regular email rules:

Last Priority: Catch-all rules are evaluated after all other routing rules
Unmatched Emails: Only emails that don’t match any other rules reach the catch-all
Single Rule: There can only be one catch-all rule per zone
Special Endpoint: Uses a dedicated API endpoint (/catch_all) instead of regular rules

Common Use Cases

Admin Notification

Forward unmatched emails to administrators:

await EmailCatchAll("admin-notification", {
  zone: "example.com",
  enabled: true,
  name: "Admin notifications",
  actions: [
    {
      type: "forward",
      value: ["admin@company.com"],
    },
  ],
});

Spam Prevention

Drop unmatched emails to prevent spam:

await EmailCatchAll("spam-prevention", {
  zone: "example.com",
  enabled: true,
  name: "Drop unmatched emails",
  actions: [
    {
      type: "drop",
    },
  ],
});

Custom Processing

Process unmatched emails with custom logic:

await EmailCatchAll("custom-processing", {
  zone: "example.com",
  enabled: true,
  name: "Custom email processing",
  actions: [
    {
      type: "worker",
      value: ["unmatched-email-handler"],
    },
  ],
});

Best Practices

Strategy Selection

Forward First: Start by forwarding unmatched emails to see what you’re getting
Analyze Patterns: Look for common patterns in unmatched emails
Refine Rules: Create specific rules for common patterns, then update catch-all

Security Considerations

Monitor Volume: Watch for sudden increases in unmatched emails
Verify Destinations: Ensure catch-all destinations can handle the volume
Review Regularly: Periodically review what emails are being caught

Performance Optimization

Use Drop Wisely: Drop obvious spam/unwanted emails to reduce processing
Worker Efficiency: Keep Worker processing lightweight for high volumes
Multiple Destinations: Distribute load across multiple forwarding addresses

Action Types

Forward Action

Forward unmatched emails to destination addresses:

{
  type: "forward",
  value: ["admin@company.com", "backup@company.com"]
}

Worker Action

Process unmatched emails with a Cloudflare Worker:

{
  type: "worker",
  value: ["unmatched-email-processor"]
}

Drop Action

Drop/reject unmatched emails:

{
  type: "drop";
  // No value needed
}

Limitations

Only one catch-all rule per zone
Catch-all rules are evaluated last (after all other rules)
All limitations of regular email routing apply (destination verification, etc.)

Troubleshooting

Catch-All Not Working

Check if Enabled: Verify the catch-all rule is enabled
Other Rules Matching: Check if other rules are catching emails first
Verify Destinations: Ensure forwarding addresses are verified

Too Many Emails

Create Specific Rules: Add rules for common patterns to reduce catch-all volume
Use Drop Action: Drop unwanted emails before they reach catch-all
Monitor Patterns: Analyze unmatched emails to improve rule coverage

Processing Errors

Worker Logs: Check Worker script logs for processing errors
Timeout Issues: Ensure Worker processing is fast enough for email volume
Memory Limits: Monitor Worker memory usage for high-volume processing