nowtempmail 0.1.2__tar.gz

nowtempmail-0.1.2/.gitignore

@@ -0,0 +1,8 @@
+dist/
+build/
+*.egg-info/
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

nowtempmail-0.1.2/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to this package are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+`nowtempmail` and `pytest-nowtempmail` are released together from this
+repository and share a version number.
+
+## [Unreleased]
+
+## [0.1.2] - 2026-08-30
+
+First release where both distributions reach PyPI together. Package code is
+again unchanged from 0.1.0.
+
+### Fixed
+
+- **The PyPI publish step could not be retried.** It uploads both distributions
+  in one call and PyPI processes them one at a time, so when the second failed
+  the first was already published and every retry then died on the duplicate
+  file rather than on the real problem — leaving a version bump as the only way
+  forward. The TestPyPI step had `skip-existing` from the start; the PyPI step
+  did not, and that asymmetry cost the 0.1.1 release.
+
+### Note on 0.1.1
+
+`nowtempmail` 0.1.1 is on PyPI and is a complete, working SDK. Its companion
+`pytest-nowtempmail` 0.1.1 is not, because that upload failed. Install 0.1.2 or
+later if you want the fixtures; nothing is wrong with 0.1.1 of the SDK itself.
+
+## [0.1.1] - 2026-08-30
+
+First release on PyPI. Identical package code to 0.1.0 — the only changes are
+to the release pipeline and this file.
+
+### Fixed
+
+- **The release workflow's smoke check rejected a working package.** It ran
+  `pytest --version --trace-config | grep -q nowtempmail` to prove the
+  `pytest11` entry point had registered. `--version` makes pytest print the
+  version and exit *before* emitting any plugin trace, so the grep matched
+  nothing and the step failed after every real check had passed — the install
+  succeeded, the import succeeded, the fixtures were registered. It now asserts
+  against installed metadata instead: the entry point resolves, loads, and
+  exposes `ntm_inbox`, `ntm_fresh_inbox` and `ntm_client`.
+- **`CHANGELOG.md` did not exist**, while `pyproject.toml` advertised a
+  Changelog URL. The PyPI project page would have carried a dead link.
+
+## [0.1.0] - 2026-08-30
+
+Published to **TestPyPI only**. Its release run failed the smoke gate described
+above, so it was never promoted to PyPI. Nothing is wrong with the 0.1.0
+artifacts; they are simply superseded by 0.1.1.
+
+### Added
+
+- **`NowTempMail` client** — `me()`, `domains.list()`,
+  `mailboxes.create/get/attach/delete`, `reservations`, `webhooks`. Zero runtime
+  dependencies, on `urllib`: this package installs into test environments that
+  already hold pytest, Playwright and somebody else's HTTP client, and a hard
+  `httpx` requirement would be a resolver conflict in exactly those places.
+- **`Mailbox`** with `wait_for_code()` and `wait_for_message()`. Verification
+  codes are extracted server-side at ingest, so `wait_for_code()` never fetches
+  a message body — one request per poll, and no message content transferred.
+- **pytest fixtures**, via the `pytest-nowtempmail` distribution:
+  `ntm_inbox` (session-scoped and shared, because mailbox creation is the only
+  call that spends daily quota and deleting one never refunds it),
+  `ntm_fresh_inbox`, `ntm_client` and `ntm_options`. Every wait is watermarked
+  per test, so a shared inbox cannot resolve with an earlier test's code.
+- **Report redaction.** A matched message is recorded on the test and printed
+  on failure — sender, subject, timestamp and extracted codes, but **not**
+  bodies or links. A CI artifact is downloaded by anyone with repository read
+  access, and a password-reset link inside one is a live credential.
+- Full typing with `py.typed`, and an error taxonomy that branches on
+  `err.code` so an unrecognised problem code from a newer API cannot break an
+  older client.
+
+### Notes
+
+- Two error class names differ from the JavaScript SDK because the literal
+  translations shadow `OSError` builtins: `WaitTimeoutError` (not
+  `TimeoutError`) and `TransportError` (not `ConnectionError`).
+- `ignore_existing` carries a one-second ambiguity that cannot be removed —
+  `receivedAt` on the wire has one-second granularity. It resolves by excluding,
+  because including risks silently returning the stale code the flag exists to
+  avoid. See `MessageFilter.ignore_existing`.
+
+[Unreleased]: https://github.com/nowtempmail/nowtempmail-python/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/nowtempmail/nowtempmail-python/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/nowtempmail/nowtempmail-python/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/nowtempmail/nowtempmail-python/releases/tag/v0.1.0

