> ## 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.

# JmailClient

> Client constructor and configuration

## Constructor

```python theme={null}
JmailClient(cache=True)
```

Create a new client instance.

### Parameters

<ParamField query="cache" type="bool" default="True">
  Enable local ETag-based file caching at `~/.cache/jmail/`. Set to `False` to always download fresh data.
</ParamField>

### Example

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

# Default: caching enabled
client = JmailClient()

# No caching
client = JmailClient(cache=False)
```

## Methods

| Method                                                 | Returns     | Description                        |
| ------------------------------------------------------ | ----------- | ---------------------------------- |
| [`manifest()`](/docs/api-reference/jmail-client#manifest)   | `dict`      | API manifest with dataset metadata |
| [`emails(slim)`](/docs/api-reference/emails)                | `DataFrame` | Email archive                      |
| [`documents(include_text)`](/docs/api-reference/documents)  | `DataFrame` | Document metadata/text             |
| [`photos()`](/docs/api-reference/photos)                    | `DataFrame` | Photo metadata                     |
| [`people()`](/docs/api-reference/people)                    | `DataFrame` | Identified people                  |
| [`photo_faces()`](/docs/api-reference/photo-faces)          | `DataFrame` | Face bounding boxes                |
| [`imessage_conversations()`](/docs/api-reference/imessages) | `DataFrame` | iMessage conversations             |
| [`imessage_messages()`](/docs/api-reference/imessages)      | `DataFrame` | iMessage messages                  |
| [`star_counts()`](/docs/api-reference/star-counts)          | `DataFrame` | Crowd-sourced stars                |
| [`release_batches()`](/docs/api-reference/release-batches)  | `DataFrame` | Release batch info                 |
| [`url(dataset, fmt)`](/docs/api-reference/jmail-client#url) | `str`       | Raw dataset URL                    |

## `manifest()`

Fetch the API manifest with dataset metadata and checksums.

```python theme={null}
manifest = client.manifest()
print(manifest)
```

**Returns:** `dict` -- parsed JSON from `data.jmail.world/v1/manifest.json`

## `url(dataset, fmt="parquet")`

Get the raw URL for a dataset file. Useful for passing directly to DuckDB, Polars, or any tool that reads Parquet over HTTP.

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

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

<ParamField query="dataset" type="str" required>
  Dataset name. One of: `emails`, `emails-slim`, `documents`, `photos`, `people`, `photo_faces`, `imessage_conversations`, `imessage_messages`, `star_counts`, `release_batches`.
</ParamField>

<ParamField query="fmt" type="str" default="parquet">
  File format. Either `parquet` or `ndjson.gz`.
</ParamField>

**Returns:** `str` -- full URL