mailflat 0.3.3__tar.gz → 0.4.0__tar.gz

{mailflat-0.3.3 → mailflat-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailflat
-Version: 0.3.3
+Version: 0.4.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
@@ -85,20 +85,37 @@ for self-hosted / BYOD deployments. Supports use as a context manager (`with Mai
 
 ### `Inbox`
 - `.address` — the email address.
-- `.messages() -> list[Message]` — all messages, newest first.
-- `.latest() -> Message | None` — most recent message.
+- `.messages(*, direction="in") -> list[Message]` — messages, newest first.
+- `.latest(*, direction="in") -> 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.
+- `.wait_for_message(*, timeout=30, poll_interval=1.0, direction="in") -> Message` — poll until a message arrives.
 - `.send(to, *, subject="", body="", html=None) -> dict` — send a DKIM-signed email from this inbox.
+- `.mark_read(message_id) -> dict` — mark a message read so later polls can skip it.
+- `.burn() -> dict` — delete every message but keep the address.
+- `.download_attachment(message_id, attachment_id) -> bytes` — fetch an attachment's bytes.
 - `.delete() -> dict` — delete the inbox and all its messages.
 
+> **Reads return received mail by default.** `direction="out"` returns mail you sent from
+> this address, `"all"` returns both. This matters for agent-to-agent flows: without it,
+> `send()` followed by `wait_for_message()` returns your own outgoing message.
+
 ### `Message`
-`.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`, `.raw`.
+`.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`,
+`.links`, `.attachments`, `.spam`, `.headers`, `.is_read`, `.raw`.
+
+- `.links` — URLs found in the body (HTML hrefs first). For "click the verification link" flows.
+- `.attachments` — metadata; `msg.attachments[0].download()` fetches the bytes.
+- `.spam` — `{score, required, is_spam, rules, scanner}`, or `None` when never scanned
+  (which is not the same as a score of 0).
+- `.headers` — raw headers; `Message-ID` lives here (threading, dedup).
+- `.mark_read()` / `.delete()` — act on this message directly.
 
 ## Errors
 
-All errors subclass `MailFlatError`: `AuthenticationError` (401), `PermissionError` (403),
-`NotFoundError` (404), `RateLimitError` (429), `APIError` (other), `OTPTimeoutError`
+All errors subclass `MailFlatError`: `AuthenticationError` (401), `MailFlatPermissionError` (403,
+still exported as `PermissionError` for compatibility — the new name no longer shadows the built-in),
+`NotFoundError` (404), `RateLimitError` (429, carries `.retry_after` when the server sent one),
+`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).
 

{mailflat-0.3.3 → mailflat-0.4.0}/README.md

@@ -56,20 +56,37 @@ for self-hosted / BYOD deployments. Supports use as a context manager (`with Mai
 
 ### `Inbox`
 - `.address` — the email address.
-- `.messages() -> list[Message]` — all messages, newest first.
-- `.latest() -> Message | None` — most recent message.
+- `.messages(*, direction="in") -> list[Message]` — messages, newest first.
+- `.latest(*, direction="in") -> 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.
+- `.wait_for_message(*, timeout=30, poll_interval=1.0, direction="in") -> Message` — poll until a message arrives.
 - `.send(to, *, subject="", body="", html=None) -> dict` — send a DKIM-signed email from this inbox.
+- `.mark_read(message_id) -> dict` — mark a message read so later polls can skip it.
+- `.burn() -> dict` — delete every message but keep the address.
+- `.download_attachment(message_id, attachment_id) -> bytes` — fetch an attachment's bytes.
 - `.delete() -> dict` — delete the inbox and all its messages.
 
+> **Reads return received mail by default.** `direction="out"` returns mail you sent from
+> this address, `"all"` returns both. This matters for agent-to-agent flows: without it,
+> `send()` followed by `wait_for_message()` returns your own outgoing message.
+
 ### `Message`
-`.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`, `.raw`.
+`.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`,
+`.links`, `.attachments`, `.spam`, `.headers`, `.is_read`, `.raw`.
+
+- `.links` — URLs found in the body (HTML hrefs first). For "click the verification link" flows.
+- `.attachments` — metadata; `msg.attachments[0].download()` fetches the bytes.
+- `.spam` — `{score, required, is_spam, rules, scanner}`, or `None` when never scanned
+  (which is not the same as a score of 0).
+- `.headers` — raw headers; `Message-ID` lives here (threading, dedup).
+- `.mark_read()` / `.delete()` — act on this message directly.
 
 ## Errors
 
-All errors subclass `MailFlatError`: `AuthenticationError` (401), `PermissionError` (403),
-`NotFoundError` (404), `RateLimitError` (429), `APIError` (other), `OTPTimeoutError`
+All errors subclass `MailFlatError`: `AuthenticationError` (401), `MailFlatPermissionError` (403,
+still exported as `PermissionError` for compatibility — the new name no longer shadows the built-in),
+`NotFoundError` (404), `RateLimitError` (429, carries `.retry_after` when the server sent one),
+`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).
 

{mailflat-0.3.3 → mailflat-0.4.0}/src/mailflat/__init__.py

@@ -1,17 +1,19 @@
-"""MailFlat Python SDK — disposable, otomasyon-dostu e-posta inbox'ları için resmi client.
+"""MailFlat Python SDK — the official client for automation-friendly email inboxes.
 
 `pip install mailflat` → `from mailflat import MailFlat`.
 
+NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
+
 Connected to:
   - imports from: mailflat.client, mailflat.inbox, mailflat.errors
-  - imported by:  kullanıcı kodu, mailflat-mcp, mailflat.langchain
+  - imported by:  user code, mailflat-mcp, mailflat.langchain
 
 Key exports:
   - `MailFlat` — client
-  - `Inbox`, `Message` — domain tipleri
-  - hata tipleri: `MailFlatError`, `AuthenticationError`, `PermissionError`,
+  - `Inbox`, `Message`, `Attachment` — domain types
+  - errors: `MailFlatError`, `AuthenticationError`, `MailFlatPermissionError`,
     `NotFoundError`, `RateLimitError`, `APIError`, `OTPTimeoutError`, `EncryptedInboxError`
-  - `redact_secrets()` — ajan araç çıktısından sır alanlarını atar (MCP/LangChain kullanır)
+  - `redact_secrets()` — strips secret fields from agent tool output (used by MCP/LangChain)
 """
 from __future__ import annotations
 
@@ -21,25 +23,28 @@ from .errors import (
     AuthenticationError,
     EncryptedInboxError,
     MailFlatError,
+    MailFlatPermissionError,
     NotFoundError,
     OTPTimeoutError,
     PermissionError,
     RateLimitError,
 )
-from .inbox import Inbox, Message
+from .inbox import Attachment, Inbox, Message
 from .redact import redact_secrets
 
 # Paketin TEK sürüm kaynağı — pyproject.toml bunu [tool.hatch.version] ile okur.
 # Yayın = burayı yükselt, başka hiçbir yeri değil.
-__version__ = "0.3.3"
+__version__ = "0.4.0"
 
 __all__ = [
     "MailFlat",
     "Inbox",
     "Message",
+    "Attachment",
     "MailFlatError",
     "AuthenticationError",
-    "PermissionError",
+    "MailFlatPermissionError",
+    "PermissionError",  # deprecated alias of MailFlatPermissionError
     "NotFoundError",
     "RateLimitError",
     "APIError",

{mailflat-0.3.3 → mailflat-0.4.0}/src/mailflat/client.py

@@ -1,7 +1,9 @@
-"""MailFlat client — /api/v1 otomasyon API'sinin ince, tiplenmiş Python sarmalayıcısı.
+"""MailFlat client — a thin, typed Python wrapper around the /api/v1 automation API.
 
-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.
+One account API key (X-API-Key) creates inboxes, lists them, reads mail/OTP and sends mail.
+Every higher layer (MCP, LangChain) calls this client, so behaviour lives in one place.
+
+NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
 
 Connected to:
   - imports from: mailflat.inbox, mailflat.errors (+ httpx)
@@ -9,12 +11,13 @@ Connected to:
 
 Key exports:
   - `MailFlat(api_key=..., base_url=...)` — client
-  - `.create(...) / .create_inbox(...)` — yeni inbox → `Inbox`
-  - `.list()` — `Inbox` listesi
-  - `.inbox(address)` — mevcut adrese bağlan
+  - `.create(...) / .create_inbox(...)` — new inbox → `Inbox`
+  - `.list()` — list of `Inbox`
+  - `.inbox(address)` — attach to an existing address
 """
 from __future__ import annotations
 
+import logging
 import os
 import time
 from typing import Any
@@ -27,9 +30,34 @@ from .inbox import Inbox
 DEFAULT_BASE_URL = "https://mailflat.net"
 _RETRY_STATUSES = {429, 502, 503, 504}
 
+# Yalnız yan etkisi olmayan (idempotent) metotlar tekrar denenir. POST bilerek YOK:
+# /send'de MTA maili kabul edip ağ geçidi 504 dönerse, retry AYNI MAİLİ İKİNCİ KEZ yollar
+# ve kullanıcı bunu asla fark etmez. Idempotency-Key desteği gelene kadar POST tek atış.
+_IDEMPOTENT_METHODS = {"GET", "HEAD", "DELETE"}
+
+_MAX_BACKOFF = 8.0
+
+logger = logging.getLogger("mailflat")
+
+
+def _retry_after_seconds(resp: httpx.Response) -> float | None:
+    """Parse the `Retry-After` header (seconds form). Returns None when absent/unparsable.
+
+    Bir sunucu "12 saniye bekle" diyorsa 1 saniyede geri dönmek, hem 429'u tekrar yemek
+    hem de rate limit penceresini uzatmak demek.
+    """
+    raw = resp.headers.get("Retry-After")
+    if not raw:
+        return None
+    try:
+        return max(0.0, float(raw.strip()))
+    except (TypeError, ValueError):
+        # HTTP-date biçimi de geçerli ama nadir; tahmin etmektense kendi backoff'umuza düşeriz.
+        return None
+
 
 class MailFlat:
-    """MailFlat otomasyon API client'ı.
+    """MailFlat automation API client.
 
     >>> from mailflat import MailFlat
     >>> mf = MailFlat(api_key="mf_live_...")
@@ -59,10 +87,21 @@ class MailFlat:
         # 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},
+            headers={"X-API-Key": api_key, "User-Agent": self.user_agent()},
             timeout=timeout,
         )
 
