mailflat 0.1.0__tar.gz

mailflat-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+venv/
+.venv/
+*.db
+*.db-wal
+*.db-shm
+
+# env — secret'lar asla commit edilmez (.env.example HARİÇ, o şablon)
+.env
+.env.*
+!.env.example
+
+# secrets — DKIM gizli anahtarı + SSH key'ler
+*.pem
+*_key
+*_key.pub
+id_rsa*
+id_ed25519*
+
+# Node / Next.js
+node_modules/
+.next/
+dist/
+out/
+
+# Playwright (E2E) — test çıktıları + indirilen browser'lar
+test-results/
+playwright-report/
+playwright/.cache/
+.last-run.json
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+/Keys

mailflat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MailFlat
+
+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.

mailflat-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: mailflat
+Version: 0.1.0
+Summary: Official Python SDK for MailFlat — disposable, automation-friendly email inboxes with one-line OTP retrieval.
+Project-URL: Homepage, https://mailflat.net
+Project-URL: Documentation, https://mailflat.net/docs
+Project-URL: Source, https://github.com/onderyentar/mailflat
+Author-email: MailFlat <support@mailflat.net>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,automation,disposable-email,email,otp,temporary-email,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MailFlat — Python SDK
+
+Official Python client for [MailFlat](https://mailflat.net): disposable, automation-friendly
+email inboxes with **one-line OTP retrieval**. Spin up a real inbox, read the verification
+code your app just sent, and move on — no flaky polling, no shared mailbox state.
+
+```bash
+pip install mailflat
+```
+
+## Quickstart
+
+```python
+from mailflat import MailFlat
+
+mf = MailFlat(api_key="mf_live_...")  # or set MAILFLAT_API_KEY
+
+# 1 · spin up a disposable inbox
+inbox = mf.create(label="signup-test")
+print(inbox.address)            # → signup-test-8f3@x7k2m.mailflat.net
+
+# 2 · your app/browser submits the form using inbox.address ...
+
+# 3 · grab the OTP (polls until it arrives or times out)
+otp = inbox.wait_for_otp(timeout=30)
+print(otp)                      # → "123456"
+
+# inbox auto-clears in 2h — no cleanup needed (or call inbox.delete())
+```
+
+## For AI agents
+
+Hand an agent one API key and it spins up real inboxes on demand:
+
+```python
+mf = MailFlat()  # reads MAILFLAT_API_KEY
+
+inbox = mf.create(label="deep-research")
+browser.fill("#email", inbox.address)
+browser.click("Sign up")
+
+otp = inbox.wait_for_otp(timeout=30)
+browser.fill("#code", otp)
+```
+
+## API
+
+### `MailFlat(api_key=None, *, base_url="https://mailflat.net", timeout=30.0, max_retries=2)`
+Client. `api_key` falls back to the `MAILFLAT_API_KEY` environment variable. Use `base_url`
+for self-hosted / BYOD deployments. Supports use as a context manager (`with MailFlat() as mf:`).
+
+- `create(*, prefix=None, label=None, subdomain=None, domain=None, retention_hours=None) -> Inbox`
+  — open a new inbox. `create_inbox(...)` is an alias.
+- `list() -> list[Inbox]` — inboxes opened with this key.
+- `inbox(address) -> Inbox` — attach to an existing address without a network call.
+
+### `Inbox`
+- `.address` — the email address.
+- `.messages() -> list[Message]` — all messages, newest first.
+- `.latest() -> Message | None` — most recent message.
+- `.wait_for_otp(*, timeout=30, poll_interval=1.0) -> str` — poll until an OTP arrives; returns the code.
+- `.wait_for_message(*, timeout=30, poll_interval=1.0) -> Message` — poll until any message arrives.
+- `.send(to, *, subject="", body="", html=None) -> dict` — send a DKIM-signed email from this inbox.
+- `.delete() -> dict` — delete the inbox and all its messages.
+
+### `Message`
+`.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`, `.raw`.
+
+## Errors
+
+All errors subclass `MailFlatError`: `AuthenticationError` (401), `PermissionError` (403),
+`NotFoundError` (404), `RateLimitError` (429), `APIError` (other), `OTPTimeoutError`
+(no OTP before timeout), `EncryptedInboxError` (the inbox is end-to-end encrypted, so the
+server cannot read its contents — use a non-encrypted inbox for agent automation).
+
+## License
+
+MIT

mailflat-0.1.0/README.md

@@ -0,0 +1,78 @@
+# MailFlat — Python SDK
+
+Official Python client for [MailFlat](https://mailflat.net): disposable, automation-friendly
+email inboxes with **one-line OTP retrieval**. Spin up a real inbox, read the verification
+code your app just sent, and move on — no flaky polling, no shared mailbox state.
+
+```bash
+pip install mailflat
+```
+
+## Quickstart
+
+```python
+from mailflat import MailFlat
+
+mf = MailFlat(api_key="mf_live_...")  # or set MAILFLAT_API_KEY
+
+# 1 · spin up a disposable inbox
+inbox = mf.create(label="signup-test")
+print(inbox.address)            # → signup-test-8f3@x7k2m.mailflat.net
+
+# 2 · your app/browser submits the form using inbox.address ...
+
+# 3 · grab the OTP (polls until it arrives or times out)
+otp = inbox.wait_for_otp(timeout=30)
+print(otp)                      # → "123456"
+
+# inbox auto-clears in 2h — no cleanup needed (or call inbox.delete())
+```
+
+## For AI agents
+
+Hand an agent one API key and it spins up real inboxes on demand:
+
+```python
+mf = MailFlat()  # reads MAILFLAT_API_KEY
+
+inbox = mf.create(label="deep-research")
+browser.fill("#email", inbox.address)
+browser.click("Sign up")
+
+otp = inbox.wait_for_otp(timeout=30)
+browser.fill("#code", otp)
+```
+
+## API
+
+### `MailFlat(api_key=None, *, base_url="https://mailflat.net", timeout=30.0, max_retries=2)`
+Client. `api_key` falls back to the `MAILFLAT_API_KEY` environment variable. Use `base_url`
+for self-hosted / BYOD deployments. Supports use as a context manager (`with MailFlat() as mf:`).
+
+- `create(*, prefix=None, label=None, subdomain=None, domain=None, retention_hours=None) -> Inbox`
+  — open a new inbox. `create_inbox(...)` is an alias.
+- `list() -> list[Inbox]` — inboxes opened with this key.
+- `inbox(address) -> Inbox` — attach to an existing address without a network call.
+
+### `Inbox`
+- `.address` — the email address.
+- `.messages() -> list[Message]` — all messages, newest first.
+- `.latest() -> Message | None` — most recent message.
+- `.wait_for_otp(*, timeout=30, poll_interval=1.0) -> str` — poll until an OTP arrives; returns the code.
+- `.wait_for_message(*, timeout=30, poll_interval=1.0) -> Message` — poll until any message arrives.
+- `.send(to, *, subject="", body="", html=None) -> dict` — send a DKIM-signed email from this inbox.
+- `.delete() -> dict` — delete the inbox and all its messages.
+
+### `Message`
+`.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`, `.raw`.
+
+## Errors
+
+All errors subclass `MailFlatError`: `AuthenticationError` (401), `PermissionError` (403),
+`NotFoundError` (404), `RateLimitError` (429), `APIError` (other), `OTPTimeoutError`
+(no OTP before timeout), `EncryptedInboxError` (the inbox is end-to-end encrypted, so the
+server cannot read its contents — use a non-encrypted inbox for agent automation).
+
+## License
+
+MIT

mailflat-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mailflat"
+version = "0.1.0"
+description = "Official Python SDK for MailFlat — disposable, automation-friendly email inboxes with one-line OTP retrieval."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "MailFlat", email = "support@mailflat.net" }]
+keywords = ["email", "disposable-email", "otp", "automation", "testing", "ai-agents", "temporary-email"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Communications :: Email",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://mailflat.net"
+Documentation = "https://mailflat.net/docs"
+Source = "https://github.com/onderyentar/mailflat"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "respx>=0.20"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailflat"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/mailflat", "README.md", "LICENSE"]

