Read your mail from the command line
The reader, reader/mailbox.py, lists, shows, downloads, and exports the emails in your bucket. This page shows how to do each of those, and how to read the bucket with other S3 tools instead. It assumes you’ve set up your inbox and python3 reader/mailbox.py check succeeds.
Run every command from the repo folder. For every flag and output field, see the reader reference.
List recent emails
list prints one line per email that arrived in the last 24 hours:
python3 reader/mailbox.py list
Each line shows the time the email arrived, the sender, the subject, and the email’s key in square brackets. You pass the key to show and get.
To look further back, or at a shorter window, pass --hours. It accepts decimals:
python3 reader/mailbox.py list --hours 168 # the last 7 days
python3 reader/mailbox.py list --hours 0.5 # the last 30 minutes
list downloads each email to read its sender and subject, so a long window over a busy inbox takes a while. For a large number of emails, export gives you the same emails in one file.
Read one email
show prints an email’s headers, its text, and its links:
python3 reader/mailbox.py show mail/2026-11-17/your_email_key_here.eml
The output starts with From, To, Date, Subject, and DMARC, followed by the text of the email. If the email only has an HTML version, the reader pulls the text out of the HTML. The links come last, each with the text it was attached to.
show never opens a link. Before you open one yourself, check that the email came from the sender you expect; the DMARC line helps with that. See Check whether an email is genuine.
Download the original email
get downloads the email exactly as it arrived, as an .eml file:
python3 reader/mailbox.py get \
mail/2026-11-17/your_email_key_here.eml -o email.eml
You can open email.eml in most email apps, or parse it with any email library. Use get when you need an attachment, because show and export only list attachment file names. Without -o, get writes the email to standard output, so you can pipe it into another command.
Export emails as JSON
export writes every email from a time window to one JSON file, already parsed:
python3 reader/mailbox.py export --hours 24 -o mail.json
The file has a messages list with one entry per email. Each entry has the sender, subject, date, DMARC result, links, attachment names, and text. The command prints how many emails it wrote. Without -o, export prints the JSON to standard output.
Each email’s text is cut at 20,000 characters, and a cut entry gets "text_truncated": true. To keep the full text, pass --max-text 0. To cut it shorter, pass a smaller number:
python3 reader/mailbox.py export --hours 24 --max-text 4000 -o mail.json
For the full list of fields, see Export format. To run export on a schedule and pass the file to your own code, see Send your mail to a script or AI agent.
Check whether an email is genuine
Anyone can put any address in an email’s From line, so check the DMARC result before you trust an email. Cloudflare records it when the email arrives, and show prints it on the DMARC line:
pass: the email came from the domain in itsFromaddressfail: the email claims to be from a domain that didn’t send itnone: the sender’s domain doesn’t publish a DMARC policy, so there was nothing to checkunknown: Cloudflare’s check result wasn’t in the email
The Worker reads this only from the header that Cloudflare adds, so a sender can’t fake a pass by adding their own copy of the header. To reject everything that doesn’t pass, see Require a DMARC pass.
Use a config file other than the default
The reader looks for its settings in ~/.config/r2-mailbox/config.json by default. You can point it at another file, or use environment variables instead.
To use another file, pass --config before the command:
python3 reader/mailbox.py --config ./work-inbox.json list
To use environment variables, set all four of these:
export R2_ACCOUNT_ID=your_account_id_here
export R2_BUCKET=r2-mailbox
export R2_ACCESS_KEY_ID=your_access_key_id_here
export R2_SECRET_ACCESS_KEY=your_secret_access_key_here
python3 reader/mailbox.py check
The reader uses environment variables whenever R2_ACCESS_KEY_ID is set and you didn’t pass --config. In that case it ignores the config file completely, so set R2_BUCKET too. For the full order, see Where the reader looks for settings.
Read the bucket with another S3 tool
R2 works with tools built for Amazon S3, so you can skip the reader and use any of them with the same read-only key. Point the tool at your account’s R2 endpoint and use auto as the region.
With the AWS command-line tool, for example, put the key in a profile first:
aws configure --profile r2-mailbox
Enter the Access Key ID and Secret Access Key when it asks, and auto for the region. Then list and download emails:
ENDPOINT=https://your_account_id_here.r2.cloudflarestorage.com
aws s3 ls s3://r2-mailbox/mail/ --recursive \
--profile r2-mailbox --endpoint-url "$ENDPOINT"
aws s3 cp s3://r2-mailbox/mail/2026-11-17/your_email_key_here.eml . \
--profile r2-mailbox --endpoint-url "$ENDPOINT"
To see the metadata the Worker attached to an email, such as the sender’s envelope address, use head-object:
aws s3api head-object --bucket r2-mailbox \
--key mail/2026-11-17/your_email_key_here.eml \
--profile r2-mailbox --endpoint-url "$ENDPOINT"
The metadata shows up under Metadata in the output. For the key layout and every metadata field, see the Worker reference.