+    @staticmethod
+    def user_agent() -> str:
+        """Return the `User-Agent` this client sends, e.g. `mailflat-python/0.4.0`.
+
+        Sunucu tarafında hangi SDK sürümünün sorun çıkardığını görebilmek için; sürüm
+        döngüsel import'a girmeden okunur.
+        """
+        from . import __version__
+
+        return f"mailflat-python/{__version__}"
+
     # --------------------------------------------------------------- context
     def __enter__(self) -> "MailFlat":
         return self
@@ -82,9 +121,19 @@ class MailFlat:
             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:
+            retry_after = _retry_after_seconds(resp)
+            retriable = (
+                resp.status_code in _RETRY_STATUSES
+                and method.upper() in _IDEMPOTENT_METHODS
+                and attempt < self.max_retries
+            )
+            if retriable:
                 attempt += 1
-                time.sleep(min(2 ** attempt * 0.5, 4.0))  # 1s, 2s, ... backoff
+                delay = retry_after if retry_after is not None else min(2 ** attempt * 0.5, _MAX_BACKOFF)
+                delay = min(delay, _MAX_BACKOFF)
+                logger.debug("retrying %s %s after %s (status %s, attempt %s/%s)",
+                             method, path, delay, resp.status_code, attempt, self.max_retries)
+                time.sleep(delay)
                 continue
 
             try:
