Skip to main content
The Python client uses ETag-based conditional requests to avoid re-downloading unchanged files.

​
How It Works

  1. On first download, the client saves the file and its ETag to ~/.cache/jmail/
  2. On subsequent requests, the client sends a conditional HEAD request with If-None-Match: <etag>
  3. If the server responds with 304 Not Modified, the cached file is used (no download)
  4. If the ETag has changed, the file is re-downloaded

​
Cache Location

~/.cache/jmail/
  emails.parquet
  emails.etag
  emails-slim.parquet
  emails-slim.etag
  documents.parquet
  documents.etag
  ...

​
Disabling Cache

​
Python

client = JmailClient(cache=False)

​
CLI

uv run jmail.py emails --no-cache --head 5

​
Clearing Cache

rm -rf ~/.cache/jmail/

​
Manifest

The /v1/manifest.json endpoint provides dataset metadata and checksums, allowing programmatic freshness checks: 
curl https://data.jmail.world/v1/manifest.json | python -m json.tool

client = JmailClient()
manifest = client.manifest()
print(manifest)