temptf 0.1.0__tar.gz

temptf-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+build/
+dist/
+*.egg-info/
+.eggs/
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+.venv/
+venv/
+ENV/
+.env

temptf-0.1.0/LICENSE

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

temptf-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: temptf
+Version: 0.1.0
+Summary: Python client for the temp.tf disposable email API
+Project-URL: Homepage, https://github.com/patrikdzejn88-ux/temptf
+Project-URL: Repository, https://github.com/patrikdzejn88-ux/temptf
+Project-URL: Issues, https://github.com/patrikdzejn88-ux/temptf/issues
+Author: Liaksol
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,disposable-email,inbox,temp-tf,tempmail
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# temptf
+
+Python client library for the [temp.tf](https://temp.tf/) disposable email API. Zero external dependencies.
+
+## Installation
+
+```bash
+pip install git+https://github.com/patrikdzejn88-ux/temptf.git
+```
+
+Or install locally from source:
+
+```bash
+git clone https://github.com/patrikdzejn88-ux/temptf.git
+cd temptf
+pip install .
+```
+
+## Quick Start
+
+### Creating Addresses by Provider
+
+```python
+import temptf
+
+# Random address across all providers
+email = temptf.create_email()
+
+# Provider-specific addresses
+gmail_any = temptf.create_gmail()          # @gmail.com (dot or plus)
+gmail_dot = temptf.create_gmail_dot()      # u.s.e.r@gmail.com
+gmail_plus = temptf.create_gmail_plus()    # user+tag@gmail.com
+outlook = temptf.create_outlook()          # user+tag@outlook.com
+hotmail = temptf.create_hotmail()          # user+tag@hotmail.com
+edu = temptf.create_edu()                  # @high.edu.pl
+```
+
+### Reading and Streaming Messages
+
+```python
+import temptf
+
+email = temptf.create_outlook()
+print("Listening on:", email)
+
+# Fetch current inbox contents once
+messages = temptf.get_messages(email)
+
+# Block until the first matching message arrives
+msg = temptf.wait_for_message(email, timeout=60.0)
+print(msg.subject, msg.text)
+
+# Stream incoming messages continuously
+for msg in temptf.stream_messages(email, interval=5.0):
+    print(f"[{msg.date}] {msg.sender}: {msg.subject}")
+    print(msg.text)
+```
+
+### Using `TempTFClient` Directly
+
+```python
+from temptf import TempTFClient
+
+client = TempTFClient(timeout=10.0)
+email = client.create_gmail_plus()
+
+for msg in client.stream_messages(email):
+    for att in msg.attachments:
+        client.download_attachment(email, msg.id, att.id, dest=f"./downloads/{att.name}")
+```
+
+## License
+
+MIT

temptf-0.1.0/README.md

@@ -0,0 +1,74 @@
+# temptf
+
+Python client library for the [temp.tf](https://temp.tf/) disposable email API. Zero external dependencies.
+
+## Installation
+
+```bash
+pip install git+https://github.com/patrikdzejn88-ux/temptf.git
+```
+
+Or install locally from source:
+
+```bash
+git clone https://github.com/patrikdzejn88-ux/temptf.git
+cd temptf
+pip install .
+```
+
+## Quick Start
+
+### Creating Addresses by Provider
+
+```python
+import temptf
+
+# Random address across all providers
+email = temptf.create_email()
+
+# Provider-specific addresses
+gmail_any = temptf.create_gmail()          # @gmail.com (dot or plus)
+gmail_dot = temptf.create_gmail_dot()      # u.s.e.r@gmail.com
+gmail_plus = temptf.create_gmail_plus()    # user+tag@gmail.com
+outlook = temptf.create_outlook()          # user+tag@outlook.com
+hotmail = temptf.create_hotmail()          # user+tag@hotmail.com
+edu = temptf.create_edu()                  # @high.edu.pl
+```
+
+### Reading and Streaming Messages
+
+```python
+import temptf
+
+email = temptf.create_outlook()
+print("Listening on:", email)
+
+# Fetch current inbox contents once
+messages = temptf.get_messages(email)
+
+# Block until the first matching message arrives
+msg = temptf.wait_for_message(email, timeout=60.0)
+print(msg.subject, msg.text)
+
+# Stream incoming messages continuously
+for msg in temptf.stream_messages(email, interval=5.0):
+    print(f"[{msg.date}] {msg.sender}: {msg.subject}")
+    print(msg.text)
+```
+
+### Using `TempTFClient` Directly
+
+```python
+from temptf import TempTFClient
+
+client = TempTFClient(timeout=10.0)
+email = client.create_gmail_plus()
+
+for msg in client.stream_messages(email):
+    for att in msg.attachments:
+        client.download_attachment(email, msg.id, att.id, dest=f"./downloads/{att.name}")
+```
+
+## License
+
+MIT

temptf-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "temptf"
+version = "0.1.0"
+description = "Python client for the temp.tf disposable email API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+    { name = "Liaksol" },
+]
+keywords = ["tempmail", "disposable-email", "temp-tf", "inbox", "api-client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Email",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/patrikdzejn88-ux/temptf"
+Repository = "https://github.com/patrikdzejn88-ux/temptf"
+Issues = "https://github.com/patrikdzejn88-ux/temptf/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.3.0",
+    "mypy>=1.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/temptf"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

temptf-0.1.0/src/temptf/__init__.py

@@ -0,0 +1,121 @@
+from typing import Callable, Iterator, List, Optional, Sequence, Union
+
+from .client import PROVIDERS, TempTFClient
+from .exceptions import APIError, RateLimitError, TempTFError
+from .models import Attachment, Message, Stats
+
+__version__ = "0.1.0"
+
+_default_client: Optional[TempTFClient] = None
+
+
+def _get_client() -> TempTFClient:
+    global _default_client
+    if _default_client is None:
+        _default_client = TempTFClient()
+    return _default_client
+
+
+def create_email(
+    providers: Optional[Union[str, Sequence[str]]] = None,
+    dot: bool = True,
+    plus: bool = True,
+) -> str:
+    """Generate a random temporary email address."""
+    return _get_client().create_email(providers=providers, dot=dot, plus=plus)
+
+
+def create_gmail(dot: bool = True, plus: bool = True) -> str:
+    """Generate a @gmail.com address using dot syntax, plus alias, or both."""
+    return _get_client().create_gmail(dot=dot, plus=plus)
+
+
+def create_gmail_dot() -> str:
+    """Generate a @gmail.com dot-variant address."""
+    return _get_client().create_gmail_dot()
+
+
+def create_gmail_plus() -> str:
+    """Generate a @gmail.com plus-alias address."""
+    return _get_client().create_gmail_plus()
+
+
+def create_outlook() -> str:
+    """Generate an @outlook.com address."""
+    return _get_client().create_outlook()
+
+
+def create_hotmail() -> str:
+    """Generate a @hotmail.com address."""
+    return _get_client().create_hotmail()
+
+
+def create_edu() -> str:
+    """Generate a @high.edu.pl address."""
+    return _get_client().create_edu()
+
+
+def get_messages(email: str) -> List[Message]:
+    """Fetch all messages in the inbox for the given address."""
+    return _get_client().get_messages(email)
+
+
+def wait_for_message(
+    email: str,
+    timeout: float = 120.0,
+    interval: float = 4.0,
+    predicate: Optional[Callable[[Message], bool]] = None,
+) -> Message:
+    """Poll the inbox until a message arrives or timeout expires."""
+    return _get_client().wait_for_message(
+        email=email,
+        timeout=timeout,
+        interval=interval,
+        predicate=predicate,
+    )
+
+
+def stream_messages(
+    email: str,
+    interval: float = 5.0,
+    skip_existing: bool = False,
+) -> Iterator[Message]:
+    """Yield new messages for the given address as they arrive."""
+    return _get_client().stream_messages(
+        email=email,
+        interval=interval,
+        skip_existing=skip_existing,
+    )
+
+
+def get_stats(
+    providers: Optional[Union[str, Sequence[str]]] = None,
+    dot: bool = True,
+    plus: bool = True,
+) -> Stats:
+    """Return pool availability and message statistics."""
+    return _get_client().get_stats(providers=providers, dot=dot, plus=plus)
+
+
+__all__ = [
+    "__version__",
+    "PROVIDERS",
+    "TempTFClient",
+    "TempTFError",
+    "APIError",
+    "RateLimitError",
+    "Message",
+    "Attachment",
+    "Stats",
+    "create_email",
+    "create_gmail",
+    "create_gmail_dot",
+    "create_gmail_plus",
+    "create_outlook",
+    "create_hotmail",
+    "create_edu",
+    "get_messages",
+    "wait_for_message",
+    "stream_messages",
+    "get_stats",
+]

temptf-0.1.0/src/temptf/client.py

@@ -0,0 +1,225 @@
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterator, List, Optional, Sequence, Set, Tuple, Union
+
+from .exceptions import APIError, RateLimitError, TempTFError
+from .models import Message, Stats
+
+BASE_URL = "https://temp.tf/api"
+PROVIDERS = ("gmail", "outlook", "hotmail", "high.edu.pl")
+
+
+class TempTFClient:
+    """Client for the temp.tf disposable email API."""
+
+    def __init__(
+        self,
+        base_url: str = BASE_URL,
+        timeout: float = 15.0,
+        auto_retry_rate_limit: bool = True,
+        user_agent: str = "temptf-python/0.1.0",
+        opener: Optional[urllib.request.OpenerDirector] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.auto_retry_rate_limit = auto_retry_rate_limit
+        self.user_agent = user_agent
+        self._opener = opener or urllib.request.build_opener()
+
+    def _request_raw(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, str]] = None,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[bytes, Dict[str, str]]:
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+        if params:
+            query = urllib.parse.urlencode(params)
+            url = f"{url}?{query}"
+
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        data: Optional[bytes] = None
+        if json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        while True:
+            req = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with self._opener.open(req, timeout=self.timeout) as resp:
+                    resp_headers = {k.lower(): v for k, v in resp.headers.items()}
+                    return resp.read(), resp_headers
+            except urllib.error.HTTPError as exc:
+                status = exc.code
+                raw_err = exc.read()
+                if status == 429:
+                    retry_header = exc.headers.get("Retry-After") if exc.headers else None
+                    retry_after = int(retry_header) if retry_header and retry_header.isdigit() else 5
+                    if self.auto_retry_rate_limit:
+                        time.sleep(retry_after)
+                        continue
+                    raise RateLimitError(retry_after=retry_after) from exc
+
+                try:
+                    parsed = json.loads(raw_err.decode("utf-8", errors="replace"))
+                    err_msg = parsed.get("error", raw_err.decode("utf-8", errors="replace"))
+                except ValueError:
+                    err_msg = raw_err.decode("utf-8", errors="replace")
+                raise APIError(status, str(err_msg)) from exc
+            except urllib.error.URLError as exc:
+                raise TempTFError(f"Network error: {exc.reason}") from exc
+
+    def _request_json(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, str]] = None,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        raw, _ = self._request_raw(method, endpoint, params=params, json_body=json_body)
+        try:
+            return dict(json.loads(raw.decode("utf-8")))
+        except ValueError as exc:
+            raise TempTFError("Invalid JSON response from server") from exc
+
+    def create_email(
+        self,
+        providers: Optional[Union[str, Sequence[str]]] = None,
+        dot: bool = True,
+        plus: bool = True,
+    ) -> str:
+        """Generate a random temporary email address."""
+        if not dot and not plus:
+            raise ValueError("At least one of 'dot' or 'plus' must be True.")
+
+        params: Dict[str, str] = {}
+        if dot:
+            params["dot"] = "1"
+        if plus:
+            params["plus"] = "1"
+
+        if providers:
+            params["providers"] = (
+                providers if isinstance(providers, str) else ",".join(providers)
+            )
+
+        payload = self._request_json("GET", "/account", params=params)
+        email = payload.get("email")
+        if not email:
+            raise TempTFError("No email returned for the requested parameters.")
+        return str(email)
+
+    def create_gmail(self, dot: bool = True, plus: bool = True) -> str:
+        """Generate a @gmail.com address using dot syntax, plus alias, or both."""
+        return self.create_email(providers="gmail", dot=dot, plus=plus)
+
+    def create_gmail_dot(self) -> str:
+        """Generate a @gmail.com dot-variant address (e.g. u.s.e.r@gmail.com)."""
+        return self.create_email(providers="gmail", dot=True, plus=False)
+
+    def create_gmail_plus(self) -> str:
+        """Generate a @gmail.com plus-alias address (e.g. user+tag@gmail.com)."""
+        return self.create_email(providers="gmail", dot=False, plus=True)
+
+    def create_outlook(self) -> str:
+        """Generate an @outlook.com plus-alias address."""
+        return self.create_email(providers="outlook", dot=False, plus=True)
+
+    def create_hotmail(self) -> str:
+        """Generate a @hotmail.com plus-alias address."""
+        return self.create_email(providers="hotmail", dot=False, plus=True)
+
+    def create_edu(self) -> str:
+        """Generate a @high.edu.pl educational email address."""
+        return self.create_email(providers="high.edu.pl", dot=False, plus=True)
+
+    def get_messages(self, email: str) -> List[Message]:
+        """Fetch all messages currently in the inbox for the given address."""
+        payload = self._request_json("POST", "/check", json_body={"email": email})
+        items = payload.get("data") or []
+        return [Message.from_dict(item) for item in items]
+
+    def wait_for_message(
+        self,
+        email: str,
+        timeout: float = 120.0,
+        interval: float = 4.0,
+        predicate: Optional[Callable[[Message], bool]] = None,
+    ) -> Message:
+        """Poll the inbox until a matching message arrives or timeout is reached."""
+        deadline = time.monotonic() + timeout
+        while True:
+            for msg in self.get_messages(email):
+                if predicate is None or predicate(msg):
+                    return msg
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Timed out waiting for message on {email}")
+            time.sleep(interval)
+
+    def stream_messages(
+        self,
+        email: str,
+        interval: float = 5.0,
+        skip_existing: bool = False,
+    ) -> Iterator[Message]:
+        """Continuously poll the inbox and yield new messages as they arrive."""
+        seen: Set[str] = set()
+        if skip_existing:
+            for msg in self.get_messages(email):
+                seen.add(msg.id or f"{msg.date}:{msg.subject}")
+
+        while True:
+            messages = self.get_messages(email)
+            for msg in reversed(messages):
+                key = msg.id or f"{msg.date}:{msg.subject}"
+                if key not in seen:
+                    seen.add(key)
+                    yield msg
+            time.sleep(interval)
+
+    def download_attachment(
+        self,
+        email: str,
+        message_id: str,
+        attachment_id: str,
+        dest: Optional[Union[str, Path]] = None,
+    ) -> bytes:
+        """Download attachment content and optionally write it to disk."""
+        params = {
+            "email": email,
+            "messageId": message_id,
+            "attachmentId": attachment_id,
+        }
+        content, _ = self._request_raw("GET", "/attachment", params=params)
+        if dest is not None:
+            path = Path(dest)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(content)
+        return content
+
+    def get_stats(
+        self,
+        providers: Optional[Union[str, Sequence[str]]] = None,
+        dot: bool = True,
+        plus: bool = True,
+    ) -> Stats:
+        """Return pool availability and message statistics."""
+        params: Dict[str, str] = {}
+        if dot:
+            params["dot"] = "1"
+        if plus:
+            params["plus"] = "1"
+        if providers:
+            params["providers"] = (
+                providers if isinstance(providers, str) else ",".join(providers)
+            )
+        payload = self._request_json("GET", "/stats", params=params)
+        return Stats.from_dict(payload)

temptf-0.1.0/src/temptf/exceptions.py

@@ -0,0 +1,19 @@
+class TempTFError(Exception):
+    """Base exception for temptf errors."""
+
+
+class APIError(TempTFError):
+    """Raised when the temp.tf API returns an error status code."""
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"HTTP {status_code}: {message}")
+
+
+class RateLimitError(APIError):
+    """Raised when rate limit (HTTP 429) is exceeded and auto-retry is disabled."""
+
+    def __init__(self, retry_after: int, message: str = "Rate limit exceeded"):
+        self.retry_after = retry_after
+        super().__init__(429, message)