@@ -96,7 +145,8 @@ class MailFlat:
                 detail = ""
                 if isinstance(data, dict):
                     detail = data.get("detail") or data.get("error") or ""
-                raise_for_status(resp.status_code, detail)
+                logger.debug("%s %s failed with %s: %s", method, path, resp.status_code, detail)
+                raise_for_status(resp.status_code, detail, retry_after=retry_after)
 
             if isinstance(data, dict) and data.get("error"):  # güvenlik: 200 + error
                 raise MailFlatError(data["error"], status_code=resp.status_code)
@@ -105,12 +155,29 @@ class MailFlat:
     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 _post(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._request("POST", path, json=json or {})
 
     def _delete(self, path: str) -> dict[str, Any]:
         return self._request("DELETE", path)
 
+    def _get_bytes(self, path: str) -> httpx.Response:
+        """Raw response for binary endpoints (attachment download)."""
+        try:
+            resp = self._http.request("GET", path)
+        except httpx.HTTPError as exc:
+            raise MailFlatError(f"Network error: {exc}") from exc
+        if resp.status_code >= 400:
+            detail = ""
+            try:
+                body = resp.json()
+                if isinstance(body, dict):
+                    detail = body.get("detail") or body.get("error") or ""
+            except ValueError:
+                pass
+            raise_for_status(resp.status_code, detail, retry_after=_retry_after_seconds(resp))
+        return resp
+
     # --------------------------------------------------------------- public
     def create(
         self,
@@ -121,13 +188,13 @@ class MailFlat:
         domain: str | None = None,
         retention_hours: int | None = None,
     ) -> Inbox:
-        """Yeni bir disposable inbox açar ve `Inbox` döndürür.
+        """Create a new inbox and return it as an `Inbox`.
 
-        - 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ı)
+        - prefix: local part of the address (random `agent-...` when omitted)
+        - label: display name shown in the dashboard
+        - subdomain: mailflat.net subdomain (random when omitted)
+        - domain: one of your own verified BYOD domains, e.g. `acme.com`
+        - retention_hours: how long messages are kept (defaults to your plan, capped by it)
         """
         payload: dict[str, Any] = {}
         if prefix is not None:
@@ -147,7 +214,7 @@ class MailFlat:
     create_inbox = create
 
     def list(self) -> list[Inbox]:
-        """Bu API key ile açılmış (agent) inbox'ları döndürür."""
+        """Return the inboxes created with this API key."""
         res = self._get("/api/v1/inboxes")
         return [
             Inbox(self, i["address"], **{k: v for k, v in i.items() if k != "address"})
@@ -155,5 +222,5 @@ class MailFlat:
         ]
 
     def inbox(self, address: str) -> Inbox:
-        """Var olan bir adrese (API çağrısı yapmadan) bağlan."""
+        """Attach to an existing address without making an API call."""
         return Inbox(self, address)

mailflat-0.4.0/src/mailflat/errors.py

@@ -0,0 +1,87 @@
+"""MailFlat SDK error types — maps HTTP status codes to meaningful Python exceptions.
+
+NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
+Burada docstring bir yorum değil, kullanıcının `help()` ve IDE tooltip'inde gördüğü arayüzdür.
+
+Connected to:
+  - imported by:  mailflat.client, mailflat.inbox, mailflat.__init__
+
+Key exports:
+  - `MailFlatError` — base class for every SDK error
+  - `AuthenticationError` — 401 (missing/invalid API key)
+  - `MailFlatPermissionError` — 403 (key does not own this inbox)
+  - `NotFoundError` — 404
+  - `RateLimitError` — 429 (carries `retry_after` when the server sent it)
+  - `APIError` — any other 4xx/5xx
+  - `OTPTimeoutError` — wait_for_otp / wait_for_message timed out
+  - `EncryptedInboxError` — end-to-end encrypted inbox cannot be read through the API
+"""
+from __future__ import annotations
+
+
+class MailFlatError(Exception):
+    """Base class for every MailFlat SDK error."""
+
+    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 — the API key is missing or invalid."""
+
+
+class MailFlatPermissionError(MailFlatError):
+    """403 — this API key does not own that inbox."""
+
+
+# Geriye dönük uyumluluk: 0.3.3'e kadar bu sınıfın adı `PermissionError` idi ve built-in'i
+# GÖLGELİYORDU. `except PermissionError` yazan kullanıcı, SDK'yı import etmemiş bir modülde
+# built-in'i yakalayıp bizimkini kaçırabilir (ya da tersi) — sessiz ve teşhisi zor bir hata.
+# Eski adı alias olarak bırakıyoruz ki mevcut kod kırılmasın.
+PermissionError = MailFlatPermissionError  # noqa: A001 - deprecated alias, kept for compatibility
+
+
+class NotFoundError(MailFlatError):
+    """404 — the resource does not exist."""
+
+
+class RateLimitError(MailFlatError):
+    """429 — rate limit exceeded.
+
+    `retry_after` holds the server's `Retry-After` value in seconds when it sent one,
+    so callers can wait exactly as long as the server asked instead of guessing.
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None,
+                 retry_after: float | None = None) -> None:
+        super().__init__(message, status_code=status_code)
+        self.retry_after = retry_after
+
+
+class APIError(MailFlatError):
+    """An unexpected 4xx/5xx response."""
+
+
+class OTPTimeoutError(MailFlatError):
+    """No OTP (or message) arrived before the timeout elapsed."""
+
+
+class EncryptedInboxError(MailFlatError):
+    """The inbox is end-to-end encrypted, so the server cannot read its contents."""
+
+
+def raise_for_status(status_code: int, detail: str, *, retry_after: float | None = None) -> None:
+    """Raise the matching `MailFlatError` subclass for an HTTP status code."""
+    if status_code == 401:
+        raise AuthenticationError(detail or "Invalid or missing API key", status_code=status_code)
+    if status_code == 403:
+        raise MailFlatPermissionError(
+            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,
+                             retry_after=retry_after)
+    raise APIError(detail or f"Request failed with status {status_code}", status_code=status_code)

mailflat-0.4.0/src/mailflat/inbox.py

