Metadata-Version: 2.4
Name: firefox-relay-api
Version: 0.1.0rc1
Summary: Unofficial Python client for Firefox Relay
Project-URL: Homepage, https://github.com/leo-proger/firefox-relay-api
Project-URL: Issues, https://github.com/leo-proger/firefox-relay-api/issues
Project-URL: Repository, https://github.com/leo-proger/firefox-relay-api
Author-email: Leo Proger <leoproger11@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: alias,email,firefox,mask,privacy,relay
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# firefox-relay-api

Unofficial Python client for [Firefox Relay](https://relay.firefox.com/). Not affiliated with Mozilla.

> ⚠️ The Firefox Relay API is **not officially documented** for third-party use. Endpoints and fields may change without
> notice.

## Install

```bash
pip install firefox-relay-api
```

Requires Python 3.10+.

## Quickstart

Get your API key from [Relay account settings](https://relay.firefox.com/accounts/profile/).

```python
from firefox_relay import FirefoxRelayClient

with FirefoxRelayClient(api_key="your-api-key") as client:
    # Create a mask
    mask = client.relay_addresses.create(description="for shopping")
    print(mask.full_address)  # e.g. abc123@mozmail.com

    # List all masks
    for m in client.relay_addresses.list():
        print(m.full_address, "—", m.description)

    # Rename
    client.relay_addresses.update(mask.id, description="renamed")

    # Disable (stop forwarding) without deleting
    client.relay_addresses.update(mask.id, enabled=False)

    # Delete
    client.relay_addresses.delete(mask.id)
```

## Error handling

All errors inherit from `RelayError`:

```python
from firefox_relay import RelayError, RelayAuthError, RelayRateLimitError

try:
    client.relay_addresses.list()
except RelayAuthError:
    print("Bad or expired API key")
except RelayRateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except RelayError as e:
    print(f"API error: {e.message} (HTTP {e.status_code})")
```

## Status

`v0.1.0` — MVP, supports random masks (`/relayaddresses/`) only.

Planned for `v0.2`: domain addresses (premium), profile, runtime data, async client.

## License

MIT