mailflat-0.1.0/src/mailflat/__init__.py

@@ -0,0 +1,45 @@
+"""MailFlat Python SDK — disposable, otomasyon-dostu e-posta inbox'ları için resmi client.
+
+`pip install mailflat` → `from mailflat import MailFlat`.
+
+Connected to:
+  - imports from: mailflat.client, mailflat.inbox, mailflat.errors
+  - imported by:  kullanıcı kodu, mailflat-mcp, mailflat.langchain
+
+Key exports:
+  - `MailFlat` — client
+  - `Inbox`, `Message` — domain tipleri
+  - hata tipleri: `MailFlatError`, `AuthenticationError`, `PermissionError`,
+    `NotFoundError`, `RateLimitError`, `APIError`, `OTPTimeoutError`, `EncryptedInboxError`
+"""
+from __future__ import annotations
+
+from .client import MailFlat
+from .errors import (
+    APIError,
+    AuthenticationError,
+    EncryptedInboxError,
+    MailFlatError,
+    NotFoundError,
+    OTPTimeoutError,
+    PermissionError,
+    RateLimitError,
+)
+from .inbox import Inbox, Message
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MailFlat",
+    "Inbox",
+    "Message",
+    "MailFlatError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "RateLimitError",
+    "APIError",
+    "OTPTimeoutError",
+    "EncryptedInboxError",
+    "__version__",
+]