@@ -0,0 +1,321 @@
+"""Inbox + Message — high-level operations on one MailFlat inbox and its messages.
+
+`Inbox` is returned by the `MailFlat` client and carries the read, wait, send and delete
+methods. `Message` is the typed form of an /api/v1 email payload.
+
+NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
+
+Connected to:
+  - imports from: mailflat.errors
+  - imported by:  mailflat.client, mailflat.__init__
+
+Key exports:
+  - `Inbox` — `.address`, `.messages()`, `.latest()`, `.wait_for_message()`,
+    `.wait_for_otp()`, `.send()`, `.mark_read()`, `.burn()`, `.download_attachment()`
+  - `Message` — `.otp`, `.subject`, `.text`, `.html`, `.links`, `.attachments`, `.spam`, ...
+  - `Attachment` — `.filename`, `.size_bytes`, `.download()`
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from .errors import EncryptedInboxError, MailFlatError, OTPTimeoutError
+
+if TYPE_CHECKING:  # döngüsel import'tan kaçın (sadece tip ipucu)
+    from .client import MailFlat
+
+# Sunucunun kabul ettiği yön filtreleri. "in" varsayılan: bir ajan için "mesaj geldi mi"
+# sorusuna kendi gönderdiği mail cevap olamaz.
+DIRECTIONS = ("in", "out", "all")
+
+
+def _check_direction(direction: str) -> str:
+    if direction not in DIRECTIONS:
+        raise ValueError(f"direction must be one of {DIRECTIONS!r}, got {direction!r}")
+    return direction
+
+
+@dataclass
+class Attachment:
+    """Attachment metadata. The bytes are fetched on demand with `.download()`.
+
+    İçerik listede GELMEZ: tek ekli 5 MB'lık bir mail, mesaj listesini kullanılamaz yapardı.
+    """
+
+    id: int | None = None
+    filename: str | None = None
+    content_type: str | None = None
+    size_bytes: int | None = None
+    is_encrypted: bool = False
+    truncated: bool = False  # True → file exceeded the storage cap; bytes were never stored
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+    _message: "Message | None" = field(default=None, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Attachment":
+        return cls(
+            id=data.get("id"),
+            filename=data.get("filename"),
+            content_type=data.get("content_type"),
+            size_bytes=data.get("size_bytes"),
+            is_encrypted=bool(data.get("is_encrypted")),
+            truncated=bool(data.get("truncated")),
+            raw=data,
+        )
+
+    def download(self) -> bytes:
+        """Download this attachment's bytes.
+
+        Raises `MailFlatError` when the attachment is not attached to a message, when the
+        file was too large to store (`truncated`), or when the inbox is end-to-end encrypted
+        (the server cannot decrypt it).
+        """
+        if self._message is None or self._message._inbox is None or self.id is None:
+            raise MailFlatError(
+                "This attachment isn't attached to a message. "
+                "Use inbox.download_attachment(message_id, attachment_id) instead."
+            )
+        if self.truncated:
+            raise MailFlatError(f"Attachment {self.filename!r} was too large to store")
+        return self._message._inbox.download_attachment(self._message.id, self.id)
+
+
+@dataclass
+class Message:
+    """A single email — the typed form of the /api/v1 payload."""
+
+    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 (when the server extracted one)
+    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
+    # URLs found in the body (HTML hrefs first, then plain text). Verification-link flows
+    # read this instead of parsing the body themselves.
+    links: list[str] = field(default_factory=list)
+    attachments: list[Attachment] = field(default_factory=list)
+    # {score, required, is_spam, rules, scanner} — None means NOT SCANNED, which is not
+    # the same as a score of 0.0.
+    spam: dict[str, Any] | None = None
+    # Raw message headers (Message-ID lives here — needed for threading and dedup).
+    # None on encrypted inboxes: headers carry the Subject, so they go inside the envelope.
+    headers: dict[str, Any] | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+    # Bu mesajı döndüren Inbox (msg.delete() şekeri için). Inbox.messages()/latest()/wait_* doldurur.
+    _inbox: "Inbox | None" = field(default=None, repr=False, compare=False)
+
+    def delete(self) -> dict[str, Any]:
+        """Delete this message (the inbox itself stays)."""
+        if self._inbox is None or self.id is None:
+            raise ValueError(
+                "This message isn't attached to an inbox (or has no id). "
+                "Use inbox.delete_message(message_id) instead."
+            )
+        return self._inbox.delete_message(self.id)
+
+    def mark_read(self) -> dict[str, Any]:
+        """Mark this message as read, so the next poll can skip it."""
+        if self._inbox is None or self.id is None:
+            raise ValueError(
+                "This message isn't attached to an inbox (or has no id). "
+                "Use inbox.mark_read(message_id) instead."
+            )
+        return self._inbox.mark_read(self.id)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Message":
+        msg = 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"),
+            links=list(data.get("links") or []),
+            spam=data.get("spam"),
+            headers=data.get("headers"),
+            raw=data,
+        )
+        msg.attachments = [Attachment.from_dict(a) for a in (data.get("attachments") or [])]
+        for att in msg.attachments:
+            att._message = msg
+        return msg
+
+
+class Inbox:
+    """Operations on a single MailFlat inbox.
+
+    Obtained from `MailFlat.create()` / `.list()` / `.inbox(address)` rather than
+    constructed directly.
+    """
+
+    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.api_key: str | None = meta.get("api_key")  # per-inbox key (mf_sk_...)
+        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")
+        # backend yanıtının tamamı (Message.raw ile simetrik) — MCP/agent katmanı için.
+        self.raw: dict[str, Any] = {"address": address, **meta}
+
+    def __repr__(self) -> str:
+        return f"<Inbox {self.address!r}>"
+
+    # ----------------------------------------------------------------- okuma
+    def _wrap(self, data: dict[str, Any]) -> Message:
+        """API mail dict'ini Message'a çevirir + bu inbox ref'ini iliştirir (msg.delete() için)."""
+        m = Message.from_dict(data)
+        m._inbox = self
+        return m
+
+    def messages(self, *, direction: str = "in") -> list[Message]:
+        """Return this inbox's messages, newest first.
+
+        `direction` defaults to `"in"`: received mail only. Pass `"out"` for mail you sent
+        from this address, or `"all"` for both.
+        """
+        _check_direction(direction)
+        res = self._client._get(
+            f"/api/v1/inboxes/{self.address}/messages?direction={direction}")
+        return [self._wrap(e) for e in (res.get("emails") or [])]
+
+    def latest(self, *, direction: str = "in") -> Message | None:
+        """Return the most recent message, or None when the inbox is empty.
+
+        Defaults to received mail. Before 0.4.0 this also returned mail you had just sent,
+        which made `send()` followed by `wait_for_message()` return your own message.
+        """
+        _check_direction(direction)
+        res = self._client._get(
+            f"/api/v1/inboxes/{self.address}/latest?direction={direction}")
+        email = res.get("email")
+        return self._wrap(email) if email else None
+
+    def wait_for_message(
+        self, *, timeout: float = 30, poll_interval: float = 1.0, direction: str = "in"
+    ) -> Message:
+        """Poll until a message arrives and return it.
+
+        Only received mail counts by default, so an agent can `send()` to a peer and then
+        wait for the reply without immediately matching its own outgoing message.
+
+        Raises `OTPTimeoutError` on timeout, `EncryptedInboxError` on an E2E inbox.
+        """
+        _check_direction(direction)
+        deadline = time.monotonic() + max(0.0, timeout)
+        while True:
+            res = self._client._get(
+                f"/api/v1/inboxes/{self.address}/latest?direction={direction}")
+            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 self._wrap(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:
+        """Poll until an OTP arrives and return the code.
+
+        Raises `OTPTimeoutError` on timeout, `EncryptedInboxError` on an E2E inbox.
+        """
+        deadline = time.monotonic() + max(0.0, timeout)
+        while True:
+            res = self._client._get(f"/api/v1/inboxes/{self.address}/latest?direction=in")
+            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)
+
+    def download_attachment(self, message_id: int, attachment_id: int) -> bytes:
+        """Download one attachment's bytes.
+
+        Metadata already ships with each message (`msg.attachments`); this fetches the file
+        itself. Prefer `msg.attachments[0].download()`.
+        """
+        resp = self._client._get_bytes(
+            f"/api/v1/inboxes/{self.address}/messages/{message_id}/attachments/{attachment_id}"
+        )
+        ctype = resp.headers.get("content-type", "")
+        if ctype.startswith("application/json"):
+            # Şifreli kutuda sunucu çözemez → zarf JSON'u döner, baytları değil.
+            raise EncryptedInboxError(
+                "This inbox is end-to-end encrypted; the server cannot decrypt this attachment."
+            )
+        return resp.content
+
+    # ----------------------------------------------------------------- yazma
+    def send(
+        self, to: str, *, subject: str = "", body: str = "", html: str | None = None
+    ) -> dict[str, Any]:
+        """Send mail from this inbox's address (DKIM-signed, through our own MTA).
+
+        Not retried on gateway errors: a retried send can deliver the same mail twice.
+        """
+        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 mark_read(self, message_id: int) -> dict[str, Any]:
+        """Mark one message as read.
+
+        Lets an agent poll for *new* mail instead of re-reading the whole inbox and
+        tracking state on its own.
+        """
+        return self._client._post(
+            f"/api/v1/inboxes/{self.address}/messages/{message_id}/read")
+
+    def burn(self) -> dict[str, Any]:
+        """Delete every message in this inbox and keep the address.
+
+        Useful between test scenarios: the address stays registered wherever you used it.
+        """
+        return self._client._post(f"/api/v1/inboxes/{self.address}/burn")
+
+    def delete(self) -> dict[str, Any]:
+        """Delete this inbox and all of its messages. Cannot be undone."""
+        return self._client._delete(f"/api/v1/inboxes/{self.address}")
+
+    def delete_message(self, message_id: int) -> dict[str, Any]:
+        """Delete a single message; the inbox stays. Backs `Message.delete()`."""
+        return self._client._delete(
+            f"/api/v1/inboxes/{self.address}/messages/{message_id}")