nowtempmail-0.1.2/LICENSE

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

nowtempmail-0.1.2/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.5
+Name: nowtempmail
+Version: 0.1.2
+Summary: Disposable mailboxes and OTP codes for your tests. Verification codes are extracted server-side, so there is no regex to write.
+Project-URL: Homepage, https://nowtempmail.com/developers
+Project-URL: Documentation, https://nowtempmail.com/developers
+Project-URL: Source, https://github.com/nowtempmail/nowtempmail-python
+Project-URL: Changelog, https://github.com/nowtempmail/nowtempmail-python/blob/main/CHANGELOG.md
+Project-URL: Issues, https://nowtempmail.userjot.com
+Author: NowTempMail
+License: MIT License
+        
+        Copyright (c) 2026 NowTempMail
+        
+        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.
+License-File: LICENSE
+Keywords: disposable-email,e2e,email,otp,playwright,pytest,qa,selenium,temp-mail,testing,verification-code
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nowtempmail
+
+Disposable mailboxes and OTP codes for your tests. **Verification codes are
+extracted server-side, so there is no regex to write.**
+
+```bash
+pip install pytest-nowtempmail     # the fixtures (most people want this)
+pip install nowtempmail            # the client on its own
+```
+
+```python
+def test_signup(page, ntm_inbox):
+    page.goto("/signup")
+    page.fill("#email", ntm_inbox.address)
+    page.click("text=Create account")
+    page.fill("#code", ntm_inbox.wait_for_code())  # only this test's mail
+```
+
+Get a key at <https://nowtempmail.com/developers> and set `NTM_API_KEY`. There is
+no config file and no `login` command — a key on a command line ends up in `ps`
+output and shell history.
+
+**Zero runtime dependencies.** This installs into test environments that already
+hold pytest, Playwright and usually an HTTP-client pin from some other SDK, so
+it deliberately brings nothing that could conflict with them.
+
+**Server-side only.** `/v1` rejects any request carrying an `Origin` header. This
+is a library for test runners, CI and backends — not for anything in a page.
+
+---
+
+## The fixtures
+
+| Fixture | Scope | What it is |
+|---|---|---|
+| `ntm_inbox` | session | One mailbox, shared by every test. **Start here.** |
+| `ntm_fresh_inbox` | function | A mailbox of this test's own. Costs quota — see below. |
+| `ntm_client` | session | The `NowTempMail` client. |
+| `ntm_options` | session | Resolved configuration, for overriding in a conftest. |
+
+### Why `ntm_inbox` is shared, and why that is safe
+
+`POST /v1/mailboxes` is the only endpoint that consumes daily quota, the counter
+increments on creation, and **it is never decremented on delete**. A per-test
+mailbox therefore spends the Free plan's 50 mailboxes/day inside a single CI
+run — the suite goes green locally, then starts failing with `quota_exceeded`
+partway through the third run of the afternoon, and the failure has nothing to
+do with the code that triggered it.
+
+Sharing is safe because **every wait is watermarked**. An autouse fixture
+re-stamps a boundary at the start of each test, and `wait_for_code()` /
+`wait_for_message()` default their `after` to it — so a code triggered by an
+earlier test is not a candidate.
+
+The watermark is floored to the whole second and set one second behind, because
+`received_at` on the wire has one-second granularity and a CI runner's clock is
+not the API's clock. **The consequence is a real limit:** two tests that trigger
+mail within about a second of each other are not isolated from one another. Fix
+that by disambiguating on content, which is what you want anyway:
+
+```python
+code = ntm_inbox.wait_for_code(sender="github", subject="Sign in")
+```
+
+Use `ntm_fresh_inbox` only where sharing genuinely cannot work — a test
+asserting on an empty inbox, one that deletes messages out from under a sibling,
+or one needing a different domain or TTL. A 40-test file using it burns 40 of
+the Free plan's 50/day, and teardown does not give any of them back.
+
+### Configuration
+
+```toml
+[tool.pytest.ini_options]
+ntm_base_url = "https://nowtempmail.com"
+ntm_attach_body = false          # read "What reaches your CI report" first
+ntm_watermark_skew_ms = 1000
+ntm_mailbox_ttl_seconds = 3600
+ntm_mailbox_domain = ""          # empty = the rotation's choice
+```
+
+There is deliberately no `ntm_api_key` option. An API key in `pyproject.toml` is
+an API key in git.
+
+### What reaches your CI report
+
+When a wait matches, the message is recorded on the test — and on failure it is
+printed in the output, which is where "the wrong mail matched" actually gets
+diagnosed.
+
+**Bodies and links are withheld by default.** A report is zipped into an
+artifact, downloaded by whoever has repo read access, and pasted into issues; a
+password-reset link inside one is a live credential with a working expiry. What
+you get is sender, subject, timestamp, a link *count*, and the extracted codes.
+
+The codes are included deliberately even though they are secrets: a verification
+code is single-use, already spent by the time anyone reads the report, and it is
+the one value you cannot debug an OTP flow without.
+
+Set `ntm_attach_body = true` to include bodies and links, and treat the whole
+artifact as a secret if you do.
+
+---
+
+## The client on its own
+
+```python
+from nowtempmail import NowTempMail
+
+ntm = NowTempMail()  # reads NTM_API_KEY
+inbox = ntm.mailboxes.create()  # returns once it can RECEIVE
+sign_up(inbox.address)
+code = inbox.wait_for_code(sender="acme", timeout=120)
+```
+
+`mailboxes.create()` confirms the mailbox is readable before returning. The mail
+receiver drops inbound mail if its inbox lookup misses, so "created" and "able
+to receive" are not the same instant, and a handle returned before the second
+one hands you a race you cannot see.
+
+**Creation is never retried.** It is the only call that spends daily quota and
+the API has no idempotency key, so a transport failure raises
+`MailboxMayExistError` rather than quietly spending a second mailbox.
+
+### Waiting
+
+```python
+inbox.wait_for_code(
+    sender="github",  # substring, case-insensitive, or a compiled pattern
+    subject=re.compile(r"\d{6}"),
+    after=some_datetime,  # default: the mailbox's created_at
+    ignore_existing=True,  # for resend flows, where the stale code is the bug
+    timeout=120,
+    cancel=threading.Event(),
+)
+```
+
+`after` defaults to the mailbox's `created_at`, **not** to the moment you called.
+Mail routinely lands before anyone waits for it — a form submits, mail arrives in
+300ms, and the test gets around to waiting a second later. Defaulting to call
+time makes that message invisible and produces a flake nobody can reproduce.
+
+`wait_for_code()` never fetches a body: codes ride on the message summary
+because they are extracted at ingest. One request per poll, no message content
+transferred.
+
+A timeout raises `WaitTimeoutError` carrying **`messages_seen`** — the number
+that separates "nothing arrived" from "mail arrived but nothing matched".
+
+### Errors
+
+Branch on `err.code`, not on the class. The API may grow a problem code this
+package has never heard of, and an unrecognised one arrives on the base class
+carrying that code verbatim rather than being rewritten.
+
+```python
+from nowtempmail import NowTempMailError, QuotaExceededError
+
+try:
+    inbox = ntm.mailboxes.create()
+except QuotaExceededError as err:
+    print(err.retry_after)
+except NowTempMailError as err:
+    print(err.code, err.request_id)  # request_id is what support asks for
+```
+
+No error message, `repr()` or log line ever contains the API key.
+
+**Two class names differ from the JavaScript SDK**, because the literal
+translations shadow builtins that are `OSError` subclasses:
+
+| JavaScript | Python |
+|---|---|
+| `TimeoutError` | `WaitTimeoutError` |
+| `ConnectionError` | `TransportError` |
+
+---
+
+## Quota, plainly
+
+| | |
+|---|---|
+| Spends daily quota | `mailboxes.create()` — nothing else |
+| Refunded on delete | **No.** Never. |
+| Free plan | 50 mailboxes/day, 30 requests/minute |
+| Check what is left | `ntm.me().usage.mailboxes_remaining_today` |
+
+Polling `me()` is free: it runs in peek mode server-side and does not consume
+the budget it reports on.
+
+---
+
+## Links
+
+- Docs and keys — <https://nowtempmail.com/developers>
+- Source — <https://github.com/nowtempmail/nowtempmail-python>
+- Issues — <https://nowtempmail.userjot.com>
+
+MIT licensed.

