verifyinboxes 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. verifyinboxes-0.1.0/.gitignore +14 -0
  2. verifyinboxes-0.1.0/LICENSE +21 -0
  3. verifyinboxes-0.1.0/PKG-INFO +488 -0
  4. verifyinboxes-0.1.0/README.md +462 -0
  5. verifyinboxes-0.1.0/SECURITY.md +20 -0
  6. verifyinboxes-0.1.0/examples/list_from_csv.py +45 -0
  7. verifyinboxes-0.1.0/examples/quickstart.py +39 -0
  8. verifyinboxes-0.1.0/examples/webhook_receiver.py +49 -0
  9. verifyinboxes-0.1.0/pyproject.toml +56 -0
  10. verifyinboxes-0.1.0/src/verifyinboxes/__init__.py +102 -0
  11. verifyinboxes-0.1.0/src/verifyinboxes/_base.py +599 -0
  12. verifyinboxes-0.1.0/src/verifyinboxes/_client.py +364 -0
  13. verifyinboxes-0.1.0/src/verifyinboxes/_exceptions.py +164 -0
  14. verifyinboxes-0.1.0/src/verifyinboxes/_models.py +373 -0
  15. verifyinboxes-0.1.0/src/verifyinboxes/_pagination.py +50 -0
  16. verifyinboxes-0.1.0/src/verifyinboxes/_resources.py +929 -0
  17. verifyinboxes-0.1.0/src/verifyinboxes/_version.py +1 -0
  18. verifyinboxes-0.1.0/src/verifyinboxes/_webhooks.py +81 -0
  19. verifyinboxes-0.1.0/src/verifyinboxes/py.typed +0 -0
  20. verifyinboxes-0.1.0/tests/conformance/scenarios.json +3338 -0
  21. verifyinboxes-0.1.0/tests/conftest.py +135 -0
  22. verifyinboxes-0.1.0/tests/fakeapi.py +307 -0
  23. verifyinboxes-0.1.0/tests/test_async.py +263 -0
  24. verifyinboxes-0.1.0/tests/test_client.py +567 -0
  25. verifyinboxes-0.1.0/tests/test_conformance.py +289 -0
  26. verifyinboxes-0.1.0/tests/test_examples.py +45 -0
  27. verifyinboxes-0.1.0/tests/test_smoke.py +34 -0
  28. verifyinboxes-0.1.0/tests/test_version.py +22 -0
  29. verifyinboxes-0.1.0/tests/test_webhooks.py +68 -0
  30. verifyinboxes-0.1.0/uv.lock +538 -0
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ /dist/
5
+ /build/
6
+ .venv/
7
+ .venv-*/
8
+ .mypy_cache/
9
+ .pytest_cache/
10
+ .ruff_cache/
11
+ .coverage
12
+ htmlcov/
13
+ .idea/
14
+ .vscode/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 VerifyInboxes
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,488 @@
1
+ Metadata-Version: 2.5
2
+ Name: verifyinboxes
3
+ Version: 0.1.0
4
+ Summary: The official Python library for the VerifyInboxes API
5
+ Project-URL: Homepage, https://verifyinboxes.com
6
+ Project-URL: Repository, https://github.com/verifyinboxes/verifyinboxes-python
7
+ Project-URL: Issues, https://github.com/verifyinboxes/verifyinboxes-python/issues
8
+ Author-email: VerifyInboxes <developers@verifyinboxes.com>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: api,email,email verification,verifyinboxes
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: >=3.9
24
+ Requires-Dist: httpx<1,>=0.23
25
+ Description-Content-Type: text/markdown
26
+
27
+ # VerifyInboxes Python library
28
+
29
+ [![CI](https://github.com/verifyinboxes/verifyinboxes-python/actions/workflows/ci.yml/badge.svg)](https://github.com/verifyinboxes/verifyinboxes-python/actions/workflows/ci.yml)
30
+
31
+ The official Python library for the [VerifyInboxes](https://verifyinboxes.com) API: check whether email addresses
32
+ can receive mail, one at a time or as lists of any size, and read the results.
33
+
34
+ - Sync and async clients with the same surface
35
+ - Typed models and typed errors; ships `py.typed`
36
+ - Retries that never charge twice, waiting for checks and lists, results read page by page
37
+ - Webhook signature checks
38
+ - One runtime dependency: [`httpx`](https://www.python-httpx.org/)
39
+ - Python 3.9+
40
+
41
+ ## Install
42
+
43
+ ```bash
44
+ pip install verifyinboxes
45
+ ```
46
+
47
+ ## Quickstart
48
+
49
+ An organisation admin makes an API key in the VerifyInboxes app under **Developers** → **API keys**. Put it in the
50
+ environment:
51
+
52
+ ```bash
53
+ export VERIFYINBOXES_API_KEY="bv_..."
54
+ ```
55
+
56
+ ```python
57
+ from verifyinboxes import VerifyInboxes
58
+
59
+ client = VerifyInboxes() # reads VERIFYINBOXES_API_KEY
60
+
61
+ result = client.verify("ann@example.com")
62
+ print(result.verdict) # "valid", "invalid", "catch_all", "risky" or "unknown"
63
+ print(result.safe_to_send) # True or False
64
+ print(result.reason) # why, e.g. "mailbox_not_found"
65
+ print(result.job_id) # the check's job
66
+
67
+ for result in client.verify_many(["bob@example.com", "cat@example.com"]):
68
+ print(result.email, result.verdict)
69
+ ```
70
+
71
+ ## The client
72
+
73
+ ```python
74
+ from verifyinboxes import VerifyInboxes
75
+
76
+ client = VerifyInboxes(
77
+ api_key="bv_...", # default: the VERIFYINBOXES_API_KEY environment variable
78
+ base_url="https://api.verifyinboxes.com", # default: VERIFYINBOXES_BASE_URL, else this
79
+ timeout=60.0, # seconds one attempt of one request may take
80
+ max_retries=2, # see "Retries"
81
+ user_agent="my-app/1.2", # put in front of verifyinboxes-python/<version>
82
+ )
83
+ ```
84
+
85
+ Without a key, the constructor raises `MissingAPIKeyError`; a key with a space or a control character in it (half
86
+ of a copy and paste) raises `ValueError`. Keep the key out of your code: the environment variable is the place for
87
+ it. The client never logs it, and `repr(client)` shows only its first 6 characters.
88
+
89
+ The client holds a connection pool. Use it as a context manager, or call `client.close()` when you are done:
90
+
91
+ ```python
92
+ with VerifyInboxes() as client:
93
+ print(client.account.get().balance)
94
+ ```
95
+
96
+ To bring your own `httpx.Client` (a proxy, TLS settings), pass `http_client=...`. The library does not close a
97
+ client it did not make.
98
+
99
+ ### Personal access tokens
100
+
101
+ Where an API key works, so does a personal access token (`vi_at_...`): what an app gets when a person signs in to it
102
+ with their VerifyInboxes account. It acts as that person, with their role in the organisation they chose, and lives
103
+ an hour; after that the API answers `401` (`AuthenticationError`) and the app signs in again or uses its refresh
104
+ token. Pass it as the key:
105
+
106
+ ```python
107
+ client = VerifyInboxes(access_token)
108
+ ```
109
+
110
+ ## Checking addresses
111
+
112
+ ### One address
113
+
114
+ ```python
115
+ result = client.verify("ann@example.com")
116
+ result = client.verify("ann@example.com", force_recheck=True) # skip the cache
117
+ ```
118
+
119
+ The API answers within about 5 seconds, or says the check is still running; then the client asks every 2 seconds
120
+ until it is done, for up to `timeout` seconds (default 60). Every result names its job (`result.job_id`): a
121
+ `catch_all` or `risky` one can later be sent to `client.lists.resolve(result.job_id)`.
122
+
123
+ | `Result` field | |
124
+ | --- | --- |
125
+ | `email` | The address, as checked. |
126
+ | `verdict` | `valid`, `invalid`, `catch_all`, `risky` or `unknown`. |
127
+ | `safe_to_send` | Whether to send to it: `valid`, or a `catch_all` whose score reaches your organisation's threshold. |
128
+ | `score` | For a `catch_all` verdict, the probability that the mailbox exists (0 to 1), else `None`. |
129
+ | `reason` | Why: `mailbox_exists`, `mailbox_not_found`, `no_mail_server`, `accept_all`, `syntax`, `typo`, ... |
130
+ | `did_you_mean` | For a `typo`: the address it probably is. |
131
+ | `flags` | `disposable`, `role`, `free_provider`, `gateway`. |
132
+ | `provider`, `catch_all_domain`, `source`, `verified_at` | The domain's mail provider, whether it accepts every address, where the answer came from, and when. |
133
+ | `job_id` | The job that holds the result. |
134
+
135
+ The API adds verdicts, reasons and flags over time: a value you do not know is kept as the string it is, never an
136
+ error. Show it, and act on `safe_to_send`.
137
+
138
+ ### Waiting, and picking a check up again
139
+
140
+ A check that has not finished when `timeout` runs out raises `WaitTimeoutError`. The check carries on, and the error
141
+ names its job in `job_ids`, so nothing is lost:
142
+
143
+ ```python
144
+ from verifyinboxes import WaitTimeoutError
145
+
146
+ try:
147
+ result = client.verify("ann@example.com", timeout=10)
148
+ except WaitTimeoutError as error:
149
+ job_id = error.job_ids[0]
150
+ ...
151
+ result = client.checks.wait(job_id) # later: picks it up where it was
152
+ ```
153
+
154
+ `wait=False` does not wait at all: you get the result, or a `PendingCheck` with its `job_id`.
155
+
156
+ ```python
157
+ from verifyinboxes import PendingCheck
158
+
159
+ started = client.verify("ann@example.com", wait=False)
160
+ if isinstance(started, PendingCheck):
161
+ result = client.checks.wait(started.job_id, timeout=120)
162
+
163
+ job = client.checks.get(job_id) # the job as it is now; job.result once it is done
164
+ ```
165
+
166
+ ### Many addresses
167
+
168
+ **Never check many addresses with a loop of `verify`.** Checks go ahead of lists only up to 10 running at once:
169
+ past that, your checks wait behind other work, and a loop gains nothing over the ways below.
170
+
171
+ `verify_many` returns the results in the order of its input:
172
+
173
+ ```python
174
+ results = client.verify_many(addresses, timeout=600)
175
+ ```
176
+
177
+ Up to 10 addresses are checked one by one, together. More go as one list (below), which the call waits for and
178
+ reads back; every result's `job_id` is then the list's. For a large or long-running batch, use a list yourself.
179
+
180
+ ### Lists
181
+
182
+ ```python
183
+ created = client.lists.create(file="prospects.csv", email_column="email") # a path, bytes or a binary file
184
+ created = client.lists.create(csv="email\nann@example.com\n") # a CSV's text
185
+ created = client.lists.create(emails=["ann@example.com", "bob@example.com"])
186
+
187
+ job = client.lists.wait(created.id) # asks at once, then after 2, 4, 8, 16 and every 30 seconds
188
+ print(job.status, job.counts) # "done", VerdictCounts(valid=..., invalid=..., ...)
189
+ ```
190
+
191
+ **How long a list takes.** A few hundred addresses take minutes, and Microsoft-hosted ones longer. `lists.wait` has no
192
+ time limit unless you give one; `lists.wait(id, timeout=...)` raises `WaitTimeoutError` (the list carries on), and
193
+ `lists.wait(id)` picks it up again at any time. Instead of waiting, you can be told: see "Webhooks" below.
194
+
195
+ The results, every row once and in order, read a page at a time as you iterate:
196
+
197
+ ```python
198
+ for row in client.lists.results(created.id):
199
+ print(row.row, row.email, row.verdict, row.safe_to_send)
200
+
201
+ client.lists.results(created.id, only_safe_to_send=True)
202
+ client.lists.results(created.id, verdicts=["valid", "catch_all"])
203
+ client.lists.results(created.id, partial=True) # a list still running, as it stands
204
+ ```
205
+
206
+ To keep your own cursor (to resume elsewhere), read one page at a time:
207
+
208
+ ```python
209
+ page = client.lists.results_page(created.id, page_size=1000)
210
+ while True:
211
+ save(page.data)
212
+ if page.next_cursor is None:
213
+ break
214
+ page = client.lists.results_page(created.id, cursor=page.next_cursor, page_size=1000)
215
+ ```
216
+
217
+ A page may hold fewer rows than asked, even none, before the last one: follow `next_cursor` until it is `None`.
218
+
219
+ The CSV you sent, with the results appended:
220
+
221
+ ```python
222
+ written = client.lists.download(created.id, "results.csv") # bytes written
223
+ client.lists.download(created.id, "safe.csv", only_safe_to_send=True)
224
+ with open("results.csv", "wb") as out:
225
+ client.lists.download(created.id, out)
226
+ ```
227
+
228
+ A download to a path is written beside it and renamed over it once whole: if it fails, the file that was there is
229
+ untouched.
230
+
231
+ `client.lists.get(id)` is the list as it is now.
232
+
233
+ ### Catch-all resolution
234
+
235
+ For an organisation allowed to send test emails, the `catch_all` and `risky` addresses of a finished list or check
236
+ can be settled by a test email. Most are settled within about 3 days of sending, some take up to 7 days. One request
237
+ takes at most 500 addresses (more is refused with `too_many_to_resolve`): for a list with more, name them in parts of
238
+ at most 500:
239
+
240
+ ```python
241
+ resolution = client.lists.resolve(created.id) # all of them, if at most 500
242
+ resolution = client.lists.resolve(created.id, emails=["bob@example.com"]) # some (at most 500)
243
+ job = client.lists.wait(resolution.id)
244
+ ```
245
+
246
+ ## Everything else
247
+
248
+ ```python
249
+ account = client.account.get() # name, balance, reviewed, test_emails, safe_to_send_threshold
250
+
251
+ domain = client.domains.get("example.com") # provider, mx_hosts, catch_all, email_pattern, ... (1 credit)
252
+
253
+ client.suppressions.add(emails=["ann@example.com"], domains=["competitor.example"]) # -> how many were added
254
+ client.suppressions.remove(emails=["ann@example.com"]) # -> how many were removed
255
+ client.suppressions.list() # domains, and the number of addresses (kept only as a hash)
256
+
257
+ created = client.webhooks.create("https://example.com/webhooks/verifyinboxes", events=["job.completed"])
258
+ created.secret # shown only now: store it
259
+ client.webhooks.list()
260
+ client.webhooks.delete(created.id)
261
+
262
+ page = client.notices.list(after=last_seen, limit=100) # verdicts you bought, overturned since
263
+ last_seen = page.next_after
264
+
265
+ from verifyinboxes import FeedbackEvent
266
+ client.feedback.report([FeedbackEvent(email="ann@example.com", type="hard_bounce",
267
+ observed_at="2026-11-04T10:00:00Z", dsn_code="5.1.1", event_id="b-1")])
268
+
269
+ hook = client.integrations.create("instantly", label="main workspace")
270
+ hook.url # shown only now: paste it into the provider
271
+ client.integrations.list()
272
+ client.integrations.delete(hook.id)
273
+ ```
274
+
275
+ ## Errors
276
+
277
+ ```text
278
+ VerifyInboxesError the base of all; also "the API broke its own rules"
279
+ ├── MissingAPIKeyError no key given and VERIFYINBOXES_API_KEY not set
280
+ ├── APIConnectionError the request got no answer
281
+ │ └── APITimeoutError ... in time
282
+ ├── APIError the API answered with an error (any other 4xx)
283
+ │ ├── InvalidRequestError 400, 413, 414, 415, 422
284
+ │ ├── AuthenticationError 401
285
+ │ ├── InsufficientCreditsError 402
286
+ │ ├── PermissionDeniedError 403
287
+ │ ├── NotFoundError 404, 410
288
+ │ ├── ConflictError 409
289
+ │ ├── RateLimitError 429
290
+ │ └── ServerError 5xx
291
+ └── WaitTimeoutError a check or a list was still running when the time to wait ran out
292
+ ```
293
+
294
+ An `APIError` carries what the API said, and the request id support asks for:
295
+
296
+ ```python
297
+ import verifyinboxes
298
+
299
+ try:
300
+ client.lists.create(file="prospects.csv")
301
+ except verifyinboxes.InsufficientCreditsError:
302
+ print("top up first")
303
+ except verifyinboxes.APIError as error:
304
+ print(error.status) # 422
305
+ print(error.code) # "consumer_list" <- match on this
306
+ print(error.message) # a sentence for a person
307
+ print(error.request_id) # the answer's X-Request-Id: quote it when you write to support
308
+ print(error) # "422 consumer_list: ... (request id 019a...)"
309
+ ```
310
+
311
+ | Attribute | |
312
+ | --- | --- |
313
+ | `status` | The HTTP status. |
314
+ | `code` | The API's error code, or `None` when the answer was not the API's (a proxy's error page). Match on it; treat one you do not know by its status. |
315
+ | `message` | A sentence for a person. Show it or log it; do not parse it. |
316
+ | `request_id` | The answer's `X-Request-Id`. After retries, the last answer's. |
317
+ | `retry_after` | The answer's `Retry-After`, in seconds, when it had one. |
318
+ | `body` | The answer's JSON body. |
319
+ | `job_ids` | On every error: the jobs the call had made when it failed. |
320
+
321
+ **`job_ids`.** Every error raised while waiting, and by `verify_many`, names every job the call made, in the order
322
+ of its input. Those jobs carry on, and the credits they hold are spent on them: pick them up with
323
+ `client.checks.wait(job_id)` or `client.lists.wait(job_id)` instead of starting again.
324
+
325
+ When `verify` or `verify_many` is interrupted instead (Ctrl-C, a cancelled task, a timeout around it), it names the
326
+ jobs it made in a warning on the `verifyinboxes` logger ("interrupted; still running: ...") and on the exception, as
327
+ `job_ids` (and as a note on Python 3.11 and later), before the exception goes on. The exception you catch does not
328
+ always carry them: on Python 3.9 and 3.10 the `CancelledError` a cancelled task raises to whoever awaits it is a new
329
+ one, without `job_ids`, and a timeout around the call (`asyncio.wait_for`) raises a `TimeoutError` without them on
330
+ every version. The warning names them in every case.
331
+
332
+ A request that starts a check or `verify_many`'s list and may have reached the API is let finish first, so that its
333
+ job is known: a cancelled task waits for the attempt on its way (at most the client's `timeout`, or the rest of a
334
+ pause before a retry), and so does Ctrl-C during `verify_many`, whose requests run in threads of their own. Nothing
335
+ is sent after that attempt: if it fails, it is not retried, and a job it may have made is not named. A second
336
+ interruption stops waiting. Ctrl-C during the request of a plain `verify` (sync) cuts it off: if it had reached the
337
+ API, the check exists but is not named.
338
+
339
+ Errors can be pickled and copied with everything on them, so they cross a process pool or a task queue whole.
340
+
341
+ ## Retries
342
+
343
+ A request that fails in a way worth retrying is sent again, up to `max_retries` times (default 2):
344
+
345
+ | Failure | Retried |
346
+ | --- | --- |
347
+ | No answer: the connection failed, was reset or closed, or timed out | Yes |
348
+ | `429` | Yes, after `Retry-After` |
349
+ | `409 idempotency_in_progress` | Yes, after `Retry-After` |
350
+ | `5xx` | Yes |
351
+ | Any other `4xx` | No: the same request would get the same answer |
352
+
353
+ The wait is the answer's `Retry-After` when it has one. A `Retry-After` over 60 seconds is not waited for: the error
354
+ is raised at once, with the wait on `.retry_after`. Otherwise it backs off exponentially, with jitter: up to half a
355
+ second before the first retry, up to a second before the second, doubling to at most eight. Once its call is
356
+ interrupted (Ctrl-C, a cancelled task), a request is not retried: see **`job_ids`** above.
357
+
358
+ **Nothing is charged twice.** Every `POST` carries an `Idempotency-Key`, the same on every attempt of one call.
359
+ When an answer is lost after the API ran the request (a check, a list, an upload, a resolution, feedback, a
360
+ suppression), the retry gets the first answer again: one job, charged once.
361
+
362
+ A `409 idempotency_in_progress` (`ConflictError`) left after the retries means the first request with that key is
363
+ still running on the API. Repeat the call later with your own `idempotency_key`, the same one: the API then answers
364
+ with what the first request answered, and runs nothing twice. (Without a key of your own, each call makes a new one,
365
+ which cannot be sent again: pass your own where a repeat matters.)
366
+
367
+ Your own key makes one request safe to send again after your program restarts. A key names **one** request, and the
368
+ API keeps its answer for 24 hours: in that time the same key gets that answer again, whatever you send with it. An
369
+ upload is known by its key alone, never by its file, so another file under a used key gets the first file's list;
370
+ and an error is kept like any answer, so a `402` stays a `402` under its key. So make the key from the request
371
+ itself, and give a new file, or a retry after you topped up, a new key:
372
+
373
+ ```python
374
+ import hashlib
375
+
376
+ client.verify("ann@example.com", idempotency_key=f"order-{order_id}") # one key per order
377
+
378
+ with open("prospects.csv", "rb") as f:
379
+ digest = hashlib.sha256(f.read()).hexdigest()
380
+ client.lists.create(file="prospects.csv", idempotency_key=f"import-{digest}") # one key per file
381
+ ```
382
+
383
+ A file is sent again whole: a path is opened again, a seekable file rewound to where it was. A stream that can be
384
+ read only once is not sent again once it began to be read.
385
+
386
+ Two requests are not sent again once they may have arrived: `webhooks.create` and `integrations.create`, whose
387
+ answers hold a secret shown once. They are retried only when the connection was never made, or after a `429`; after
388
+ an `APIConnectionError`, look at `webhooks.list()` or `integrations.list()` before making another. A `DELETE` whose
389
+ answer was lost is sent again; if the retry finds it gone, the first one did it.
390
+
391
+ ```python
392
+ client = VerifyInboxes(max_retries=0) # never retry
393
+ ```
394
+
395
+ ## Webhooks
396
+
397
+ A webhook gets a `POST` when a list finishes (`job.completed`) and when a verdict you bought is overturned
398
+ (`address.contradicted`). Check its signature before you read anything in it, against the raw body as it arrived:
399
+
400
+ ```python
401
+ from verifyinboxes import verify_signature
402
+
403
+ if not verify_signature(raw_body, headers["X-Boxverifier-Signature"], secret):
404
+ return 400 # not from VerifyInboxes, changed on the way, or older than 5 minutes
405
+ event = json.loads(raw_body)
406
+ ```
407
+
408
+ `secret` is the 64 characters `webhooks.create` returned. A signature more than `tolerance` seconds (default 300)
409
+ from your clock is refused, so an old delivery cannot be sent again. It never raises: anything it cannot read is
410
+ `False`. It needs no client and no key, and `client.webhooks.verify_signature` is the same function. Deliveries come
411
+ at least once: `X-Boxverifier-Delivery` is the same on every retry of one, to drop duplicates. The two header names
412
+ are `verifyinboxes.SIGNATURE_HEADER` and `verifyinboxes.DELIVERY_HEADER`.
413
+
414
+ ## Async
415
+
416
+ `AsyncVerifyInboxes` has the same resources, methods and arguments; every call is awaited, and results are read
417
+ with `async for`. Up to 10 addresses of `verify_many` are sent together with `asyncio.gather`.
418
+
419
+ ```python
420
+ import asyncio
421
+ from verifyinboxes import AsyncVerifyInboxes
422
+
423
+
424
+ async def main() -> None:
425
+ async with AsyncVerifyInboxes() as client:
426
+ result = await client.verify("ann@example.com")
427
+ results = await client.verify_many(["ann@example.com", "bob@example.com"])
428
+
429
+ created = await client.lists.create(file="prospects.csv")
430
+ await client.lists.wait(created.id)
431
+ async for row in client.lists.results(created.id):
432
+ print(row.email, row.verdict)
433
+
434
+
435
+ asyncio.run(main())
436
+ ```
437
+
438
+ ## Models
439
+
440
+ Answers are frozen dataclasses named after the API's schemas (`Result`, `Job`, `JobCreated`, `ResultRow`,
441
+ `Domain`, ...), with the API's field names. Timestamps are ISO 8601 strings. `to_dict()` gives the fields back as
442
+ the API names them; a field this version does not know is left out, never an error. `WebhookCreated.secret` and
443
+ `IntegrationCreated.url` are left out of `repr()`, and kept in `to_dict()`.
444
+
445
+ ## Logging
446
+
447
+ The library logs each request to the `verifyinboxes` logger at `DEBUG`: the method, the path, the status, the
448
+ request id and the attempt. Never a header, a body, or a download's query. At `WARNING` it logs only the jobs an
449
+ interrupted `verify_many` leaves running.
450
+
451
+ ```python
452
+ import logging
453
+ logging.basicConfig()
454
+ logging.getLogger("verifyinboxes").setLevel(logging.DEBUG)
455
+ ```
456
+
457
+ ## Examples
458
+
459
+ - [`examples/quickstart.py`](https://github.com/verifyinboxes/verifyinboxes-python/blob/main/examples/quickstart.py): one check, then several with `verify_many`.
460
+ - [`examples/list_from_csv.py`](https://github.com/verifyinboxes/verifyinboxes-python/blob/main/examples/list_from_csv.py): a list from a CSV: start it, wait, read the results,
461
+ download them.
462
+ - [`examples/webhook_receiver.py`](https://github.com/verifyinboxes/verifyinboxes-python/blob/main/examples/webhook_receiver.py): a webhook receiver on the standard library's HTTP
463
+ server, checking the signature before anything else.
464
+
465
+ ## Versioning
466
+
467
+ The library follows [semantic versioning](https://semver.org). It is `0.x` until the API's public launch, when it
468
+ becomes `1.0.0`; until then a minor version may change the library's surface, and the changes are listed in its
469
+ release notes. The API itself changes without breaking you: it adds fields, values and error codes, which this
470
+ library ignores or keeps as they are.
471
+
472
+ ## Development
473
+
474
+ ```bash
475
+ uv sync
476
+ uv run pytest # the tests, against a fake API on 127.0.0.1 (no network)
477
+ uv run mypy # the strict type check, of the package and the examples
478
+ uv build # the wheel and the source distribution
479
+ ```
480
+
481
+ `tests/conformance/scenarios.json` is shared by every official VerifyInboxes library: what each must send and do on
482
+ the wire (retries with the same `Idempotency-Key`, job ids kept on a timeout, request ids on errors, results through
483
+ empty pages, the webhook signature cases). `tests/test_conformance.py` replays it. `tests/test_smoke.py` runs against
484
+ the live API when `VERIFYINBOXES_SMOKE_API_KEY` holds a key (it spends a few credits).
485
+
486
+ ## Licence
487
+
488
+ MIT. See [LICENSE](https://github.com/verifyinboxes/verifyinboxes-python/blob/main/LICENSE). To report a security problem, see [SECURITY.md](https://github.com/verifyinboxes/verifyinboxes-python/blob/main/SECURITY.md).