{mailflat-0.3.3 → mailflat-0.4.0}/src/mailflat/langchain.py

@@ -1,20 +1,23 @@
-"""MailFlat LangChain entegrasyonu — `MailFlatToolkit` + 6 araçlık LangChain tool seti.
+"""MailFlat LangChain integration — `MailFlatToolkit` plus a 9-tool LangChain tool set.
 
-`mailflat` SDK'sının üstüne ince bir LangChain kabuğu; tüm HTTP/iş mantığı client'ta (DRY).
-`langchain-core` opsiyonel bağımlılıktır → `pip install mailflat[langchain]`.
+A thin LangChain shell over the `mailflat` SDK; all HTTP and behaviour live in the client.
+`langchain-core` is an optional dependency → `pip install mailflat[langchain]`.
 
-Kullanım:
+NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
+
+Usage:
     from mailflat.langchain import MailFlatToolkit
     toolkit = MailFlatToolkit(api_key=env("MAILFLAT_KEY"))
-    tools = toolkit.get_tools()   # create_inbox, list_inboxes, read_messages,
-                                  # wait_for_otp, send_email, delete_inbox
+    tools = toolkit.get_tools()   # create_inbox, list_inboxes, read_messages, wait_for_otp,
+                                  # wait_for_message, send_email, mark_read, burn_inbox,
+                                  # delete_inbox  (delete_message bilerek YOK)
 
 ⚠️ Araç çıktıları `redact_secrets()`'ten geçer: per-inbox `api_key` modelin bağlamına
 (ve oradan LangSmith trace'lerine) girmemeli — bkz. B-055.
 
 Connected to:
   - imports from: mailflat.client (MailFlat), mailflat.redact, langchain_core.tools
-  - imported by:  kullanıcı kodu (LangChain ajanları)
+  - imported by:  user code (LangChain agents)
 
 Key exports:
   - `MailFlatToolkit(api_key=..., base_url=...)` — `.get_tools()` → list[BaseTool]
@@ -40,7 +43,7 @@ if TYPE_CHECKING:
 
 
 class MailFlatToolkit:
-    """MailFlat araçlarını bir LangChain ajanına bağlamak için toolkit.
+    """Toolkit that plugs MailFlat's tools into a LangChain agent.
 
     >>> from mailflat.langchain import MailFlatToolkit
     >>> toolkit = MailFlatToolkit(api_key="mf_live_...")
@@ -59,7 +62,7 @@ class MailFlatToolkit:
 
     # ------------------------------------------------------------------ tools
     def get_tools(self) -> "Sequence[BaseTool]":
-        """6 MailFlat aracını LangChain `BaseTool` listesi olarak döndürür."""
+        """Return every MailFlat tool as a list of LangChain `BaseTool`s."""
         client = self._client
 
         def create_inbox(prefix: str = "", label: str = "", retention_hours: int = 0) -> dict:
@@ -88,14 +91,19 @@ class MailFlatToolkit:
             except MailFlatError as e:
                 return {"error": str(e)}
 
-        def read_messages(address: str) -> dict:
-            """Read all messages in the given inbox address (newest first).
+        def read_messages(address: str, direction: str = "in") -> dict:
+            """Read messages in the given inbox address (newest first).
 
             Args:
                 address: The full inbox address, e.g. signup-8f3@mailflat.net.
+                direction: 'in' for received mail (default), 'out' for mail you sent from
+                    this address, 'all' for both.
             """
             try:
-                return redact_secrets({"ok": True, "emails": [m.raw for m in client.inbox(address).messages()]})
+                msgs = client.inbox(address).messages(direction=direction)
+                return redact_secrets({"ok": True, "emails": [m.raw for m in msgs]})
+            except ValueError as e:      # geçersiz direction — ağa çıkmadan
+                return {"error": str(e)}
             except MailFlatError as e:
                 return {"error": str(e)}
 
@@ -118,6 +126,26 @@ class MailFlatToolkit:
             except MailFlatError as e:
                 return {"otp_code": None, "error": str(e)}
 
+        def wait_for_message(address: str, timeout: int = 30) -> dict:
+            """Poll the inbox until a NEW message arrives, then return it.
+
+            Only received mail counts, so you can send to a peer and wait for their reply
+            without matching your own outgoing message.
+
+            Args:
+                address: The inbox address to poll.
+                timeout: Maximum seconds to wait before giving up (default 30).
+            """
+            try:
+                msg = client.inbox(address).wait_for_message(timeout=timeout)
+                return redact_secrets({"ok": True, "email": msg.raw})
+            except OTPTimeoutError:
+                return {"email": None, "error": "timeout"}
+            except EncryptedInboxError as e:
+                return {"email": None, "encrypted": True, "error": str(e)}
+            except MailFlatError as e:
+                return {"email": None, "error": str(e)}
+
         def send_email(
             address: str, to: str, subject: str = "", body: str = "", html: str = ""
         ) -> dict:
@@ -135,6 +163,32 @@ class MailFlatToolkit:
             except MailFlatError as e:
                 return {"error": str(e)}
 
+        def mark_read(address: str, message_id: int) -> dict:
+            """Mark one message as read so later polls can skip it.
+
+            Args:
+                address: The inbox address that holds the message.
+                message_id: The message id, as returned by read_messages.
+            """
+            try:
+                return redact_secrets(client.inbox(address).mark_read(message_id))
+            except MailFlatError as e:
+                return {"error": str(e)}
+
+        def burn_inbox(address: str) -> dict:
+            """Delete every message in an inbox but keep the address itself.
+
+            Use this to start a clean scenario without losing the address you already
+            registered somewhere.
+
+            Args:
+                address: The inbox address to empty.
+            """
+            try:
+                return redact_secrets(client.inbox(address).burn())
+            except MailFlatError as e:
+                return {"error": str(e)}
+
         def delete_inbox(address: str) -> dict:
             """Delete an inbox and all its messages by address. Irreversible.
 
@@ -151,7 +205,10 @@ class MailFlatToolkit:
             list_inboxes,
             read_messages,
             wait_for_otp,
+            wait_for_message,
             send_email,
+            mark_read,
+            burn_inbox,
             delete_inbox,
         ]
         # from_function tip ipuçları + docstring'den args_schema'yı kendisi çıkarır