temptf-0.1.0/src/temptf/models.py

@@ -0,0 +1,86 @@
+import html
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+
+def _strip_html(raw: str) -> str:
+    if not raw:
+        return ""
+    cleaned = re.sub(r"<(script|style)[^>]*>.*?</\1>", "", raw, flags=re.DOTALL | re.IGNORECASE)
+    cleaned = re.sub(r"<br\s*/?>", "\n", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"</(p|div|tr|li|h[1-6])>", "\n", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"<[^>]+>", "", cleaned)
+    cleaned = html.unescape(cleaned)
+    return "\n".join(line.strip() for line in cleaned.splitlines() if line.strip())
+
+
+@dataclass(frozen=True)
+class Attachment:
+    id: str
+    name: str
+    content_type: str
+    size: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Attachment":
+        return cls(
+            id=str(data.get("id", "")),
+            name=str(data.get("name", "")),
+            content_type=str(data.get("contentType", "application/octet-stream")),
+            size=int(data.get("size", 0)),
+        )
+
+
+@dataclass(frozen=True)
+class Message:
+    id: str
+    sender: str
+    subject: str
+    date: str
+    body: str
+    body_content_type: str
+    attachments: List[Attachment] = field(default_factory=list)
+    inline_cids: Dict[str, str] = field(default_factory=dict)
+
+    @property
+    def text(self) -> str:
+        """Plain-text representation of the message body."""
+        if self.body_content_type.lower() == "html":
+            return _strip_html(self.body)
+        return self.body.strip()
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Message":
+        attachments = [Attachment.from_dict(item) for item in (data.get("attachments") or [])]
+        return cls(
+            id=str(data.get("id", "")),
+            sender=str(data.get("from", "")),
+            subject=str(data.get("subject", "")),
+            date=str(data.get("date", "")),
+            body=str(data.get("body", "")),
+            body_content_type=str(data.get("bodyContentType", "text")),
+            attachments=attachments,
+            inline_cids=dict(data.get("inlineCids") or {}),
+        )
+
+
+@dataclass(frozen=True)
+class Stats:
+    total_addresses: int
+    total_formatted: str
+    total_received: int
+    breakdown: Dict[str, int]
+    breakdown_formatted: Dict[str, str]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Stats":
+        raw_breakdown = data.get("breakdown") or {}
+        breakdown = {k: int(v) for k, v in raw_breakdown.items()}
+        return cls(
+            total_addresses=int(data.get("totalAddresses", 0)),
+            total_formatted=str(data.get("totalFormatted", "0")),
+            total_received=int(data.get("totalReceived", 0)),
+            breakdown=breakdown,
+            breakdown_formatted=dict(data.get("breakdownFormatted") or {}),
+        )

