mailsocket 0.2.0__tar.gz → 0.3.1__tar.gz

{mailsocket-0.2.0 → mailsocket-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.2.0
+Version: 0.3.1
 Summary: Official Python client for the mailsocket REST API — one line to wait for an OTP.
 Author: mailsocket
 License-Expression: MIT
@@ -31,17 +31,34 @@ The official Python client for the [mailsocket](https://mailsocket.app) v1 REST
 Ephemeral email inboxes, message retrieval, and — the whole point — **wait for the OTP in one line**.
 
 ```python
+import time
+
 from mailsocket import Client
 
 client = Client("ms_live_...")            # your API key from the dashboard
 inbox = client.create_inbox(label="signup")  # -> {"id": "inbox_...", "address": "..."}
 
+started = time.time()                         # take the cutoff BEFORE the trigger
 # hand inbox["address"] to whatever form sends the code, then:
-result = client.wait_for_otp(inbox["id"])     # blocks up to 60s
+result = client.wait_for_otp(inbox["id"], since=started)  # blocks up to 60s
 print(result.otp)         # "123456"
 print(result.confidence)  # 0.95
 ```
 
+Take `started` just before you trigger the email and pass it as `since`: a
+code that lands before `wait_for_otp` starts is still caught, and an older
+code in a reused inbox is not.
+
+No email handy? `client.send_test_code(inbox_id)` drops a sample code into
+the inbox so you can see the whole loop work:
+
+```python
+started = time.time()
+client.send_test_code(inbox["id"])            # -> {"message_id": "msg_...", "sent_at": "..."}
+result = client.wait_for_otp(inbox["id"], since=started)
+print(result.otp)         # the sample code
+```
+
 No polling loop. No regex over the email body. `wait_for_otp` long-polls the
 server (which already knows how to extract the code) and hands back a
 deterministic result with a confidence score.
@@ -69,6 +86,7 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 | `list_messages(inbox_id, has_otp=None, subject_contains=None, sender=None, ...)` | `Page` — `sender` maps to the API's `from` filter |
 | `get_latest(inbox_id)` | `dict` — newest message |
 | `get_message(message_id)` | `dict` — full message |
+| `send_test_code(inbox_id)` | `dict` — `message_id`, `sent_at` of a sample OTP email put straight into the inbox (no mail server; 5 per inbox / 20 per account per hour) |
 
 ### The moat
 
@@ -78,6 +96,14 @@ result = client.wait_for_link("inbox_abc123", timeout=60, since=None)
 result = client.wait("inbox_abc123", timeout=60, min_confidence=0.0, since=None)  # otp OR link
 ```
 
+With a cutoff taken before the trigger (the usual case):
+
+```python
+started = time.time()
+# trigger the email here
+result = client.wait_for_otp("inbox_abc123", since=started)
+```
+
 All three return a `WaitResult` and take keyword-only arguments after
 `inbox_id`. `timeout`/`min_confidence`/`since` shown above are the defaults —
 call with no extra arguments for the common case.
@@ -112,11 +138,16 @@ Semantics:
 `MailsocketError` (base) with subclasses:
 
 - `AuthError` — HTTP 401 (bad/missing key).
-- `NotFound` — HTTP 404.
+- `NotFound` — HTTP 404 (also an unknown, deleted or foreign inbox in
+  `send_test_code`).
 - `RateLimited` — HTTP 429, carries `.subcode` (`rate_limited`,
   `too_many_wait_requests`, `wait_capacity`) and `.retry_after`.
 - `WaitTimeout` — no matching message within the overall deadline.
 
+`send_test_code` on a disabled inbox raises the base `MailsocketError` with
+`code="inbox_disabled"` and `status=409`. Over its hourly quota it raises
+`RateLimited`; `.retry_after` says how many seconds until it frees up.
+
 ## Develop
 
 ```bash
@@ -131,6 +162,16 @@ invalid id never reaches the network.
 
 ## Changelog
 
+- **0.3.1** — the `wait*` helpers no longer miss a message that lands between
+  two long-poll calls. When you pass no `since`, the first call still omits it
+  (the server uses the request start), and every following call sends the
+  cutoff the server reported in the `Mailsocket-Wait-Since` response header of
+  the previous call. With an older server that sends no such header, behaviour
+  is unchanged. An explicit `since` is used as before on every call.
+- **0.3.0** — new `Client.send_test_code(inbox_id)` (`POST /inboxes/{id}/test-code`):
+  puts one sample OTP email into your own inbox without going through the
+  mail server, and returns `{"message_id", "sent_at"}`. README samples now
+  take `started = time.time()` before the trigger and pass `since=started`.
 - **0.2.0** — BEHAVIOUR CHANGE: `wait_for_otp`/`wait_for_link`/`wait` now
   default `since=None`, which omits the param so the server uses the
   request start time, instead of the old `since=0` ("any message already

{mailsocket-0.2.0 → mailsocket-0.3.1}/README.md

@@ -4,17 +4,34 @@ The official Python client for the [mailsocket](https://mailsocket.app) v1 REST
 Ephemeral email inboxes, message retrieval, and — the whole point — **wait for the OTP in one line**.
 
 ```python
+import time
+
 from mailsocket import Client
 
 client = Client("ms_live_...")            # your API key from the dashboard
 inbox = client.create_inbox(label="signup")  # -> {"id": "inbox_...", "address": "..."}
 
+started = time.time()                         # take the cutoff BEFORE the trigger
 # hand inbox["address"] to whatever form sends the code, then:
-result = client.wait_for_otp(inbox["id"])     # blocks up to 60s
+result = client.wait_for_otp(inbox["id"], since=started)  # blocks up to 60s
 print(result.otp)         # "123456"
 print(result.confidence)  # 0.95
 ```
 
+Take `started` just before you trigger the email and pass it as `since`: a
+code that lands before `wait_for_otp` starts is still caught, and an older
+code in a reused inbox is not.
+
+No email handy? `client.send_test_code(inbox_id)` drops a sample code into
+the inbox so you can see the whole loop work:
+
+```python
+started = time.time()
+client.send_test_code(inbox["id"])            # -> {"message_id": "msg_...", "sent_at": "..."}
+result = client.wait_for_otp(inbox["id"], since=started)
+print(result.otp)         # the sample code
+```
+
 No polling loop. No regex over the email body. `wait_for_otp` long-polls the
 server (which already knows how to extract the code) and hands back a
 deterministic result with a confidence score.
@@ -42,6 +59,7 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 | `list_messages(inbox_id, has_otp=None, subject_contains=None, sender=None, ...)` | `Page` — `sender` maps to the API's `from` filter |
 | `get_latest(inbox_id)` | `dict` — newest message |
 | `get_message(message_id)` | `dict` — full message |
+| `send_test_code(inbox_id)` | `dict` — `message_id`, `sent_at` of a sample OTP email put straight into the inbox (no mail server; 5 per inbox / 20 per account per hour) |
 
 ### The moat
 
@@ -51,6 +69,14 @@ result = client.wait_for_link("inbox_abc123", timeout=60, since=None)
 result = client.wait("inbox_abc123", timeout=60, min_confidence=0.0, since=None)  # otp OR link
 ```
 
+With a cutoff taken before the trigger (the usual case):
+
+```python
+started = time.time()
+# trigger the email here
+result = client.wait_for_otp("inbox_abc123", since=started)
+```
+
 All three return a `WaitResult` and take keyword-only arguments after
 `inbox_id`. `timeout`/`min_confidence`/`since` shown above are the defaults —
 call with no extra arguments for the common case.
@@ -85,11 +111,16 @@ Semantics:
 `MailsocketError` (base) with subclasses:
 
 - `AuthError` — HTTP 401 (bad/missing key).
-- `NotFound` — HTTP 404.
+- `NotFound` — HTTP 404 (also an unknown, deleted or foreign inbox in
+  `send_test_code`).
 - `RateLimited` — HTTP 429, carries `.subcode` (`rate_limited`,
   `too_many_wait_requests`, `wait_capacity`) and `.retry_after`.
 - `WaitTimeout` — no matching message within the overall deadline.
 
+`send_test_code` on a disabled inbox raises the base `MailsocketError` with
+`code="inbox_disabled"` and `status=409`. Over its hourly quota it raises
+`RateLimited`; `.retry_after` says how many seconds until it frees up.
+
 ## Develop
 
 ```bash
@@ -104,6 +135,16 @@ invalid id never reaches the network.
 
 ## Changelog
 
+- **0.3.1** — the `wait*` helpers no longer miss a message that lands between
+  two long-poll calls. When you pass no `since`, the first call still omits it
+  (the server uses the request start), and every following call sends the
+  cutoff the server reported in the `Mailsocket-Wait-Since` response header of
+  the previous call. With an older server that sends no such header, behaviour
+  is unchanged. An explicit `since` is used as before on every call.
+- **0.3.0** — new `Client.send_test_code(inbox_id)` (`POST /inboxes/{id}/test-code`):
+  puts one sample OTP email into your own inbox without going through the
+  mail server, and returns `{"message_id", "sent_at"}`. README samples now
+  take `started = time.time()` before the trigger and pass `since=started`.
 - **0.2.0** — BEHAVIOUR CHANGE: `wait_for_otp`/`wait_for_link`/`wait` now
   default `since=None`, which omits the param so the server uses the
   request start time, instead of the old `since=0` ("any message already

{mailsocket-0.2.0 → mailsocket-0.3.1}/mailsocket/__init__.py

@@ -3,7 +3,7 @@
 from .client import Client, Page, WaitResult
 from .errors import AuthError, MailsocketError, NotFound, RateLimited, WaitTimeout
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"
 
 __all__ = [
     "Client",

{mailsocket-0.2.0 → mailsocket-0.3.1}/mailsocket/client.py

@@ -18,6 +18,8 @@ DEFAULT_BASE_URL = "https://dash.mailsocket.app/api/v1"
 WAIT_TIMEOUT_MAX = 25  # seconds — the server clamps the per-call wait to [1, 25]
 WAIT_SOCKET_BUFFER = 10  # seconds of client-side slack above the server block
 DEFAULT_RETRY_AFTER = 1.0  # seconds, when a 429 carries no Retry-After header
+# Response header with the cutoff a wait call actually used (server >= 2026-10).
+WAIT_SINCE_HEADER = "mailsocket-wait-since"
 
 __all__ = ["Client", "Page", "WaitResult"]
 
@@ -201,6 +203,25 @@ class Client:
         payload = self._request("GET", f"/messages/{_seg(message_id)}")
         return payload["data"]
 
+    def send_test_code(self, inbox_id: str) -> dict:
+        """Put one sample OTP email (a random 6-digit code) into ``inbox_id``.
+
+        Calls ``POST /inboxes/{id}/test-code`` and returns its ``data`` dict:
+        ``{"message_id": "msg_...", "sent_at": "..."}``. The message does NOT
+        go through the mail server: it is stored and parsed like real inbound
+        mail, so a pending or later wait (with a ``since`` from before this
+        call) returns it. Use it to prove the wait loop end to end without
+        sending real email.
+
+        Shares the dashboard "Send a test code" quota (5 per inbox, 20 per
+        account per hour). Errors: :class:`NotFound` for an unknown, deleted
+        or foreign inbox; :class:`RateLimited` (with ``retry_after``) over the
+        quota; :class:`MailsocketError` with ``code="inbox_disabled"``
+        (HTTP 409) for a disabled inbox.
+        """
+        payload = self._request("POST", f"/inboxes/{_seg(inbox_id)}/test-code")
+        return payload["data"]
+
     # -- the moat -------------------------------------------------------------
 
     def wait_for_otp(
@@ -270,6 +291,12 @@ class Client:
         since,
     ) -> WaitResult:
         deadline = _monotonic() + float(timeout)
+        # No caller ``since``: the first call omits it (server default = the
+        # request start), and every later call sends back the cutoff the
+        # previous response reported, so a message that lands between two
+        # calls is still matched. An older server sends no header; then each
+        # call keeps omitting ``since`` exactly as before.
+        cursor = since
         while True:
             remaining = deadline - _monotonic()
             if remaining <= 0:
@@ -278,8 +305,8 @@ class Client:
                 )
             server_timeout = max(1.0, min(float(WAIT_TIMEOUT_MAX), remaining))
             params = {"timeout": server_timeout, "require": require}
-            if since is not None:
-                params["since"] = since
+            if cursor is not None:
+                params["since"] = cursor
             if min_confidence is not None:
                 params["min_confidence"] = min_confidence
 
@@ -293,6 +320,7 @@ class Client:
             if status == 200:
                 return WaitResult(payload["data"])
             if status == 204:
+                cursor = self._next_cursor(since, cursor, headers)
                 continue
             if status == 429:
                 if not self._retry_wait_on_429:
@@ -307,6 +335,15 @@ class Client:
                 continue
             self._raise_for_status(status, headers, payload)
 
+    @staticmethod
+    def _next_cursor(since, cursor, headers: dict):
+        """The ``since`` for the next wait call: the caller's own value when
+        given, else the server-reported cutoff of this call, else unchanged
+        (an older server sends no header)."""
+        if since is not None:
+            return cursor
+        return headers.get(WAIT_SINCE_HEADER) or cursor
+
     def _request(self, method: str, path: str, *, params: dict | None = None, json_body=None):
         status, headers, body = self._request_http(method, path, params=params, json_body=json_body)
         payload = self._parse_json(body)
@@ -320,7 +357,7 @@ class Client:
             url += "?" + urllib.parse.urlencode(params, doseq=True)
         headers = {
             "Accept": "application/json",
-            "User-Agent": "mailsocket-python/0.2.0",
+            "User-Agent": "mailsocket-python/0.3.1",
         }
         headers.update(self._extra_headers)
         # Set last so nothing in extra_headers can ever replace it.

{mailsocket-0.2.0 → mailsocket-0.3.1}/mailsocket.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.2.0
+Version: 0.3.1
 Summary: Official Python client for the mailsocket REST API — one line to wait for an OTP.
 Author: mailsocket
 License-Expression: MIT
@@ -31,17 +31,34 @@ The official Python client for the [mailsocket](https://mailsocket.app) v1 REST
 Ephemeral email inboxes, message retrieval, and — the whole point — **wait for the OTP in one line**.
 
 ```python
+import time
+
 from mailsocket import Client
 
 client = Client("ms_live_...")            # your API key from the dashboard
 inbox = client.create_inbox(label="signup")  # -> {"id": "inbox_...", "address": "..."}
 
+started = time.time()                         # take the cutoff BEFORE the trigger
 # hand inbox["address"] to whatever form sends the code, then:
-result = client.wait_for_otp(inbox["id"])     # blocks up to 60s
+result = client.wait_for_otp(inbox["id"], since=started)  # blocks up to 60s
 print(result.otp)         # "123456"
 print(result.confidence)  # 0.95
 ```
 
+Take `started` just before you trigger the email and pass it as `since`: a
+code that lands before `wait_for_otp` starts is still caught, and an older
+code in a reused inbox is not.
+
+No email handy? `client.send_test_code(inbox_id)` drops a sample code into
+the inbox so you can see the whole loop work:
+
+```python
+started = time.time()
+client.send_test_code(inbox["id"])            # -> {"message_id": "msg_...", "sent_at": "..."}
+result = client.wait_for_otp(inbox["id"], since=started)
+print(result.otp)         # the sample code
+```
+
 No polling loop. No regex over the email body. `wait_for_otp` long-polls the
 server (which already knows how to extract the code) and hands back a
 deterministic result with a confidence score.
@@ -69,6 +86,7 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 | `list_messages(inbox_id, has_otp=None, subject_contains=None, sender=None, ...)` | `Page` — `sender` maps to the API's `from` filter |
 | `get_latest(inbox_id)` | `dict` — newest message |
 | `get_message(message_id)` | `dict` — full message |
+| `send_test_code(inbox_id)` | `dict` — `message_id`, `sent_at` of a sample OTP email put straight into the inbox (no mail server; 5 per inbox / 20 per account per hour) |
 
 ### The moat
 
@@ -78,6 +96,14 @@ result = client.wait_for_link("inbox_abc123", timeout=60, since=None)
 result = client.wait("inbox_abc123", timeout=60, min_confidence=0.0, since=None)  # otp OR link
 ```
 
+With a cutoff taken before the trigger (the usual case):
+
+```python
+started = time.time()
+# trigger the email here
+result = client.wait_for_otp("inbox_abc123", since=started)
+```
+
 All three return a `WaitResult` and take keyword-only arguments after
 `inbox_id`. `timeout`/`min_confidence`/`since` shown above are the defaults —
 call with no extra arguments for the common case.
@@ -112,11 +138,16 @@ Semantics:
 `MailsocketError` (base) with subclasses:
 
 - `AuthError` — HTTP 401 (bad/missing key).
-- `NotFound` — HTTP 404.
+- `NotFound` — HTTP 404 (also an unknown, deleted or foreign inbox in
+  `send_test_code`).
 - `RateLimited` — HTTP 429, carries `.subcode` (`rate_limited`,
   `too_many_wait_requests`, `wait_capacity`) and `.retry_after`.
 - `WaitTimeout` — no matching message within the overall deadline.
 
+`send_test_code` on a disabled inbox raises the base `MailsocketError` with
+`code="inbox_disabled"` and `status=409`. Over its hourly quota it raises
+`RateLimited`; `.retry_after` says how many seconds until it frees up.
+
 ## Develop
 
 ```bash
@@ -131,6 +162,16 @@ invalid id never reaches the network.
 
 ## Changelog
 
+- **0.3.1** — the `wait*` helpers no longer miss a message that lands between
+  two long-poll calls. When you pass no `since`, the first call still omits it
+  (the server uses the request start), and every following call sends the
+  cutoff the server reported in the `Mailsocket-Wait-Since` response header of
+  the previous call. With an older server that sends no such header, behaviour
+  is unchanged. An explicit `since` is used as before on every call.
+- **0.3.0** — new `Client.send_test_code(inbox_id)` (`POST /inboxes/{id}/test-code`):
+  puts one sample OTP email into your own inbox without going through the
+  mail server, and returns `{"message_id", "sent_at"}`. README samples now
+  take `started = time.time()` before the trigger and pass `since=started`.
 - **0.2.0** — BEHAVIOUR CHANGE: `wait_for_otp`/`wait_for_link`/`wait` now
   default `since=None`, which omits the param so the server uses the
   request start time, instead of the old `since=0` ("any message already

{mailsocket-0.2.0 → mailsocket-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsocket"
-version = "0.2.0"
+version = "0.3.1"
 description = "Official Python client for the mailsocket REST API — one line to wait for an OTP."
 readme = "README.md"
 requires-python = ">=3.9"

{mailsocket-0.2.0 → mailsocket-0.3.1}/tests/test_client.py

@@ -193,6 +193,63 @@ def test_wait_keeps_polling_through_204s_then_returns(monkeypatch):
         assert "require=otp" in url
 
 
+def _since_of(url):
+    query = urllib.parse.parse_qs(urllib.parse.urlsplit(url).query)
+    return query.get("since", [None])[0]
+
+
+CURSOR_1 = "2026-10-12T03:04:05.123456Z"
+CURSOR_2 = "2026-10-12T03:04:30.654321Z"
+EPOCH = "1970-01-01T00:00:00.000000Z"
+H = "Mailsocket-Wait-Since"
+
+
+@pytest.mark.parametrize(
+    "method, kwargs, headers, expected",
+    [
+        # 0.3.1 gap fix: no caller since -> call 1 omits it, call N sends the
+        # header of call N-1, so a message landing between calls is matched.
+        ("wait_for_otp", {}, [{H: CURSOR_1}, {H: CURSOR_1}, {}], [None, CURSOR_1, CURSOR_1]),
+        ("wait_for_link", {}, [{H: CURSOR_1}, {}], [None, CURSOR_1]),
+        ("wait", {}, [{H: CURSOR_1}, {}], [None, CURSOR_1]),
+        ("wait_for_otp", {}, [{H: CURSOR_1}, {H: CURSOR_2}, {}], [None, CURSOR_1, CURSOR_2]),
+        ("wait_for_otp", {}, [{H.upper(): CURSOR_1}, {}], [None, CURSOR_1]),
+        # Old server (no header) or an empty header: unchanged 0.3.0 behaviour.
+        ("wait_for_otp", {}, [{}, {}, {}], [None, None, None]),
+        ("wait_for_otp", {}, [{H: ""}, {}], [None, None]),
+        # An explicit since is never replaced by the header.
+        ("wait_for_otp", {"since": "msg_anchor"}, [{H: CURSOR_1}, {H: CURSOR_1}, {}], ["msg_anchor"] * 3),
+        ("wait_for_otp", {"since": 0}, [{H: EPOCH}, {}], ["0", "0"]),
+    ],
+)
+def test_wait_loop_cursor(monkeypatch, method, kwargs, headers, expected):
+    final = LINK_MESSAGE if method == "wait_for_link" else OTP_MESSAGE
+    responses = [(204, h, None) for h in headers[:-1]] + [(200, headers[-1], {"data": final})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    getattr(client, method)("inbox_abc", timeout=60, **kwargs)
+
+    assert [_since_of(url) for _, url in transport.calls] == expected
+
+
+def test_wait_loop_keeps_cursor_across_a_429_retry_and_not_between_waits(monkeypatch):
+    responses = [
+        (204, {H: CURSOR_1}, None),
+        (429, {"Retry-After": "0"}, {"error": {"code": "wait_capacity", "message": "busy"}}),
+        (200, {}, {"data": OTP_MESSAGE}),
+        (200, {}, {"data": OTP_MESSAGE}),
+    ]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+    monkeypatch.setattr(mailsocket.client, "_sleep", lambda s: None)
+
+    client.wait_for_otp("inbox_abc", timeout=60)
+    client.wait_for_otp("inbox_abc", timeout=60)  # a new wait starts fresh
+
+    assert [_since_of(url) for _, url in transport.calls] == [None, CURSOR_1, CURSOR_1, None]
+
+
 def test_wait_respects_overall_timeout_raises_wait_timeout(monkeypatch):
     # A 204 means "the server blocked for `timeout` seconds and found nothing".
     # Model that with a controllable clock: each 204 advances time by the
@@ -557,6 +614,7 @@ def test_invalid_id_rejected_before_any_request_hits_real_server(raw):
             lambda: client.wait_for_otp(raw, timeout=5),
             lambda: client.wait_for_link(raw, timeout=5),
             lambda: client.wait(raw, timeout=5),
+            lambda: client.send_test_code(raw),
         ]
         for call in calls:
             with pytest.raises(MailsocketError) as exc_info:
@@ -581,7 +639,7 @@ def test_metadata_consistency_across_files():
     from pathlib import Path
 
     root = Path(__file__).resolve().parents[1]
-    expected = "0.2.0"
+    expected = "0.3.1"
 
     pyproject = tomllib.loads((root / "pyproject.toml").read_text())
     assert pyproject["project"]["version"] == expected
@@ -657,3 +715,138 @@ def test_no_extra_headers_is_backwards_compatible(monkeypatch):
     sent = capture.headers[0]
     assert set(sent) >= {"authorization", "accept", "user-agent"}
     assert "x-forwarded-proto" not in sent
+
+
+# -- send_test_code (POST /inboxes/{id}/test-code) ----------------------------
+
+TEST_CODE_DATA = {"message_id": "msg_test1", "sent_at": "2026-10-08T12:00:00Z"}
+
+
+def test_send_test_code_posts_and_returns_data(monkeypatch):
+    client, transport = make_client([(201, {}, {"data": TEST_CODE_DATA})])
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    data = client.send_test_code("inbox_abc")
+
+    assert data == TEST_CODE_DATA
+    assert transport.calls == [("POST", "https://example.test/api/v1/inboxes/inbox_abc/test-code")]
+
+
+def test_send_test_code_sends_no_body(monkeypatch):
+    seen = []
+
+    def capture(request, timeout=None):
+        seen.append((request.get_method(), request.data, dict(request.header_items())))
+
+        class _Resp:
+            headers = {}
+
+            def getcode(self):
+                return 201
+
+            def read(self):
+                return json.dumps({"data": TEST_CODE_DATA}).encode()
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *exc_info):
+                return False
+
+        return _Resp()
+
+    monkeypatch.setattr("urllib.request.urlopen", capture)
+    Client("ms_live_test1234567890", base_url="https://example.test/api/v1").send_test_code("inbox_abc")
+    method, body, headers = seen[0]
+    assert method == "POST"
+    assert body is None
+    assert headers["Authorization"] == "Bearer ms_live_test1234567890"
+
+
+def test_send_test_code_encodes_id_as_one_segment(monkeypatch):
+    client, transport = make_client([(201, {}, {"data": TEST_CODE_DATA})])
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    client.send_test_code("a/b?c")
+
+    assert transport.calls[0][1] == "https://example.test/api/v1/inboxes/a%2Fb%3Fc/test-code"
+
+
+def test_send_test_code_404_raises_not_found(monkeypatch):
+    responses = [(404, {}, {"error": {"code": "not_found", "message": "Resource not found.", "fields": {}}})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    with pytest.raises(NotFound) as exc_info:
+        client.send_test_code("inbox_foreign")
+    assert exc_info.value.status == 404
+
+
+def test_send_test_code_429_raises_rate_limited_with_retry_after(monkeypatch):
+    slept = []
+    monkeypatch.setattr(mailsocket.client, "_sleep", lambda s: slept.append(s))
+    responses = [
+        (
+            429,
+            {"Retry-After": "1800"},
+            {"error": {"code": "rate_limited", "message": "Too many test codes. Try again at 13:00 UTC.", "fields": {}}},
+        )
+    ]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    with pytest.raises(RateLimited) as exc_info:
+        client.send_test_code("inbox_abc")
+    err = exc_info.value
+    assert err.retry_after == 1800.0
+    assert err.subcode == "rate_limited"
+    assert "Try again at" in str(err)
+    assert len(transport.calls) == 1  # never retried
+    assert slept == []
+
+
+def test_send_test_code_disabled_inbox_raises_mailsocket_error(monkeypatch):
+    responses = [
+        (
+            409,
+            {},
+            {"error": {"code": "inbox_disabled", "message": "This inbox is disabled. Enable it to receive a test code.", "fields": {}}},
+        )
+    ]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    with pytest.raises(MailsocketError) as exc_info:
+        client.send_test_code("inbox_abc")
+    err = exc_info.value
+    assert type(err) is MailsocketError
+    assert err.code == "inbox_disabled"
+    assert err.status == 409
+
+
+def test_send_test_code_401_raises_auth_error(monkeypatch):
+    responses = [(401, {}, {"error": {"code": "authentication_required", "message": "Auth required.", "fields": {}}})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    with pytest.raises(AuthError):
+        client.send_test_code("inbox_abc")
+
+
+def test_readme_wait_samples_take_a_cutoff_before_the_trigger():
+    """Every runnable wait sample in the README passes since=started, with
+    started taken before the trigger (ux4 SDK follow-up)."""
+    from pathlib import Path
+
+    readme = (Path(__file__).resolve().parents[1] / "README.md").read_text()
+    blocks = readme.split("```python")[1:]
+    samples = [b.split("```")[0] for b in blocks]
+    waits = [s for s in samples if "wait_for_otp(" in s and "since=None" not in s]
+    assert waits, "no wait sample found"
+    for sample in waits:
+        assert "started = time.time()" in sample
+        assert sample.index("started = time.time()") < sample.index("wait_for_otp(")
+        for line in sample.splitlines():
+            if "wait_for_otp(" in line or "wait_for_link(" in line:
+                assert "since=" in line, line
+    assert "client.send_test_code(inbox" in readme