nowtempmail-0.1.2/README.md

@@ -0,0 +1,198 @@
+# nowtempmail
+
+Disposable mailboxes and OTP codes for your tests. **Verification codes are
+extracted server-side, so there is no regex to write.**
+
+```bash
+pip install pytest-nowtempmail     # the fixtures (most people want this)
+pip install nowtempmail            # the client on its own
+```
+
+```python
+def test_signup(page, ntm_inbox):
+    page.goto("/signup")
+    page.fill("#email", ntm_inbox.address)
+    page.click("text=Create account")
+    page.fill("#code", ntm_inbox.wait_for_code())  # only this test's mail
+```
+
+Get a key at <https://nowtempmail.com/developers> and set `NTM_API_KEY`. There is
+no config file and no `login` command — a key on a command line ends up in `ps`
+output and shell history.
+
+**Zero runtime dependencies.** This installs into test environments that already
+hold pytest, Playwright and usually an HTTP-client pin from some other SDK, so
+it deliberately brings nothing that could conflict with them.
+
+**Server-side only.** `/v1` rejects any request carrying an `Origin` header. This
+is a library for test runners, CI and backends — not for anything in a page.
+
+---
+
+## The fixtures
+
+| Fixture | Scope | What it is |
+|---|---|---|
+| `ntm_inbox` | session | One mailbox, shared by every test. **Start here.** |
+| `ntm_fresh_inbox` | function | A mailbox of this test's own. Costs quota — see below. |
+| `ntm_client` | session | The `NowTempMail` client. |
+| `ntm_options` | session | Resolved configuration, for overriding in a conftest. |
+
+### Why `ntm_inbox` is shared, and why that is safe
+
+`POST /v1/mailboxes` is the only endpoint that consumes daily quota, the counter
+increments on creation, and **it is never decremented on delete**. A per-test
+mailbox therefore spends the Free plan's 50 mailboxes/day inside a single CI
+run — the suite goes green locally, then starts failing with `quota_exceeded`
+partway through the third run of the afternoon, and the failure has nothing to
+do with the code that triggered it.
+
+Sharing is safe because **every wait is watermarked**. An autouse fixture
+re-stamps a boundary at the start of each test, and `wait_for_code()` /
+`wait_for_message()` default their `after` to it — so a code triggered by an
+earlier test is not a candidate.
+
+The watermark is floored to the whole second and set one second behind, because
+`received_at` on the wire has one-second granularity and a CI runner's clock is
+not the API's clock. **The consequence is a real limit:** two tests that trigger
+mail within about a second of each other are not isolated from one another. Fix
+that by disambiguating on content, which is what you want anyway:
+
+```python
+code = ntm_inbox.wait_for_code(sender="github", subject="Sign in")
+```
+
+Use `ntm_fresh_inbox` only where sharing genuinely cannot work — a test
+asserting on an empty inbox, one that deletes messages out from under a sibling,
+or one needing a different domain or TTL. A 40-test file using it burns 40 of
+the Free plan's 50/day, and teardown does not give any of them back.
+
+### Configuration
+
+```toml
+[tool.pytest.ini_options]
+ntm_base_url = "https://nowtempmail.com"
+ntm_attach_body = false          # read "What reaches your CI report" first
+ntm_watermark_skew_ms = 1000
+ntm_mailbox_ttl_seconds = 3600
+ntm_mailbox_domain = ""          # empty = the rotation's choice
+```
+
+There is deliberately no `ntm_api_key` option. An API key in `pyproject.toml` is
+an API key in git.
+
+### What reaches your CI report
+
+When a wait matches, the message is recorded on the test — and on failure it is
+printed in the output, which is where "the wrong mail matched" actually gets
+diagnosed.
+
+**Bodies and links are withheld by default.** A report is zipped into an
+artifact, downloaded by whoever has repo read access, and pasted into issues; a
+password-reset link inside one is a live credential with a working expiry. What
+you get is sender, subject, timestamp, a link *count*, and the extracted codes.
+
+The codes are included deliberately even though they are secrets: a verification
+code is single-use, already spent by the time anyone reads the report, and it is
+the one value you cannot debug an OTP flow without.
+
+Set `ntm_attach_body = true` to include bodies and links, and treat the whole
+artifact as a secret if you do.
+
+---
+
+## The client on its own
+
+```python
+from nowtempmail import NowTempMail
+
+ntm = NowTempMail()  # reads NTM_API_KEY
+inbox = ntm.mailboxes.create()  # returns once it can RECEIVE
+sign_up(inbox.address)
+code = inbox.wait_for_code(sender="acme", timeout=120)
+```
+
+`mailboxes.create()` confirms the mailbox is readable before returning. The mail
+receiver drops inbound mail if its inbox lookup misses, so "created" and "able
+to receive" are not the same instant, and a handle returned before the second
+one hands you a race you cannot see.
+
+**Creation is never retried.** It is the only call that spends daily quota and
+the API has no idempotency key, so a transport failure raises
+`MailboxMayExistError` rather than quietly spending a second mailbox.
+
+### Waiting
+
+```python
+inbox.wait_for_code(
+    sender="github",  # substring, case-insensitive, or a compiled pattern
+    subject=re.compile(r"\d{6}"),
+    after=some_datetime,  # default: the mailbox's created_at
+    ignore_existing=True,  # for resend flows, where the stale code is the bug
+    timeout=120,
+    cancel=threading.Event(),
+)
+```
+
+`after` defaults to the mailbox's `created_at`, **not** to the moment you called.
+Mail routinely lands before anyone waits for it — a form submits, mail arrives in
+300ms, and the test gets around to waiting a second later. Defaulting to call
+time makes that message invisible and produces a flake nobody can reproduce.
+
+`wait_for_code()` never fetches a body: codes ride on the message summary
+because they are extracted at ingest. One request per poll, no message content
+transferred.
+
+A timeout raises `WaitTimeoutError` carrying **`messages_seen`** — the number
+that separates "nothing arrived" from "mail arrived but nothing matched".
+
+### Errors
+
+Branch on `err.code`, not on the class. The API may grow a problem code this
+package has never heard of, and an unrecognised one arrives on the base class
+carrying that code verbatim rather than being rewritten.
+
+```python
+from nowtempmail import NowTempMailError, QuotaExceededError
+
+try:
+    inbox = ntm.mailboxes.create()
+except QuotaExceededError as err:
+    print(err.retry_after)
+except NowTempMailError as err:
+    print(err.code, err.request_id)  # request_id is what support asks for
+```
+
+No error message, `repr()` or log line ever contains the API key.
+
+**Two class names differ from the JavaScript SDK**, because the literal
+translations shadow builtins that are `OSError` subclasses:
+
+| JavaScript | Python |
+|---|---|
+| `TimeoutError` | `WaitTimeoutError` |
+| `ConnectionError` | `TransportError` |
+
+---
+
+## Quota, plainly
+
+| | |
+|---|---|
+| Spends daily quota | `mailboxes.create()` — nothing else |
+| Refunded on delete | **No.** Never. |
+| Free plan | 50 mailboxes/day, 30 requests/minute |
+| Check what is left | `ntm.me().usage.mailboxes_remaining_today` |
+
+Polling `me()` is free: it runs in peek mode server-side and does not consume
+the budget it reports on.
+
+---
+
+## Links
+
+- Docs and keys — <https://nowtempmail.com/developers>
+- Source — <https://github.com/nowtempmail/nowtempmail-python>
+- Issues — <https://nowtempmail.userjot.com>
+
+MIT licensed.