temptf-0.1.0/tests/test_client.py

@@ -0,0 +1,125 @@
+import io
+import json
+import unittest
+import urllib.error
+from email.message import Message as HTTPHeaders
+from unittest.mock import MagicMock
+
+from temptf import TempTFClient
+from temptf.exceptions import APIError, RateLimitError
+
+
+def _mock_opener(payload=None, raw_bytes: bytes = b""):
+    opener = MagicMock()
+    resp = MagicMock()
+    if payload is not None:
+        raw_bytes = json.dumps(payload).encode("utf-8")
+    resp.read.return_value = raw_bytes
+    resp.headers = {"Content-Type": "application/json"}
+    resp.__enter__.return_value = resp
+    resp.__exit__.return_value = False
+    opener.open.return_value = resp
+    return opener
+
+
+class TestTempTFClient(unittest.TestCase):
+    def test_provider_specific_creation(self) -> None:
+        opener = _mock_opener({"email": "u.s.e.r@gmail.com"})
+        client = TempTFClient(opener=opener)
+
+        self.assertEqual(client.create_gmail_dot(), "u.s.e.r@gmail.com")
+        req = opener.open.call_args[0][0]
+        self.assertEqual(req.full_url, "https://temp.tf/api/account?dot=1&providers=gmail")
+
+        opener = _mock_opener({"email": "user+123@gmail.com"})
+        client = TempTFClient(opener=opener)
+        self.assertEqual(client.create_gmail_plus(), "user+123@gmail.com")
+        req = opener.open.call_args[0][0]
+        self.assertEqual(req.full_url, "https://temp.tf/api/account?plus=1&providers=gmail")
+
+        opener = _mock_opener({"email": "user+123@outlook.com"})
+        client = TempTFClient(opener=opener)
+        self.assertEqual(client.create_outlook(), "user+123@outlook.com")
+        req = opener.open.call_args[0][0]
+        self.assertEqual(req.full_url, "https://temp.tf/api/account?plus=1&providers=outlook")
+
+        opener = _mock_opener({"email": "user+123@hotmail.com"})
+        client = TempTFClient(opener=opener)
+        self.assertEqual(client.create_hotmail(), "user+123@hotmail.com")
+        req = opener.open.call_args[0][0]
+        self.assertEqual(req.full_url, "https://temp.tf/api/account?plus=1&providers=hotmail")
+
+        opener = _mock_opener({"email": "abc@high.edu.pl"})
+        client = TempTFClient(opener=opener)
+        self.assertEqual(client.create_edu(), "abc@high.edu.pl")
+        req = opener.open.call_args[0][0]
+        self.assertEqual(req.full_url, "https://temp.tf/api/account?plus=1&providers=high.edu.pl")
+
+    def test_get_messages_and_html_stripping(self) -> None:
+        payload = {
+            "data": [
+                {
+                    "id": "101",
+                    "from": "noreply@service.com",
+                    "subject": "Verification Code",
+                    "date": "2026-11-06T12:00:00.000Z",
+                    "body": "<html><body><p>Your code is <b>482910</b></p></body></html>",
+                    "bodyContentType": "html",
+                    "attachments": [
+                        {
+                            "id": "att_1",
+                            "name": "receipt.pdf",
+                            "contentType": "application/pdf",
+                            "size": 512,
+                        }
+                    ],
+                }
+            ],
+            "totalReceived": 500,
+        }
+        opener = _mock_opener(payload)
+        client = TempTFClient(opener=opener)
+
+        messages = client.get_messages("user+123@gmail.com")
+        self.assertEqual(len(messages), 1)
+        msg = messages[0]
+        self.assertEqual(msg.id, "101")
+        self.assertEqual(msg.sender, "noreply@service.com")
+        self.assertEqual(msg.subject, "Verification Code")
+        self.assertEqual(msg.text, "Your code is 482910")
+        self.assertEqual(len(msg.attachments), 1)
+        self.assertEqual(msg.attachments[0].name, "receipt.pdf")
+
+    def test_error_handling(self) -> None:
+        opener = MagicMock()
+        client = TempTFClient(opener=opener, auto_retry_rate_limit=False)
+
+        headers = HTTPHeaders()
+        headers["Retry-After"] = "12"
+        err_429 = urllib.error.HTTPError(
+            url="https://temp.tf/api/check",
+            code=429,
+            msg="Too Many Requests",
+            hdrs=headers,
+            fp=io.BytesIO(b'{"error":"Rate limit"}'),
+        )
+        opener.open.side_effect = err_429
+        with self.assertRaises(RateLimitError) as exc_info:
+            client.get_messages("user+123@gmail.com")
+        self.assertEqual(exc_info.exception.retry_after, 12)
+
+        err_403 = urllib.error.HTTPError(
+            url="https://temp.tf/api/check",
+            code=403,
+            msg="Forbidden",
+            hdrs=HTTPHeaders(),
+            fp=io.BytesIO(b'{"error":"Forbidden address"}'),
+        )
+        opener.open.side_effect = err_403
+        with self.assertRaises(APIError) as api_exc:
+            client.get_messages("invalid@example.com")
+        self.assertEqual(api_exc.exception.status_code, 403)
+
+
+if __name__ == "__main__":
+    unittest.main()