tropmail 1.0.0__tar.gz

tropmail-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: mypy
+      - run: pytest -q

tropmail-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+# Push a tag like v1.2.3 (must match pyproject.toml version).
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Build without publishing
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Verify the tag matches the packaged version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          packaged="$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)"
+          if [ "$tag" != "$packaged" ]; then
+            echo "::error::tag v$tag does not match pyproject version $packaged"
+            exit 1
+          fi
+
+      - run: pip install -e ".[dev]" build
+      - run: ruff check src tests
+      - run: mypy
+      - run: pytest -q
+      - run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+  publish:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tropmail
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tropmail-1.0.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.whl
+.DS_Store
+.env
+PUBLISH.md

tropmail-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TropMail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tropmail-1.0.0/Makefile

@@ -0,0 +1,31 @@
+.PHONY: install test lint typecheck contract build clean
+
+VENV := .venv
+PY := $(VENV)/bin/python
+
+$(VENV):
+	python3 -m venv $(VENV)
+	$(PY) -m pip install --quiet --upgrade pip
+	$(PY) -m pip install --quiet -e ".[dev]"
+
+install: $(VENV)
+
+test: $(VENV)
+	$(PY) -m pytest -q
+
+lint: $(VENV)
+	$(PY) -m ruff check src tests examples
+
+typecheck: $(VENV)
+	$(PY) -m mypy
+	$(PY) -m mypy examples
+
+contract: $(VENV)
+	$(PY) -m pytest -q tests/test_contract.py
+
+build: $(VENV)
+	$(PY) -m pip install --quiet build
+	$(PY) -m build
+
+clean:
+	rm -rf $(VENV) dist build .pytest_cache .mypy_cache .ruff_cache

