notletters-client 0.1.0__tar.gz

notletters_client-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Dependencies
+node_modules/
+.pnp.*
+.yarn/
+.pnpm-store/
+
+# Build
+dist/
+build/
+*.tsbuildinfo
+*.egg-info/
+.eggs/
+wheels/
+
+# Tests and coverage
+coverage/
+.nyc_output/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+
+# Secrets
+.env
+.env.*
+!.env.example
+AGENTS.md
+
+# GitBook / HonKit
+_book/
+
+# OS and editors
+.DS_Store
+Thumbs.db
+.idea/
+*.swp

notletters_client-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 api-kit contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

notletters_client-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: notletters-client
+Version: 0.1.0
+Summary: Python client for the NotLetters email receiving and mailbox API
+Project-URL: Repository, https://github.com/TysikGG/api-kit
+Project-URL: Documentation, https://notletters.com/user/documentation
+License-Expression: ISC
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# notletters-client
+
+[![PyPI version](https://img.shields.io/pypi/v/notletters-client.svg)](https://pypi.org/project/notletters-client/)
+[![Python versions](https://img.shields.io/pypi/pyversions/notletters-client.svg)](https://pypi.org/project/notletters-client/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+Modern, typed Python client for the [NotLetters API](https://notletters.com). Manage disposable email mailboxes, retrieve incoming messages, search message contents, change mailbox passwords, and purchase mail accounts in bulk. Built on [HTTPX](https://www.python-httpx.org).
+
+Official API documentation: <https://notletters.com/user/documentation>
+
+---
+
+## Features
+
+- ✉️ **Message Retrieval & Search** — Fetch incoming emails with full HTML and plain text bodies, search queries, and star filters.
+- 📬 **Bulk Mailbox Purchase** — Order mailboxes programmatically across limit, unlimited, RU zone, and personal categories.
+- 🔑 **Password Management** — Change passwords for managed mailboxes.
+- 💰 **Account Information** — Check your account balance and rate limits.
+- 🐍 **Modern Python** — Type-annotated, Google-style docstrings, context manager support (`with NotLetters(...) as client:`).
+- 🚨 **Structured Errors** — Clear `NotLettersError` exceptions with subclasses for common HTTP status codes.
+
+---
+
+## Installation
+
+```bash
+pip install notletters-client
+```
+
+Requires Python 3.10 or higher.
+
+---
+
+## Quick Start (Safe Check)
+
+The quick check only inspects your account balance and user profile. It does not purchase mailboxes or spend money.
+
+```python
+import os
+from notletters import NotLetters
+
+api_token = os.environ["NOTLETTERS_API_TOKEN"]
+
+with NotLetters(api_token) as client:
+    profile = client.get_me()
+    print(f"Authenticated as: {profile['username']}")
+    print(f"Balance: {profile['balance']} RUB")
+    print(f"Rate limit: {profile['rate_limit']} req/min")
+```
+
+---
+
+## Usage Guide
+
+### 1. Retrieving Emails from a Mailbox
+
+Retrieve incoming messages for a mailbox with optional text search and star filtering:
+
+```python
+import os
+from notletters import NotLetters
+
+with NotLetters(os.environ["NOTLETTERS_API_TOKEN"]) as client:
+    letters = client.get_letters(
+        email="test@notletters.com",
+        password="mailbox-password",
+        search="Confirmation Code",
+        star=False,
+    )
+
+    for letter in letters:
+        print(f"ID: {letter['id']}")
+        print(f"From: {letter['sender_name']} <{letter['sender']}>")
+        print(f"Subject: {letter['subject']}")
+        print(f"Text body: {letter['letter']['text']}")
+```
+
+### 2. Changing Mailbox Password
+
+Update the password of an existing mailbox:
+
+```python
+import os
+from notletters import NotLetters
+
+with NotLetters(os.environ["NOTLETTERS_API_TOKEN"]) as client:
+    res = client.change_password(
+        email="test@notletters.com",
+        old_password="old-password",
+        new_password="new-password",
+    )
+    print(res["data"])  # "password successful changed"
+```
+
+### 3. Purchasing Mailboxes
+
+> [!WARNING]
+> Purchasing mailboxes charges your NotLetters account balance.
+
+```python
+import os
+from notletters import EmailType, NotLetters
+
+# EmailType:
+# - EmailType.LIMIT (0) - Limited emails
+# - EmailType.UNLIMITED (1) - Unlimited emails
+# - EmailType.RU_ZONE (2) - Russian zone emails
+# - EmailType.PERSONAL (3) - Personal emails
+
+with NotLetters(os.environ["NOTLETTERS_API_TOKEN"]) as client:
+    accounts = client.buy_emails(count=2, type_email=EmailType.LIMIT)
+
+    for account in accounts:
+        print(f"Email: {account.email}")
+        print(f"Password: {account.password}")
+        print(f"Raw: {account.raw}")
+```
+
+### 4. Parsing Credentials
+
+Parse any raw `"email:password"` string into a structured object:
+
+```python
+from notletters import parse_mail
+
+account = parse_mail("user@notletters.com:pass123")
+print(account.email)     # "user@notletters.com"
+print(account.password)  # "pass123"
+print(str(account))      # "user@notletters.com:pass123"
+```
+
+---
+
+## Error Handling
+
+When the API returns an error, the client raises a `NotLettersError` with status code and payload details:
+
+```python
+import os
+from notletters import (
+    NotLetters,
+    NotLettersBadRequestError,
+    NotLettersError,
+    NotLettersPaymentRequiredError,
+    NotLettersUnauthorizedError,
+)
+
+with NotLetters("invalid-token") as client:
+    try:
+        client.get_me()
+    except NotLettersUnauthorizedError:
+        print("Invalid or expired API token")
+    except NotLettersPaymentRequiredError:
+        print("Insufficient balance for operation")
+    except NotLettersError as err:
+        print(f"NotLetters API error [{err.status_code}]: {err.message}")
+```
+
+---
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `api_token` | `str \| None` | `os.environ.get("NOTLETTERS_API_TOKEN")` | Bearer token for API authentication |
+| `base_url` | `str \| None` | `https://api.notletters.com/v1` | Custom base URL for the API |
+| `timeout` | `float` | `30.0` | Request timeout in seconds |
+| `user_agent` | `str \| None` | `notletters-client/0.1.0` | Custom User-Agent header |
+
+---
+
+## License
+
+[ISC](LICENSE)

notletters_client-0.1.0/README.md

@@ -0,0 +1,174 @@
+# notletters-client
+
+[![PyPI version](https://img.shields.io/pypi/v/notletters-client.svg)](https://pypi.org/project/notletters-client/)
+[![Python versions](https://img.shields.io/pypi/pyversions/notletters-client.svg)](https://pypi.org/project/notletters-client/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+Modern, typed Python client for the [NotLetters API](https://notletters.com). Manage disposable email mailboxes, retrieve incoming messages, search message contents, change mailbox passwords, and purchase mail accounts in bulk. Built on [HTTPX](https://www.python-httpx.org).
+
+Official API documentation: <https://notletters.com/user/documentation>
+
+---
+
+## Features
+
+- ✉️ **Message Retrieval & Search** — Fetch incoming emails with full HTML and plain text bodies, search queries, and star filters.
+- 📬 **Bulk Mailbox Purchase** — Order mailboxes programmatically across limit, unlimited, RU zone, and personal categories.
+- 🔑 **Password Management** — Change passwords for managed mailboxes.
+- 💰 **Account Information** — Check your account balance and rate limits.
+- 🐍 **Modern Python** — Type-annotated, Google-style docstrings, context manager support (`with NotLetters(...) as client:`).
+- 🚨 **Structured Errors** — Clear `NotLettersError` exceptions with subclasses for common HTTP status codes.
+
+---
+
+## Installation
+
+```bash
+pip install notletters-client
+```
+
+Requires Python 3.10 or higher.
+
+---
+
+## Quick Start (Safe Check)
+
+The quick check only inspects your account balance and user profile. It does not purchase mailboxes or spend money.
+
+```python
+import os
+from notletters import NotLetters
+
+api_token = os.environ["NOTLETTERS_API_TOKEN"]
+
+with NotLetters(api_token) as client:
+    profile = client.get_me()
+    print(f"Authenticated as: {profile['username']}")
+    print(f"Balance: {profile['balance']} RUB")
+    print(f"Rate limit: {profile['rate_limit']} req/min")
+```
+
+---
+
+## Usage Guide
+
+### 1. Retrieving Emails from a Mailbox
+
+Retrieve incoming messages for a mailbox with optional text search and star filtering:
+
+```python
+import os
+from notletters import NotLetters
+
+with NotLetters(os.environ["NOTLETTERS_API_TOKEN"]) as client:
+    letters = client.get_letters(
+        email="test@notletters.com",
+        password="mailbox-password",
+        search="Confirmation Code",
+        star=False,
+    )
+
+    for letter in letters:
+        print(f"ID: {letter['id']}")
+        print(f"From: {letter['sender_name']} <{letter['sender']}>")
+        print(f"Subject: {letter['subject']}")
+        print(f"Text body: {letter['letter']['text']}")
+```
+
+### 2. Changing Mailbox Password
+
+Update the password of an existing mailbox:
+
+```python
+import os
+from notletters import NotLetters
+
+with NotLetters(os.environ["NOTLETTERS_API_TOKEN"]) as client:
+    res = client.change_password(
+        email="test@notletters.com",
+        old_password="old-password",
+        new_password="new-password",
+    )
+    print(res["data"])  # "password successful changed"
+```
+
+### 3. Purchasing Mailboxes
+
+> [!WARNING]
+> Purchasing mailboxes charges your NotLetters account balance.
+
+```python
+import os
+from notletters import EmailType, NotLetters
+
+# EmailType:
+# - EmailType.LIMIT (0) - Limited emails
+# - EmailType.UNLIMITED (1) - Unlimited emails
+# - EmailType.RU_ZONE (2) - Russian zone emails
+# - EmailType.PERSONAL (3) - Personal emails
+
+with NotLetters(os.environ["NOTLETTERS_API_TOKEN"]) as client:
+    accounts = client.buy_emails(count=2, type_email=EmailType.LIMIT)
+
+    for account in accounts:
+        print(f"Email: {account.email}")
+        print(f"Password: {account.password}")
+        print(f"Raw: {account.raw}")
+```
+
+### 4. Parsing Credentials
+
+Parse any raw `"email:password"` string into a structured object:
+
+```python
+from notletters import parse_mail
+
+account = parse_mail("user@notletters.com:pass123")
+print(account.email)     # "user@notletters.com"
+print(account.password)  # "pass123"
+print(str(account))      # "user@notletters.com:pass123"
+```
+
+---
+
+## Error Handling
+
+When the API returns an error, the client raises a `NotLettersError` with status code and payload details:
+
+```python
+import os
+from notletters import (
+    NotLetters,
+    NotLettersBadRequestError,
+    NotLettersError,
+    NotLettersPaymentRequiredError,
+    NotLettersUnauthorizedError,
+)
+
+with NotLetters("invalid-token") as client:
+    try:
+        client.get_me()
+    except NotLettersUnauthorizedError:
+        print("Invalid or expired API token")
+    except NotLettersPaymentRequiredError:
+        print("Insufficient balance for operation")
+    except NotLettersError as err:
+        print(f"NotLetters API error [{err.status_code}]: {err.message}")
+```
+
+---
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `api_token` | `str \| None` | `os.environ.get("NOTLETTERS_API_TOKEN")` | Bearer token for API authentication |
+| `base_url` | `str \| None` | `https://api.notletters.com/v1` | Custom base URL for the API |
+| `timeout` | `float` | `30.0` | Request timeout in seconds |
+| `user_agent` | `str \| None` | `notletters-client/0.1.0` | Custom User-Agent header |
+
+---
+
+## License
+
+[ISC](LICENSE)

notletters_client-0.1.0/examples/quickstart.py

@@ -0,0 +1,21 @@
+import os
+import sys
+
+from notletters import NotLetters
+
+
+def main() -> None:
+    api_token = os.environ.get("NOTLETTERS_API_TOKEN")
+    if not api_token:
+        print("Please set NOTLETTERS_API_TOKEN environment variable", file=sys.stderr)
+        sys.exit(1)
+
+    with NotLetters(api_token) as client:
+        profile = client.get_me()
+        print(f"Authenticated as: {profile['username']} (ID: {profile['id']})")
+        print(f"Current balance: {profile['balance']} RUB")
+        print(f"Rate limit: {profile['rate_limit']} req/min")
+
+
+if __name__ == "__main__":
+    main()

notletters_client-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+# Publish trigger
+# NotLetters API client
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "notletters-client"
+version = "0.1.0"
+description = "Python client for the NotLetters email receiving and mailbox API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "ISC"
+dependencies = [
+  "httpx>=0.27",
+]
+
+[project.urls]
+Repository = "https://github.com/TysikGG/api-kit"
+Documentation = "https://notletters.com/user/documentation"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-httpx>=0.30",
+  "ruff>=0.8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/notletters"]
+
+[tool.pytest.ini_options]
+markers = [
+  "live: calls the real NotLetters API and needs NOTLETTERS_API_TOKEN",
+]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

notletters_client-0.1.0/src/notletters/__init__.py

@@ -0,0 +1,41 @@
+from .client import NotLetters
+from .errors import (
+    NotLettersBadRequestError,
+    NotLettersError,
+    NotLettersForbiddenError,
+    NotLettersInternalServerError,
+    NotLettersNotFoundError,
+    NotLettersPaymentRequiredError,
+    NotLettersUnauthorizedError,
+    create_notletters_error,
+)
+from .types import (
+    ChangePasswordResult,
+    EmailType,
+    Letter,
+    LetterBody,
+    LetterFilters,
+    Mail,
+    UserData,
+    parse_mail,
+)
+
+__all__ = [
+    "ChangePasswordResult",
+    "EmailType",
+    "Letter",
+    "LetterBody",
+    "LetterFilters",
+    "Mail",
+    "NotLetters",
+    "NotLettersBadRequestError",
+    "NotLettersError",
+    "NotLettersForbiddenError",
+    "NotLettersInternalServerError",
+    "NotLettersNotFoundError",
+    "NotLettersPaymentRequiredError",
+    "NotLettersUnauthorizedError",
+    "UserData",
+    "create_notletters_error",
+    "parse_mail",
+]