nowtempmail-0.1.2/examples/signup_otp.py

@@ -0,0 +1,62 @@
+"""The client without pytest: create an inbox, wait for the code, tidy up.
+
+NTM_API_KEY=ntm_live_... python examples/signup_otp.py
+"""
+
+from __future__ import annotations
+
+import sys
+
+from nowtempmail import (
+    MailboxMayExistError,
+    NowTempMail,
+    QuotaExceededError,
+    WaitTimeoutError,
+)
+
+
+def main() -> int:
+    ntm = NowTempMail()  # reads NTM_API_KEY
+
+    account = ntm.me()  # free: peek mode, does not spend what it reports
+    left = account.usage.mailboxes_remaining_today
+    print(f"plan {account.plan.label}, {left} mailboxes left today")
+
+    try:
+        # Returns once the mailbox can actually RECEIVE, not merely once it
+        # exists -- mail arriving before that is dropped, not queued.
+        inbox = ntm.mailboxes.create(ttl_seconds=900)
+    except QuotaExceededError as err:
+        print(f"daily budget spent; resets at {err.retry_after}s", file=sys.stderr)
+        return 1
+    except MailboxMayExistError:
+        # The request went out and the outcome is unknowable. The SDK will not
+        # send a second one, because creation is the only call that spends quota
+        # and there is no idempotency key.
+        print("creation failed in transit -- check me() before retrying", file=sys.stderr)
+        return 1
+
+    print(f"address  {inbox.address}")
+    print(f"expires  {inbox.expires_at.isoformat()}")
+    if not inbox.confirmed:
+        print("warning: not readable yet; mail in the next second may be dropped", file=sys.stderr)
+
+    print("\nSend a message with a verification code to that address.")
+    try:
+        # Never fetches a body: codes are extracted server-side at ingest.
+        code = inbox.wait_for_code(timeout=180)
+    except WaitTimeoutError as err:
+        # messages_seen is the number that matters -- it separates "nothing
+        # arrived" from "mail arrived but nothing matched".
+        print(f"\ngave up: {err.message}", file=sys.stderr)
+        return 4
+
+    print(f"\ncode     {code}")
+
+    deleted = inbox.delete()
+    print(f"deleted  {deleted} message(s) -- quota is NOT refunded")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())