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.
- verifyinboxes-0.1.0/.gitignore +14 -0
- verifyinboxes-0.1.0/LICENSE +21 -0
- verifyinboxes-0.1.0/PKG-INFO +488 -0
- verifyinboxes-0.1.0/README.md +462 -0
- verifyinboxes-0.1.0/SECURITY.md +20 -0
- verifyinboxes-0.1.0/examples/list_from_csv.py +45 -0
- verifyinboxes-0.1.0/examples/quickstart.py +39 -0
- verifyinboxes-0.1.0/examples/webhook_receiver.py +49 -0
- verifyinboxes-0.1.0/pyproject.toml +56 -0
- verifyinboxes-0.1.0/src/verifyinboxes/__init__.py +102 -0
- verifyinboxes-0.1.0/src/verifyinboxes/_base.py +599 -0
- verifyinboxes-0.1.0/src/verifyinboxes/_client.py +364 -0
- verifyinboxes-0.1.0/src/verifyinboxes/_exceptions.py +164 -0
- verifyinboxes-0.1.0/src/verifyinboxes/_models.py +373 -0
- verifyinboxes-0.1.0/src/verifyinboxes/_pagination.py +50 -0
- verifyinboxes-0.1.0/src/verifyinboxes/_resources.py +929 -0
- verifyinboxes-0.1.0/src/verifyinboxes/_version.py +1 -0
- verifyinboxes-0.1.0/src/verifyinboxes/_webhooks.py +81 -0
- verifyinboxes-0.1.0/src/verifyinboxes/py.typed +0 -0
- verifyinboxes-0.1.0/tests/conformance/scenarios.json +3338 -0
- verifyinboxes-0.1.0/tests/conftest.py +135 -0
- verifyinboxes-0.1.0/tests/fakeapi.py +307 -0
- verifyinboxes-0.1.0/tests/test_async.py +263 -0
- verifyinboxes-0.1.0/tests/test_client.py +567 -0
- verifyinboxes-0.1.0/tests/test_conformance.py +289 -0
- verifyinboxes-0.1.0/tests/test_examples.py +45 -0
- verifyinboxes-0.1.0/tests/test_smoke.py +34 -0
- verifyinboxes-0.1.0/tests/test_version.py +22 -0
- verifyinboxes-0.1.0/tests/test_webhooks.py +68 -0
- verifyinboxes-0.1.0/uv.lock +538 -0
|
@@ -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
|
+
[](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).
|