> ## Documentation Index
> Fetch the complete documentation index at: https://jmail.world/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Python-Client

> Einzeldatei-Python-Client mit ETag-Caching

![Jmail](https://mintcdn.com/jmail/F-FAi3RZzojcIyie/images/jmail-app.png?fit=max\&auto=format\&n=F-FAi3RZzojcIyie\&q=85\&s=3d45d0246f3c69c7024d9a467fcfad28)

Der Jmail Python-Client ist eine einzelne Datei, die keine Installation erfordert. Er verwendet [PEP 723](https://peps.python.org/pep-0723/)-Inline-Abhängigkeiten, sodass [`uv run`](https://docs.astral.sh/uv/) alles automatisch übernimmt.

## Einrichtung

Keine Installation erforderlich. Einfach mit `uv` ausführen:

```bash theme={null}
uv run clients/python/jmail.py emails --head 5
```

Oder als Bibliothek in deinen eigenen Skripten nutzen:

```python theme={null}
from jmail import JmailClient

client = JmailClient()
df = client.emails()
```

## Verwendung der Bibliothek

### Grundlegende Nutzung

```python theme={null}
from jmail import JmailClient

client = JmailClient()

# Alle E-Mails mit vollständigem Nachrichtentext
df = client.emails()

# Nur Netzwerk (kein Nachrichtentext, wesentlich kleinerer Download)
df = client.emails(slim=True)

# Dokumente mit vollständig extrahiertem Text (lädt Datenfragmente herunter)
docs = client.documents(include_text=True)

# Fotos, Personen und Gesichtserkennungsdaten
photos = client.photos()
people = client.people()
faces = client.photo_faces()

# iMessage-Konversationen und -Nachrichten
convos = client.imessage_conversations()
messages = client.imessage_messages()

# Crowd-sourced Sterneanzahl
stars = client.star_counts()

# Release-Batch-Metadaten
batches = client.release_batches()
```

### Roh-URLs abrufen

Zur Verwendung mit DuckDB, Polars oder anderen Tools:

```python theme={null}
url = client.url("emails-slim")
# → "https://data.jmail.world/v1/emails-slim.parquet"

url = client.url("emails-slim", fmt="ndjson.gz")
# → "https://data.jmail.world/v1/emails-slim.ndjson.gz"
```

### Cache deaktivieren

```python theme={null}
# Immer neu herunterladen (kein lokaler Cache)
client = JmailClient(cache=False)
```

## Referenz zur Kommandozeilenoberfläche

```
Usage: uv run jmail.py <command> [options]

Commands:
  manifest          Print manifest JSON
  emails            Download emails (--slim for network-only, --head N)
  documents         Download documents (--include-text for full text, --head N)
  photos            Download photos metadata (--head N)
  people            Download people (--head N)
  photo_faces       Download photo face data (--head N)
  imessage_conversations  Download iMessage conversations (--head N)
  imessage_messages       Download iMessage messages (--head N)
  star_counts       Download star counts (--head N)
  release_batches   Download release batches (--head N)
  urls              Print all dataset URLs
  duckdb-examples   Print example DuckDB SQL queries

Options:
  --head N          Show first N rows
  --slim            (emails) Omit body text columns
  --include-text    (documents) Include full extracted text
  --no-cache        Skip local caching, always download fresh
```

### Beispiele

```bash theme={null}
# First 10 emails, network-only view
uv run jmail.py emails --slim --head 10

# All documents with full text
uv run jmail.py documents --include-text

# Datensatz-URLs zur Verwendung anderswo ausgeben
uv run jmail.py urls

# Get manifest with dataset checksums
uv run jmail.py manifest

# Fresh download (skip cache)
uv run jmail.py emails --no-cache --head 5
```

## Abhängigkeiten

Der Client hat drei Abhängigkeiten, die automatisch von `uv` verwaltet werden:

* `pandas` -- DataFrame-Verarbeitung
* `pyarrow` -- Lesen von Parquet-Dateien
* `requests` -- HTTP-Downloads

Diese werden inline gemäß PEP 723 deklariert:

```python theme={null}
# /// script
# requires-python = ">=3.9"
# dependencies = ["pandas", "pyarrow", "requests"]
# ///
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.