tropmail-1.0.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.5
+Name: tropmail
+Version: 1.0.0
+Summary: Official Python SDK for the TropMail API
+Project-URL: Homepage, https://tropmail.com
+Project-URL: Documentation, https://docs.tropmail.com
+Project-URL: Repository, https://github.com/tropmail/tropmail-python
+Author-email: TropMail <support@tropmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,email,sdk,tropmail,webmail
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: msgspec<1,>=0.18
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tropmail
+
+Official Python SDK for the [TropMail API](https://api.tropmail.com).
+
+Sync and async clients, fully typed, with automatic pagination, retries, and
+client-side rate-limit pacing.
+
+```bash
+pip install tropmail
+```
+
+Requires Python 3.10+. The client reads `TROPMAIL_API_KEY` unless you pass the key.
+
+## Quick start
+
+```python
+from tropmail import TropMail
+
+with TropMail() as client:           # reads TROPMAIL_API_KEY
+    mailbox = client.mailbox.get()
+    print(f"{mailbox.email}: {mailbox.opened_count} opened")
+
+    for email in client.emails.iterate(status="Open"):
+        print(email.timestamp, email.from_.address, email.subject)
+```
+
+Pass the key explicitly if you prefer:
+
+```python
+client = TropMail("your32charalphanumericapikeyhere")
+```
+
+## Async
+
+```python
+import asyncio
+from tropmail import AsyncTropMail
+
+async def main() -> None:
+    async with AsyncTropMail() as client:
+        async for email in client.emails.iterate(status="Favorite"):
+            print(email.subject)
+
+asyncio.run(main())
+```
+
+## Reading an email
+
+`get()` returns the HTML view by default. Pass the email object you already have
+instead of a bare id and the SDK forwards its timestamp for a faster lookup.
+
+```python
+page = client.emails.list(limit=10)
+email = page.emails[0]
+
+detail = client.emails.get(email, view="text")
+print(detail.content)
+
+for attachment in detail.attachments:
+    print(attachment.filename, attachment.size, attachment.scan_status)
+```
+
+### Markdown
+
+The markdown view is generated on demand and the server can block for up to a
+minute before answering `504`. `get_markdown()` handles that retry for you:
+
+```python
+detail = client.emails.get_markdown(email)
+print(detail.content)
+```
+
+## Actions
+
+```python
+client.emails.favorite(email)
+client.emails.close(email)
+client.emails.block(email)          # also blocks the sender for future mail
+client.emails.clear_action(email)   # clears the action, unblocking the sender
+```
+
+All of them are shorthands for `update()`:
+
+```python
+client.emails.update(email, email_state="Open", action_status="Favorite")
+```
+
+## Attachments
+
+```python
+info = client.attachments.get(attachment_id)
+print(info.filename, info.scan_status)
+
+client.attachments.scan(attachment_id)
+path = client.attachments.download_to(attachment_id, "/tmp/invoice.pdf")
+```
+
+The download URL lives on a separate host, so no API credentials are ever sent to it.
+
+## Search
+
+```python
+page = client.emails.search("invoice", limit=25)
+for email in client.emails.search_iterate("invoice"):
+    print(email.subject)
+```
+
+Note that the API always reports `total: 0` for search results. The iterators
+page until they see a short page rather than trusting `total`.
+
+## Errors
+
+```python
+from tropmail import (
+    AuthenticationError, NotFoundError, RateLimitError,
+    TierError, TropMailError,
+)
+
+try:
+    client.emails.get("does-not-exist")
+except NotFoundError as exc:
+    print(exc.status, exc.request_id)
+except RateLimitError as exc:
+    print("retry after", exc.retry_after)
+except TropMailError as exc:
+    print("request failed:", exc)
+```
+
+Every error carries `status`, `message`, and the `request_id` echoed by the API,
+which is what support needs to trace a call.
+
+| Exception | HTTP |
+|---|---|
+| `ValidationError` | 400 |
+| `AuthenticationError` | 401 |
+| `TierError` | 403 |
+| `NotFoundError` | 404 |
+| `RateLimitError` | 429 |
+| `MarkdownTimeoutError` | 504 |
+| `ServerError` | 5xx |
+| `ConnectionError` | transport failure |
+
+## Rate limits
+
+Budgets are per mailbox, per second: Pro 3, Ultimate 10, Enterprise 50.
+
+The client reads the limit from response headers and paces itself with a token
+bucket so you stay under the budget instead of collecting `429`s. Inspect the
+current window at any time:
+
+```python
+print(client.rate_limit)   # RateLimitInfo(limit=3, remaining=2, reset=1767225600)
+```
+
+Disable pacing with `TropMail(throttle=False)` if you manage concurrency yourself.
+
+## Configuration
+
+```python
+client = TropMail(
+    api_key=None,                                  # else TROPMAIL_API_KEY
+    base_url="https://api.tropmail.com/api/v1",
+    timeout=120.0,                                 # markdown can block ~60s
+    max_retries=3,
+    throttle=True,
+)
+```
+
+Retries use exponential backoff with full jitter on 429, 502, 503, 504, and
+transport errors. Reads retry automatically; mutations never do.
+
+## Examples
+
+Runnable scripts live in [`examples/`](examples/): a quickstart, a concurrent
+async inbox reader, and attachment downloading.
+
+## Development
+
+```bash
+make install
+make test
+make lint
+make typecheck
+```
+
+## Docs
+
+Guides and API reference: [docs.tropmail.com](https://docs.tropmail.com/sdks/python/).
+
+## License
+
+MIT

tropmail-1.0.0/README.md

@@ -0,0 +1,192 @@
+# tropmail
+
+Official Python SDK for the [TropMail API](https://api.tropmail.com).
+
+Sync and async clients, fully typed, with automatic pagination, retries, and
+client-side rate-limit pacing.
+
+```bash
+pip install tropmail
+```
+
+Requires Python 3.10+. The client reads `TROPMAIL_API_KEY` unless you pass the key.
+
+## Quick start
+
+```python
+from tropmail import TropMail
+
+with TropMail() as client:           # reads TROPMAIL_API_KEY
+    mailbox = client.mailbox.get()
+    print(f"{mailbox.email}: {mailbox.opened_count} opened")
+
+    for email in client.emails.iterate(status="Open"):
+        print(email.timestamp, email.from_.address, email.subject)
+```
+
+Pass the key explicitly if you prefer:
+
+```python
+client = TropMail("your32charalphanumericapikeyhere")
+```
+
+## Async
+
+```python
+import asyncio
+from tropmail import AsyncTropMail
+
+async def main() -> None:
+    async with AsyncTropMail() as client:
+        async for email in client.emails.iterate(status="Favorite"):
+            print(email.subject)
+
+asyncio.run(main())
+```
+
+## Reading an email
+
+`get()` returns the HTML view by default. Pass the email object you already have
+instead of a bare id and the SDK forwards its timestamp for a faster lookup.
+
+```python
+page = client.emails.list(limit=10)
+email = page.emails[0]
+
+detail = client.emails.get(email, view="text")
+print(detail.content)
+
+for attachment in detail.attachments:
+    print(attachment.filename, attachment.size, attachment.scan_status)
+```
+
+### Markdown
+
+The markdown view is generated on demand and the server can block for up to a
+minute before answering `504`. `get_markdown()` handles that retry for you:
+
+```python
+detail = client.emails.get_markdown(email)
+print(detail.content)
+```
+
+## Actions
+
+```python
+client.emails.favorite(email)
+client.emails.close(email)
+client.emails.block(email)          # also blocks the sender for future mail
+client.emails.clear_action(email)   # clears the action, unblocking the sender
+```
+
+All of them are shorthands for `update()`:
+
+```python
+client.emails.update(email, email_state="Open", action_status="Favorite")
+```
+
+## Attachments
+
+```python
+info = client.attachments.get(attachment_id)
+print(info.filename, info.scan_status)
+
+client.attachments.scan(attachment_id)
+path = client.attachments.download_to(attachment_id, "/tmp/invoice.pdf")
+```
+
+The download URL lives on a separate host, so no API credentials are ever sent to it.
+
+## Search
+
+```python
+page = client.emails.search("invoice", limit=25)
+for email in client.emails.search_iterate("invoice"):
+    print(email.subject)
+```
+
+Note that the API always reports `total: 0` for search results. The iterators
+page until they see a short page rather than trusting `total`.
+
+## Errors
+
+```python
+from tropmail import (
+    AuthenticationError, NotFoundError, RateLimitError,
+    TierError, TropMailError,
+)
+
+try:
+    client.emails.get("does-not-exist")
+except NotFoundError as exc:
+    print(exc.status, exc.request_id)
+except RateLimitError as exc:
+    print("retry after", exc.retry_after)
+except TropMailError as exc:
+    print("request failed:", exc)
+```
+
+Every error carries `status`, `message`, and the `request_id` echoed by the API,
+which is what support needs to trace a call.
+
+| Exception | HTTP |
+|---|---|
+| `ValidationError` | 400 |
+| `AuthenticationError` | 401 |
+| `TierError` | 403 |
+| `NotFoundError` | 404 |
+| `RateLimitError` | 429 |
+| `MarkdownTimeoutError` | 504 |
+| `ServerError` | 5xx |
+| `ConnectionError` | transport failure |
+
+## Rate limits
+
+Budgets are per mailbox, per second: Pro 3, Ultimate 10, Enterprise 50.
+
+The client reads the limit from response headers and paces itself with a token
+bucket so you stay under the budget instead of collecting `429`s. Inspect the
+current window at any time:
+
+```python
+print(client.rate_limit)   # RateLimitInfo(limit=3, remaining=2, reset=1767225600)
+```
+
+Disable pacing with `TropMail(throttle=False)` if you manage concurrency yourself.
+
+## Configuration
+
+```python
+client = TropMail(
+    api_key=None,                                  # else TROPMAIL_API_KEY
+    base_url="https://api.tropmail.com/api/v1",
+    timeout=120.0,                                 # markdown can block ~60s
+    max_retries=3,
+    throttle=True,
+)
+```
+
+Retries use exponential backoff with full jitter on 429, 502, 503, 504, and
+transport errors. Reads retry automatically; mutations never do.
+
+## Examples
+
+Runnable scripts live in [`examples/`](examples/): a quickstart, a concurrent
+async inbox reader, and attachment downloading.
+
+## Development
+
+```bash
+make install
+make test
+make lint
+make typecheck
+```
+
+## Docs
+
+Guides and API reference: [docs.tropmail.com](https://docs.tropmail.com/sdks/python/).
+
+## License
+
+MIT

tropmail-1.0.0/examples/README.md

@@ -0,0 +1,21 @@
+# Python examples
+
+```bash
+pip install tropmail
+export TROPMAIL_API_KEY=your32charalphanumericapikeyhere
+```
+
+| File | What it shows |
+|---|---|
+| [`quickstart.py`](quickstart.py) | mailbox summary, listing, reading one message, typed errors |
+| [`async_inbox.py`](async_inbox.py) | `AsyncTropMail`, auto-paging `async for`, concurrent reads under the rate limit |
+| [`save_attachments.py`](save_attachments.py) | scanning attachments and streaming them to disk |
+
+```bash
+python examples/quickstart.py
+python examples/async_inbox.py
+python examples/save_attachments.py <email-id> ./downloads
+```
+
+These are type-checked in CI (`make lint typecheck`), so they cannot drift from
+the SDK.

tropmail-1.0.0/examples/async_inbox.py

@@ -0,0 +1,52 @@
+"""Fetch several message bodies concurrently with the async client.
+
+    export TROPMAIL_API_KEY=...
+    python examples/async_inbox.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from tropmail import AsyncTropMail, Email, EmailDetail, TropMailError
+
+
+async def read(client: AsyncTropMail, email: Email) -> EmailDetail | None:
+    """Fetch one body, returning None instead of raising so one failure does
+    not sink the whole batch."""
+    try:
+        return await client.emails.get(email, view="text")
+    except TropMailError as error:
+        print(f"{email.id}: {error}")
+        return None
+
+
+async def main() -> None:
+    async with AsyncTropMail() as client:
+        mailbox = await client.mailbox.get()
+        print(f"{mailbox.email}\n")
+
+        # Collect the unread messages, capped so the example stays quick.
+        unread: list[Email] = []
+        async for email in client.emails.iterate(status="Open"):
+            unread.append(email)
+            if len(unread) == 10:
+                break
+
+        if not unread:
+            print("Nothing unread.")
+            return
+
+        # The client's token bucket paces these against the tier's per-second
+        # budget, so firing them all at once will not produce 429s.
+        details = await asyncio.gather(*(read(client, email) for email in unread))
+
+        for email, detail in zip(unread, details, strict=True):
+            if detail is None:
+                continue
+            preview = " ".join(detail.content.split())[:80]
+            print(f"{email.from_.address:<24} {email.subject[:30]:<30} {preview}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tropmail-1.0.0/examples/quickstart.py

@@ -0,0 +1,47 @@
+"""Print a mailbox summary and read the newest message.
+
+    export TROPMAIL_API_KEY=...
+    python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+from tropmail import NotFoundError, TropMail, TropMailError
+
+
+def main() -> None:
+    # No api_key argument: the client reads TROPMAIL_API_KEY and validates the
+    # format locally, so a malformed key fails before spending a round trip.
+    with TropMail() as client:
+        mailbox = client.mailbox.get()
+        print(
+            f"{mailbox.email} — {mailbox.opened_count} open, "
+            f"{mailbox.closed_count} closed, {mailbox.favorite_count} favorite\n"
+        )
+
+        page = client.emails.list(limit=5)
+        if not page.emails:
+            print("The mailbox is empty.")
+            return
+
+        for email in page.emails:
+            print(f"{email.from_.address:<24} {email.subject[:40]:<40} {email.timestamp}")
+
+        # Passing the email object rather than its id forwards the timestamp
+        # for a faster lookup.
+        newest = page.emails[0]
+        try:
+            detail = client.emails.get(newest, view="text")
+        except NotFoundError:
+            print("\nThat message was deleted between listing and reading it.")
+            return
+        except TropMailError as error:
+            print(f"\nRead failed ({error.status}, request {error.request_id}): {error}")
+            return
+
+        print(f"\n--- {detail.subject} ---")
+        print(detail.content[:500])
+
+
+if __name__ == "__main__":
+    main()