mailflat-0.1.0/src/mailflat/client.py

@@ -0,0 +1,159 @@
+"""MailFlat client — /api/v1 otomasyon API'sinin ince, tiplenmiş Python sarmalayıcısı.
+
+Tek hesap API key'i (X-API-Key) ile inbox açar, listeler, mail/OTP okur ve mail gönderir.
+Tüm üst katmanlar (MCP, LangChain) bu client'ı çağırır → tek kaynak.
+
+Connected to:
+  - imports from: mailflat.inbox, mailflat.errors (+ httpx)
+  - imported by:  mailflat.__init__
+
+Key exports:
+  - `MailFlat(api_key=..., base_url=...)` — client
+  - `.create(...) / .create_inbox(...)` — yeni inbox → `Inbox`
+  - `.list()` — `Inbox` listesi
+  - `.inbox(address)` — mevcut adrese bağlan
+"""
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import httpx
+
+from .errors import MailFlatError, raise_for_status
+from .inbox import Inbox
+
+DEFAULT_BASE_URL = "https://mailflat.net"
+_RETRY_STATUSES = {429, 502, 503, 504}
+
+
+class MailFlat:
+    """MailFlat otomasyon API client'ı.
+
+    >>> from mailflat import MailFlat
+    >>> mf = MailFlat(api_key="mf_live_...")
+    >>> inbox = mf.create(label="signup-test")
+    >>> inbox.address
+    'signup-test-...@mailflat.net'
+    >>> otp = inbox.wait_for_otp(timeout=30)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("MAILFLAT_API_KEY")
+        if not api_key:
+            raise MailFlatError(
+                "An API key is required. Pass MailFlat(api_key=...) or set MAILFLAT_API_KEY."
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max(0, max_retries)
+        # http_client enjeksiyonu testleri (httpx.MockTransport) kolaylaştırır.
+        self._http = http_client or httpx.Client(
+            base_url=self.base_url,
+            headers={"X-API-Key": api_key},
+            timeout=timeout,
+        )
+
+    # --------------------------------------------------------------- context
+    def __enter__(self) -> "MailFlat":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # --------------------------------------------------------------- HTTP iç
+    def _request(self, method: str, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        attempt = 0
+        while True:
+            try:
+                resp = self._http.request(method, path, json=json)
+            except httpx.HTTPError as exc:  # ağ/timeout
+                raise MailFlatError(f"Network error: {exc}") from exc
+
+            if resp.status_code in _RETRY_STATUSES and attempt < self.max_retries:
+                attempt += 1
+                time.sleep(min(2 ** attempt * 0.5, 4.0))  # 1s, 2s, ... backoff
+                continue
+
+            try:
+                data = resp.json()
+            except ValueError:
+                data = {}
+
+            if resp.status_code >= 400:
+                detail = ""
+                if isinstance(data, dict):
+                    detail = data.get("detail") or data.get("error") or ""
+                raise_for_status(resp.status_code, detail)
+
+            if isinstance(data, dict) and data.get("error"):  # güvenlik: 200 + error
+                raise MailFlatError(data["error"], status_code=resp.status_code)
+            return data if isinstance(data, dict) else {}
+
+    def _get(self, path: str) -> dict[str, Any]:
+        return self._request("GET", path)
+
+    def _post(self, path: str, json: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", path, json=json)
+
+    def _delete(self, path: str) -> dict[str, Any]:
+        return self._request("DELETE", path)
+
+    # --------------------------------------------------------------- public
+    def create(
+        self,
+        *,
+        prefix: str | None = None,
+        label: str | None = None,
+        subdomain: str | None = None,
+        domain: str | None = None,
+        retention_hours: int | None = None,
+    ) -> Inbox:
+        """Yeni bir disposable inbox açar ve `Inbox` döndürür.
+
+        - prefix: adresin local kısmı (boşsa rastgele `agent-...`)
+        - label: inbox'a verilen isim (UI'da görünür; bazı planlarda yok sayılır)
+        - subdomain: mailflat.net alt alanı (boşsa rastgele)
+        - domain: BYOD doğrulanmış kendi domain'in (örn. acme.com)
+        - retention_hours: mesaj saklama süresi (boş → plan varsayılanı; plan max'ı ile sınırlı)
+        """
+        payload: dict[str, Any] = {}
+        if prefix is not None:
+            payload["prefix"] = prefix
+        if label is not None:
+            payload["label"] = label
+        if subdomain is not None:
+            payload["subdomain"] = subdomain
+        if domain is not None:
+            payload["domain"] = domain
+        if retention_hours is not None:
+            payload["retention_hours"] = retention_hours
+        res = self._post("/api/v1/inboxes", payload)
+        return Inbox(self, res["address"], **{k: v for k, v in res.items() if k != "address"})
+
+    # Landing snippet'leriyle birebir uyum için alias.
+    create_inbox = create
+
+    def list(self) -> list[Inbox]:
+        """Bu API key ile açılmış (agent) inbox'ları döndürür."""
+        res = self._get("/api/v1/inboxes")
+        return [
+            Inbox(self, i["address"], **{k: v for k, v in i.items() if k != "address"})
+            for i in (res.get("inboxes") or [])
+        ]
+
+    def inbox(self, address: str) -> Inbox:
+        """Var olan bir adrese (API çağrısı yapmadan) bağlan."""
+        return Inbox(self, address)

mailflat-0.1.0/src/mailflat/errors.py

@@ -0,0 +1,66 @@
+"""MailFlat SDK hata tipleri — HTTP durum kodlarını anlamlı Python exception'larına çevirir.
+
+Connected to:
+  - imported by:  mailflat.client, mailflat.inbox, mailflat.__init__
+
+Key exports:
+  - `MailFlatError` — tüm SDK hatalarının tabanı
+  - `AuthenticationError` — 401 (geçersiz/eksik API key)
+  - `PermissionError` — 403 (key bu inbox'a sahip değil)
+  - `NotFoundError` — 404
+  - `RateLimitError` — 429
+  - `APIError` — diğer 4xx/5xx
+  - `OTPTimeoutError` — wait_for_otp süre aşımı
+  - `EncryptedInboxError` — E2E inbox içeriği API'den okunamaz
+"""
+from __future__ import annotations
+
+
+class MailFlatError(Exception):
+    """Tüm MailFlat SDK hatalarının tabanı."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+
+class AuthenticationError(MailFlatError):
+    """401 — API key eksik veya geçersiz."""
+
+
+class PermissionError(MailFlatError):  # noqa: A001 - kasıtlı, SDK kapsamında net isim
+    """403 — API key bu inbox'a sahip değil."""
+
+
+class NotFoundError(MailFlatError):
+    """404 — kaynak bulunamadı."""
+
+
+class RateLimitError(MailFlatError):
+    """429 — rate limit aşıldı."""
+
+
+class APIError(MailFlatError):
+    """Beklenmeyen 4xx/5xx yanıtı."""
+
+
+class OTPTimeoutError(MailFlatError):
+    """wait_for_otp verilen süre içinde OTP bulamadı."""
+
+
+class EncryptedInboxError(MailFlatError):
+    """Inbox uçtan uca şifreli — sunucu içeriği okuyamaz, OTP/gövde API'den alınamaz."""
+
+
+def raise_for_status(status_code: int, detail: str) -> None:
+    """HTTP durum kodunu uygun MailFlatError alt tipine çevirip fırlatır."""
+    if status_code == 401:
+        raise AuthenticationError(detail or "Invalid or missing API key", status_code=status_code)
+    if status_code == 403:
+        raise PermissionError(detail or "This API key does not own that inbox", status_code=status_code)
+    if status_code == 404:
+        raise NotFoundError(detail or "Not found", status_code=status_code)
+    if status_code == 429:
+        raise RateLimitError(detail or "Rate limit exceeded", status_code=status_code)
+    raise APIError(detail or f"Request failed with status {status_code}", status_code=status_code)

mailflat-0.1.0/src/mailflat/inbox.py

@@ -0,0 +1,158 @@
+"""Inbox + Message — bir MailFlat inbox'ı ve mesajları üzerindeki yüksek seviye işlemler.
+
+`Inbox`, `MailFlat` client tarafından döndürülür; mesaj okuma, OTP bekleme, gönderme ve
+silme metodlarını taşır. `Message`, /api/v1 e-posta yanıtının tiplenmiş hâlidir.
+
+Connected to:
+  - imports from: mailflat.errors
+  - imported by:  mailflat.client, mailflat.__init__
+
+Key exports:
+  - `Inbox` — `.address`, `.messages()`, `.latest()`, `.wait_for_otp()`, `.send()`, `.delete()`
+  - `Message` — `.otp`, `.subject`, `.text`, `.html`, `.sender`, ...
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from .errors import EncryptedInboxError, OTPTimeoutError
+
+if TYPE_CHECKING:  # döngüsel import'tan kaçın (sadece tip ipucu)
+    from .client import MailFlat
+
+
+@dataclass
+class Message:
+    """Tek bir e-posta — /api/v1 serialize çıktısının tiplenmiş hâli."""
+
+    id: int | None = None
+    sender: str | None = None
+    subject: str | None = None
+    text: str | None = None            # body_text
+    html: str | None = None            # body_html
+    otp: str | None = None             # otp_code (sunucu çıkardıysa)
+    tag: str | None = None
+    to_address: str | None = None
+    is_encrypted: bool = False
+    direction: str | None = None       # "in" | "out"
+    is_read: bool = False
+    send_status: str | None = None
+    send_error: str | None = None
+    received_at: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Message":
+        return cls(
+            id=data.get("id"),
+            sender=data.get("sender"),
+            subject=data.get("subject"),
+            text=data.get("body_text"),
+            html=data.get("body_html"),
+            otp=data.get("otp_code"),
+            tag=data.get("tag"),
+            to_address=data.get("to_address"),
+            is_encrypted=bool(data.get("is_encrypted")),
+            direction=data.get("direction"),
+            is_read=bool(data.get("is_read")),
+            send_status=data.get("send_status"),
+            send_error=data.get("send_error"),
+            received_at=data.get("received_at"),
+            raw=data,
+        )
+
+
+class Inbox:
+    """Tek bir disposable inbox üzerindeki işlemler.
+
+    Doğrudan oluşturmak yerine `MailFlat.create()` / `.list()` / `.inbox(address)` ile alınır.
+    """
+
+    def __init__(self, client: "MailFlat", address: str, **meta: Any) -> None:
+        self._client = client
+        self.address: str = address
+        # create/list yanıtından gelen ek alanlar (varsa)
+        self.name: str | None = meta.get("name")
+        self.retention_hours: int | None = meta.get("retention_hours")
+        self.encrypted: bool = bool(meta.get("encrypted"))
+        self.via_api: bool | None = meta.get("via_api")
+        self.created_at: str | None = meta.get("created_at")
+        self._meta = meta
+
+    def __repr__(self) -> str:
+        return f"<Inbox {self.address!r}>"
+
+    # ----------------------------------------------------------------- okuma
+    def messages(self) -> list[Message]:
+        """Inbox'taki tüm mesajları (yeniden eskiye) döndürür."""
+        res = self._client._get(f"/api/v1/inboxes/{self.address}/messages")
+        return [Message.from_dict(e) for e in (res.get("emails") or [])]
+
+    def latest(self) -> Message | None:
+        """En son mesajı döndürür (yoksa None)."""
+        res = self._client._get(f"/api/v1/inboxes/{self.address}/latest")
+        email = res.get("email")
+        return Message.from_dict(email) if email else None
+
+    def wait_for_message(
+        self, *, timeout: float = 30, poll_interval: float = 1.0
+    ) -> Message:
+        """Yeni bir mesaj gelene kadar poll'lar; gelince `Message` döndürür.
+
+        timeout aşılırsa `OTPTimeoutError`, inbox E2E şifreliyse `EncryptedInboxError`.
+        """
+        deadline = time.monotonic() + max(0.0, timeout)
+        while True:
+            res = self._client._get(f"/api/v1/inboxes/{self.address}/latest")
+            if res.get("encrypted"):
+                raise EncryptedInboxError(
+                    res.get("note") or "This inbox is end-to-end encrypted; "
+                    "use a non-encrypted inbox for agent automation."
+                )
+            email = res.get("email")
+            if email:
+                return Message.from_dict(email)
+            if time.monotonic() >= deadline:
+                raise OTPTimeoutError(
+                    f"No message arrived for {self.address} within {timeout}s"
+                )
+            time.sleep(poll_interval)
+
+    def wait_for_otp(self, *, timeout: float = 30, poll_interval: float = 1.0) -> str:
+        """OTP kodu gelene kadar poll'lar ve kodu (str) döndürür.
+
+        timeout aşılırsa `OTPTimeoutError`, inbox E2E şifreliyse `EncryptedInboxError`.
+        """
+        deadline = time.monotonic() + max(0.0, timeout)
+        while True:
+            res = self._client._get(f"/api/v1/inboxes/{self.address}/latest")
+            if res.get("encrypted"):
+                raise EncryptedInboxError(
+                    res.get("note") or "This inbox is end-to-end encrypted; "
+                    "OTP cannot be read via the API."
+                )
+            email = res.get("email") or {}
+            otp = email.get("otp_code")
+            if otp:
+                return otp
+            if time.monotonic() >= deadline:
+                raise OTPTimeoutError(
+                    f"No OTP arrived for {self.address} within {timeout}s"
+                )
+            time.sleep(poll_interval)
+
+    # ----------------------------------------------------------------- yazma
+    def send(
+        self, to: str, *, subject: str = "", body: str = "", html: str | None = None
+    ) -> dict[str, Any]:
+        """Bu inbox adresinden mail gönderir (DKIM imzalı, kendi MTA'mız üzerinden)."""
+        payload: dict[str, Any] = {"to": to, "subject": subject, "body": body}
+        if html is not None:
+            payload["html"] = html
+        return self._client._post(f"/api/v1/inboxes/{self.address}/send", payload)
+
+    def delete(self) -> dict[str, Any]:
+        """Inbox'u ve tüm mesajlarını siler. Geri alınamaz."""
+        return self._client._delete(f"/api/v1/inboxes/{self.address}")