Expiring Emails with Cloudflare Email Routing

expiring-email-routing is a Cloudflare Email Worker that redirects or drops emails based on an expiration date embedded in the recipient address.

The email worker parses the recipient email address for a date in YYYY-MM-DD format and only forwards the email if the date has not passed:

mailbox+2029-01-01@example.dev → mailbox@example.dev

catchall.2029-01-01@example.dev → steve.jobs@icloud.com

expired.2024-12-31@example.dev → 🗑️

Prerequisites

1. Enable Cloudflare Email Routing:
   Dashboard → Account → Domain → Email Routing

   Use a new or unused domain name with Email Routing. Cloudflare offers registrations priced at cost.

2. Add verified destination addresses:
   Domain → Email Routing → Destination addresses

   At least one destination address is required. Email workers can only route to email address that have been approved as destination addresses. This restriction also applies to routing between email address with the same domain.

Deploy to Cloudflare

1. Cloudflare Dashboard:
   Dashboard … Workers → Create an application → Clone a repository:

   http://github.com/andesco/expiring-email-routing
   

   

2. Wrangler CLI:

   git clone https://github.com/andesco/expiring-email-routing
   cd expiring-email-routing
   # edit wrangler.toml
   wrangler deploy

Setup

Use Catach-All Address: .YYYY-MM-DD

If your catch-all address is enabled, you can effectively use expiring-email-routing with all your custom addresses:

1. Enable catch-all address:
   Domain → Email Routing → Routing Rules
   Active

2. Send catch-all address to Worker:
   Domain → Email Routing → Routing Rules → Edit catch-all address
   Edit
   Action: Send to a Worker
   Destination: expiring-email-routing
   Save

3. Use the catach-all address:

   catchall.{YYYY-MM-DD}@example.dev → FORWARD_TO

   custom-address.{YYYY-MM-DD}@example.dev → custom-address@example.dev

Use Custom Addresses: +YYYY-MM-DD

If your catch-all address is disabled, you can selectively use expiring-email-routing with a custom addresses:

1. Enable subaddressing:
   Domain → Email Routing → Settings

2. Send custom addresses to Worker:
   Domain → Email Routing → Routing Rules
   Create address or Edit
   Action: Send to a Worker
   Destination: expiring-email-routing
   Save

3. Use your custom addresses with subaddressing:

   mailbox+{date}@example.dev → FORWARD_TO

   mailbox+{CUSTOM_TAG}@example.dev → CUSTOM_TAG

   mailbox+{date}+{CUSTOM_TAG}@example.dev → CUSTOM_TAG

Note

Subaddressing is also known as sub-addressing, plus addressing, and tagged addressing.

Important

Email workers can only route to email address that have been approved as destination addresses. This restriction also applies to routing between email address with the same domain.

Environment Variables

REQUIRE_DATE

• optional boolean
• drop emails with no date in address: true
• route emails with or without a date in address: false · default

UTC_OFFSET

• optional
• If the email address contains a date in the past, the worker drops the email.
• Set your preferred timezone to determine the end of your day relative to UTC. Examples:
  -7 Pacific Time
  -4 Eastern Time · default
  0 UTC
  +8 Singapore
  -96 4 day buffer

{CUSTOM_TAG}

• optional email address
• If subaddresses is enabled and a {CUSTOM_TAG} is included in the address, the email worker routes to {CUSTOM_TAG} first.

FORWARD_TO

• optional email address
• If FORWARD_TO is set, the email worker routes to FORWARD_TO:
• If FORWARD_TO is not set, the worker strips the date and attempts to route to a custom address:
  custom-address.YYYY-MM-DD@example.com → custom-address@example.com

Development

Build Commands

npm run deploy # wrangler deploy --config wrangler.local.toml
npm run dev    # wrangler dev    --config wrangler.local.toml