{mailflat-0.3.3 → mailflat-0.4.0}/src/mailflat/redact.py

@@ -1,4 +1,4 @@
-"""Ajan araçlarının çıktısından sır alanlarını temizler (B-055).
+"""Strips secret fields from agent tool output (B-055).
 
 Neden var: `create_inbox` ve `list_inboxes` backend yanıtını olduğu gibi döndürüyordu ve o
 yanıtta per-inbox `api_key` (`mf_sk_…`) vardı. Araç çıktısı **model bağlamına** giriyor;
@@ -14,13 +14,17 @@ Yöntem **isim bazlı**, değer bazlı değil: mesaj gövdesini tarayıp `mf_` i
 string'leri silmek, kullanıcının kendi test anahtarını konu ettiği bir maili bozardı. Alan
 adına bakmak hem kesin hem zararsız.
 
+NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
+
 Connected to:
   - imports from: —
-  - imported by:  mailflat_mcp.server, mailflat.langchain, testler
+  - imported by:  mailflat.langchain, mailflat's own tests. AYRICA repo içinde
+    `packages/mcp` (mailflat-mcp, ayrı PyPI paketi) buradan import eder — bu paketin
+    kendi içinde MCP yoktur, o yüzden referans repo düzeyindedir.
 
 Key exports:
-  - `redact_secrets(value)` — dict/list içindeki sır alanlarını atmış kopya
-  - `SECRET_NAME_PARTS` — hangi alan adlarının sır sayıldığı
+  - `redact_secrets(value)` — copy of the input with secret fields removed
+  - `SECRET_NAME_PARTS` — which field names count as secrets
 """
 from __future__ import annotations
 
@@ -43,11 +47,11 @@ def _is_secret(key: Any) -> bool:
 
 
 def redact_secrets(value: Any) -> Any:
-    """`value`'nun sır alanları çıkarılmış kopyasını döndür (girdi değiştirilmez).
+    """Return a copy of `value` with secret fields removed. The input is not modified.
 
-    dict → sır alanları atılır, kalanlar özyinelemeli temizlenir
-    list/tuple → her eleman temizlenir (liste olarak döner, JSON'a zaten liste gidiyor)
-    diğer → olduğu gibi
+    dict → secret keys dropped, remaining values cleaned recursively
+    list/tuple → every element cleaned (returned as a list; JSON carries a list anyway)
+    anything else → returned unchanged
     """
     if isinstance(value, dict):
         return {k: redact_secrets(v) for k, v in value.items() if not _is_secret(k)}

mailflat-0.3.3/src/mailflat/errors.py

@@ -1,66 +0,0 @@
-"""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.3.3/src/mailflat/inbox.py

@@ -1,181 +0,0 @@
-"""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)
-    # Bu mesajı döndüren Inbox (msg.delete() şekeri için). Inbox.messages()/latest()/wait_* doldurur.
-    _inbox: "Inbox | None" = field(default=None, repr=False, compare=False)
-
-    def delete(self) -> dict[str, Any]:
-        """Bu maili sil (inbox kalır). Mesaj bir Inbox'tan geldiyse çalışır."""
-        if self._inbox is None or self.id is None:
-            raise ValueError(
-                "This message isn't attached to an inbox (or has no id). "
-                "Use inbox.delete_message(message_id) instead."
-            )
-        return self._inbox.delete_message(self.id)
-
-    @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.api_key: str | None = meta.get("api_key")  # per-inbox key (mf_sk_...)
-        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")
-        # backend yanıtının tamamı (Message.raw ile simetrik) — MCP/agent katmanı için.
-        self.raw: dict[str, Any] = {"address": address, **meta}
-
-    def __repr__(self) -> str:
-        return f"<Inbox {self.address!r}>"
-
-    # ----------------------------------------------------------------- okuma
-    def _wrap(self, data: dict[str, Any]) -> Message:
-        """API mail dict'ini Message'a çevirir + bu inbox ref'ini iliştirir (msg.delete() için)."""
-        m = Message.from_dict(data)
-        m._inbox = self
-        return m
-
-    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 [self._wrap(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 self._wrap(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 self._wrap(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}")
-
-    def delete_message(self, message_id: int) -> dict[str, Any]:
-        """Inbox'taki TEK bir maili siler (inbox kalır). `Message.delete()` bunu çağırır."""
-        return self._client._delete(f"/api/v1/inboxes/{self.address}/messages/{message_id}")