Guides / Change the code
Guides

Change and deploy the code

r2-mailbox is two small programs: the Worker in worker/src/index.ts, and the reader in reader/mailbox.py. This page shows how to check, deploy, and debug changes to either one.

Install the tools

npm install installs the pinned versions of Wrangler, TypeScript, and the Cloudflare type definitions that the npm scripts use:

npm install

The reader needs no install step. It uses only the Python standard library and runs on Python 3.9 or newer.

Check and deploy the Worker

The npm scripts cover the Worker’s whole loop, from type-checking to watching it run:

npm run typecheck    # type-check the Worker against Cloudflare's types
npm run deploy       # deploy the Worker
npm run tail         # watch the Worker's logs live

There’s no local way to send an email to the Worker, so test a change by deploying it and sending a real email. Keep npm run tail open in a second terminal while you send it, to see the Worker run and any error it throws.

If you change the Worker’s settings or bindings, edit worker/wrangler.jsonc and deploy again. Keep workers_dev and preview_urls set to false, and don’t add a fetch handler or routes. Those keep the Worker unreachable from the internet; see Why nobody can call the Worker from the internet.

Run the reader against your bucket

The reader runs straight from the repo, so a change takes effect the next time you run it. Use check to confirm it can still reach R2, then show or export on a real email to test parsing:

python3 -I reader/mailbox.py check
python3 -I reader/mailbox.py show mail/2026-11-17/your_email_key_here.eml

The -I flag runs Python in isolated mode, so it ignores environment variables like PYTHONPATH and doesn’t load modules from the current folder. npm run check uses it too.

To test the parser without touching R2, download an email once with get -o email.eml, then run the reader’s parse function on the file. Save this as parse_test.py in the repo folder:

import importlib.util
import json
from pathlib import Path

spec = importlib.util.spec_from_file_location(
    "r2_reader", "reader/mailbox.py"
)
reader = importlib.util.module_from_spec(spec)
spec.loader.exec_module(reader)

parsed = reader.parse(Path("email.eml").read_bytes())
print(json.dumps(parsed, indent=2, ensure_ascii=False))

python3 -I parse_test.py prints the email with the same fields as an export entry. key is empty and received and dmarc are null, because those come from R2, not the file. The script loads the reader by file path under the name r2_reader, because import mailbox would load the Python standard library module with the same name.

Find your way around the repo

Each file has one job:

File What it does
worker/src/index.ts The Email Worker: checks each email and saves it to R2
worker/wrangler.jsonc Worker config: the bucket binding and settings
reader/mailbox.py The command-line reader, using the Python standard library only
scripts/setup.sh Creates the bucket and lifecycle rule, deploys, and can add the routing rule
config.example.json A template for the reader’s config file
package.json Pinned Wrangler and TypeScript versions, plus the npm scripts
tsconfig.json TypeScript settings for the Worker
SECURITY.md How to report a security problem
docs/ These docs, as Markdown that GitHub and the docs site both render
docs/images/ Diagram PNGs for GitHub, rendered from the docs site’s diagram specs
site/ The docs site, built with Astro. See site/README.md.

Change a diagram

The diagrams in these docs are specs in site/src/lib/diagrams/specs.mjs. The docs site draws them live, and GitHub shows PNGs rendered from the same specs. After you change a spec, render the PNGs again from the site/ folder:

npm install
npm run diagrams

The script writes a light and a dark PNG for each diagram to docs/images/. Commit them with the spec change, so GitHub and the site show the same diagram.

Report a security problem

If a change you’re testing shows a way around the Worker’s checks, or a way to make the reader leak credentials, report it privately instead of opening a public issue. SECURITY.md explains how, and lists what counts.