receiverdotemail 2.0.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.
- receiverdotemail-2.0.0/PKG-INFO +301 -0
- receiverdotemail-2.0.0/README.md +272 -0
- receiverdotemail-2.0.0/pyproject.toml +62 -0
- receiverdotemail-2.0.0/receiverdotemail/__init__.py +40 -0
- receiverdotemail-2.0.0/receiverdotemail/_context.py +50 -0
- receiverdotemail-2.0.0/receiverdotemail/_sse.py +39 -0
- receiverdotemail-2.0.0/receiverdotemail/_utils.py +26 -0
- receiverdotemail-2.0.0/receiverdotemail/_version.py +3 -0
- receiverdotemail-2.0.0/receiverdotemail/client.py +91 -0
- receiverdotemail-2.0.0/receiverdotemail/errors.py +58 -0
- receiverdotemail-2.0.0/receiverdotemail/http.py +169 -0
- receiverdotemail-2.0.0/receiverdotemail/resources/__init__.py +12 -0
- receiverdotemail-2.0.0/receiverdotemail/resources/api_keys.py +85 -0
- receiverdotemail-2.0.0/receiverdotemail/resources/emails.py +492 -0
- receiverdotemail-2.0.0/receiverdotemail/resources/inboxes.py +37 -0
- receiverdotemail-2.0.0/receiverdotemail/resources/organizations.py +90 -0
- receiverdotemail-2.0.0/receiverdotemail/resources/projects.py +88 -0
- receiverdotemail-2.0.0/receiverdotemail/resources/webhooks.py +58 -0
- receiverdotemail-2.0.0/receiverdotemail/types/__init__.py +69 -0
- receiverdotemail-2.0.0/receiverdotemail/types/api_key.py +42 -0
- receiverdotemail-2.0.0/receiverdotemail/types/base.py +17 -0
- receiverdotemail-2.0.0/receiverdotemail/types/email.py +126 -0
- receiverdotemail-2.0.0/receiverdotemail/types/inbox.py +15 -0
- receiverdotemail-2.0.0/receiverdotemail/types/organization.py +64 -0
- receiverdotemail-2.0.0/receiverdotemail/types/project.py +27 -0
- receiverdotemail-2.0.0/receiverdotemail/types/webhook.py +48 -0
- receiverdotemail-2.0.0/receiverdotemail/types/whoami.py +44 -0
- receiverdotemail-2.0.0/receiverdotemail/webhooks.py +47 -0
- receiverdotemail-2.0.0/receiverdotemail.egg-info/PKG-INFO +301 -0
- receiverdotemail-2.0.0/receiverdotemail.egg-info/SOURCES.txt +35 -0
- receiverdotemail-2.0.0/receiverdotemail.egg-info/dependency_links.txt +1 -0
- receiverdotemail-2.0.0/receiverdotemail.egg-info/requires.txt +9 -0
- receiverdotemail-2.0.0/receiverdotemail.egg-info/top_level.txt +1 -0
- receiverdotemail-2.0.0/setup.cfg +4 -0
- receiverdotemail-2.0.0/tests/test_agent_api.py +446 -0
- receiverdotemail-2.0.0/tests/test_client.py +213 -0
- receiverdotemail-2.0.0/tests/test_webhooks.py +37 -0
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: receiverdotemail
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: Official Python SDK for Receiver.email: programmable email inboxes for tests and AI agents, with OTP and link extraction
|
|
5
|
+
Author-email: "Receiver.email" <support@receiver.email>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://receiver.email
|
|
8
|
+
Project-URL: Documentation, https://receiver.email/docs/sdks/python
|
|
9
|
+
Project-URL: Repository, https://github.com/BUW91/mailingestion/tree/main/packages/python-sdk
|
|
10
|
+
Project-URL: Issues, https://github.com/BUW91/mailingestion/issues
|
|
11
|
+
Keywords: receiverdotemail,receiver.email,email,email-testing,email-api,inbound-email,otp,2fa,magic-link,testing,test-automation,e2e-testing,pytest,playwright,ai-agents,disposable-email
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Requires-Python: >=3.9
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
Requires-Dist: httpx>=0.25.0
|
|
22
|
+
Requires-Dist: pydantic>=2.0.0
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
25
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
|
|
26
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
27
|
+
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
28
|
+
Requires-Dist: mypy>=1.0.0; extra == "dev"
|
|
29
|
+
|
|
30
|
+
# receiverdotemail
|
|
31
|
+
|
|
32
|
+
Official Python SDK for [Receiver.email](https://receiver.email): programmable email inboxes for end-to-end tests, AI agents and scripts. Create a unique address per test, trigger your sign-up, login or password-reset email, and get the OTP code or magic link back with one call. Built for pytest, Playwright for Python and CI.
|
|
33
|
+
|
|
34
|
+
Guides: [pytest](https://receiver.email/docs/guides/pytest) · [Playwright](https://receiver.email/docs/guides/playwright) · [OTP / 2FA](https://receiver.email/docs/guides/otp-verification) · [Magic links](https://receiver.email/docs/guides/magic-links) · [Password resets](https://receiver.email/docs/guides/password-reset)
|
|
35
|
+
|
|
36
|
+
## Features
|
|
37
|
+
|
|
38
|
+
- **Unique inboxes on demand**: mint an address per test or agent run with `inboxes.create()`
|
|
39
|
+
- **Waits of any length**: `wait_for` and `wait_for_otp` loop the API's 60 s long-poll for you
|
|
40
|
+
- **OTP extraction**: the code, plus every candidate code found, newest first
|
|
41
|
+
- **Live stream**: `async for` over new emails (Server-Sent Events, reconnects automatically)
|
|
42
|
+
- **Link extraction, filtering, pagination, webhooks**
|
|
43
|
+
- **Type-safe**: Pydantic models with snake_case attributes
|
|
44
|
+
- **Async/await** API built on `httpx`
|
|
45
|
+
|
|
46
|
+
## Installation
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
pip install receiverdotemail
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Quick Start
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
import asyncio
|
|
56
|
+
from receiverdotemail import ReceiverClient
|
|
57
|
+
|
|
58
|
+
async def main():
|
|
59
|
+
# Reads RECEIVER_API_KEY (and RECEIVER_API_URL, if set) from the environment
|
|
60
|
+
async with ReceiverClient() as receiver:
|
|
61
|
+
inbox = await receiver.inboxes.create(prefix="signup")
|
|
62
|
+
await my_app.sign_up(inbox.address)
|
|
63
|
+
|
|
64
|
+
otp = await receiver.emails.wait_for_otp(
|
|
65
|
+
recipient=inbox.address,
|
|
66
|
+
since=inbox.created_at,
|
|
67
|
+
timeout=60,
|
|
68
|
+
)
|
|
69
|
+
print(otp.code)
|
|
70
|
+
|
|
71
|
+
asyncio.run(main())
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
With an API key, `project_id` is optional on every email and inbox method: the SDK
|
|
75
|
+
calls `whoami()` once and caches the key's project. Pass `project_id=...` to skip that
|
|
76
|
+
call, or when authenticating with a dashboard session token.
|
|
77
|
+
|
|
78
|
+
## Configuration
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
client = ReceiverClient(
|
|
82
|
+
api_key="recv_live_...", # default: RECEIVER_API_KEY
|
|
83
|
+
base_url="https://api.receiver.email/api/v1", # default: RECEIVER_API_URL, else production
|
|
84
|
+
timeout=30, # HTTP timeout for ordinary requests (seconds)
|
|
85
|
+
user_agent="my-tool/1.0", # default: receiver-sdk-py/<version>
|
|
86
|
+
project_id="proj_abc123", # default: RECEIVER_PROJECT_ID, else looked up once via whoami()
|
|
87
|
+
)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
A missing API key raises `ReceiverError` with `code == "MISSING_API_KEY"`.
|
|
91
|
+
|
|
92
|
+
## Usage
|
|
93
|
+
|
|
94
|
+
### Who am I
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
me = await client.whoami()
|
|
98
|
+
print(me.auth_type) # "apikey" or "jwt"
|
|
99
|
+
print(me.project.email_suffix) # -a3kx9p2m@receiver.email
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Create an inbox
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
inbox = await client.inboxes.create(prefix="reset") # prefix is optional
|
|
106
|
+
print(inbox.address) # reset-k2m9qa-a3kx9p2m@receiver.email
|
|
107
|
+
print(inbox.created_at) # pass as `since` when waiting
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Nothing is stored until mail arrives. Always build addresses this way (or from
|
|
111
|
+
`project.email_suffix`), never by hand.
|
|
112
|
+
|
|
113
|
+
### `since`
|
|
114
|
+
|
|
115
|
+
`since` (a `datetime` or ISO string) matches mail received **strictly after** it.
|
|
116
|
+
Use `inbox.created_at` for the first email, and the previous email's `received_at`
|
|
117
|
+
for the next one. Naive datetimes are treated as local time. When omitted, waits
|
|
118
|
+
look back 60 seconds and `stream()` starts from now.
|
|
119
|
+
|
|
120
|
+
### Wait for an email
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
from receiverdotemail import ReceiverTimeoutError
|
|
124
|
+
|
|
125
|
+
try:
|
|
126
|
+
email = await client.emails.wait_for(
|
|
127
|
+
recipient=inbox.address,
|
|
128
|
+
subject="Reset", # substring, case-insensitive
|
|
129
|
+
since=inbox.created_at,
|
|
130
|
+
timeout=120, # any length; the SDK repeats 60 s server waits
|
|
131
|
+
)
|
|
132
|
+
reset_link = next(link for link in email.links if "reset" in link)
|
|
133
|
+
except ReceiverTimeoutError as e:
|
|
134
|
+
print(f"Nothing after {e.waited_seconds}s (since {e.since})")
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`wait_for` returns an `Email` (with `text_body` and `links`) or raises
|
|
138
|
+
`ReceiverTimeoutError`. It never returns `None`.
|
|
139
|
+
|
|
140
|
+
### One-time codes
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
otp = await client.emails.wait_for_otp(recipient=inbox.address, since=inbox.created_at, timeout=60)
|
|
144
|
+
print(otp.code, otp.code_length, otp.source) # "123456", 6, "subject"
|
|
145
|
+
print([c.code for c in otp.candidates]) # every code found, newest first
|
|
146
|
+
|
|
147
|
+
# No waiting: returns None when nothing matches
|
|
148
|
+
otp = await client.emails.get_otp(recipient=inbox.address, code_length=6)
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Stream new emails
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
async for event in client.emails.stream(recipient=inbox.address):
|
|
155
|
+
print(event.email.subject, event.email.links)
|
|
156
|
+
if event.otp:
|
|
157
|
+
print(event.otp.code)
|
|
158
|
+
break # stop whenever you like
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
The server closes each connection after about 55 seconds; the SDK reconnects with
|
|
162
|
+
the `since` it reports, so no email is missed or repeated.
|
|
163
|
+
|
|
164
|
+
### Send a test email
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
await client.emails.send_test(to=inbox.address) # "Your Receiver.email test code: 123456"
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### List, get and delete emails
|
|
171
|
+
|
|
172
|
+
```python
|
|
173
|
+
response = await client.emails.list(recipient=inbox.address, limit=50)
|
|
174
|
+
for email in response.emails:
|
|
175
|
+
print(email.subject)
|
|
176
|
+
|
|
177
|
+
async for email in client.emails.list_all(sender="noreply@example.com"):
|
|
178
|
+
...
|
|
179
|
+
|
|
180
|
+
email = await client.emails.get("email_xyz789") # or get("proj_abc123", "email_xyz789")
|
|
181
|
+
print(email.text_body, email.html_body, email.attachments)
|
|
182
|
+
|
|
183
|
+
await client.emails.delete("email_xyz789")
|
|
184
|
+
|
|
185
|
+
emails = await client.emails.find_by_subject("Password Reset")
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Webhooks (dashboard session only)
|
|
189
|
+
|
|
190
|
+
Webhook management needs a dashboard session token; API keys get `403`.
|
|
191
|
+
|
|
192
|
+
```python
|
|
193
|
+
hook = await client.webhooks.create("proj_abc123", "https://ci.example.com/hooks/receiver")
|
|
194
|
+
print(hook.secret) # whsec_..., shown once
|
|
195
|
+
|
|
196
|
+
hooks = await client.webhooks.list("proj_abc123") # List[Webhook]
|
|
197
|
+
delivery = await client.webhooks.test("proj_abc123", hook.id)
|
|
198
|
+
deliveries = await client.webhooks.deliveries("proj_abc123", hook.id) # last 50
|
|
199
|
+
await client.webhooks.delete("proj_abc123", hook.id)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Verify each delivery in your receiver with the raw request body:
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
from receiverdotemail import verify_webhook_signature
|
|
206
|
+
|
|
207
|
+
if not verify_webhook_signature(secret, request.headers["Receiver-Signature"], raw_body):
|
|
208
|
+
return 400
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### Projects, organizations and API keys
|
|
212
|
+
|
|
213
|
+
```python
|
|
214
|
+
projects = await client.projects.list("org_abc123")
|
|
215
|
+
project = await client.projects.get("proj_abc123")
|
|
216
|
+
await client.projects.create(organization_id="org_abc123", name="CI Tests")
|
|
217
|
+
|
|
218
|
+
orgs = await client.organizations.list()
|
|
219
|
+
|
|
220
|
+
response = await client.api_keys.create(project_id="proj_abc123", name="CI Pipeline")
|
|
221
|
+
print(response.key) # Full key, only shown once!
|
|
222
|
+
await client.api_keys.revoke("proj_abc123", "key_xyz789")
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## Error Handling
|
|
226
|
+
|
|
227
|
+
```python
|
|
228
|
+
from receiverdotemail import (
|
|
229
|
+
ReceiverError,
|
|
230
|
+
ReceiverTimeoutError,
|
|
231
|
+
RateLimitError,
|
|
232
|
+
AuthenticationError,
|
|
233
|
+
NotFoundError,
|
|
234
|
+
)
|
|
235
|
+
|
|
236
|
+
try:
|
|
237
|
+
email = await client.emails.wait_for(recipient=inbox.address, timeout=30)
|
|
238
|
+
except ReceiverTimeoutError as e:
|
|
239
|
+
print(e.since, e.waited_seconds)
|
|
240
|
+
except RateLimitError as e:
|
|
241
|
+
print(f"Rate limited. Retry at: {e.reset_at}")
|
|
242
|
+
except AuthenticationError:
|
|
243
|
+
print("Invalid API key")
|
|
244
|
+
except NotFoundError:
|
|
245
|
+
print("Not found")
|
|
246
|
+
except ReceiverError as e:
|
|
247
|
+
print(e.message, e.status_code, e.code)
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
All errors derive from `ReceiverError`. `ReceiverTimeoutError` has `status_code == 408`
|
|
251
|
+
and `code == "WAIT_TIMEOUT"`.
|
|
252
|
+
|
|
253
|
+
## Pytest Integration
|
|
254
|
+
|
|
255
|
+
```python
|
|
256
|
+
import pytest
|
|
257
|
+
from receiverdotemail import ReceiverClient
|
|
258
|
+
|
|
259
|
+
@pytest.fixture
|
|
260
|
+
async def receiver():
|
|
261
|
+
async with ReceiverClient() as client: # RECEIVER_API_KEY from the environment
|
|
262
|
+
yield client
|
|
263
|
+
|
|
264
|
+
async def test_signup_email(receiver):
|
|
265
|
+
inbox = await receiver.inboxes.create(prefix="signup")
|
|
266
|
+
await my_app.signup(inbox.address)
|
|
267
|
+
|
|
268
|
+
email = await receiver.emails.wait_for(
|
|
269
|
+
recipient=inbox.address,
|
|
270
|
+
subject="Confirm your email",
|
|
271
|
+
since=inbox.created_at,
|
|
272
|
+
timeout=60,
|
|
273
|
+
)
|
|
274
|
+
assert any("confirm" in link for link in email.links)
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
## Upgrading from 1.x
|
|
278
|
+
|
|
279
|
+
See [CHANGELOG.md](CHANGELOG.md). In short: `wait_for` raises `ReceiverTimeoutError`
|
|
280
|
+
instead of returning `None`, `wait_for_otp` raises instead of returning `None`, and
|
|
281
|
+
`received_after` on waits is now `since` (the old name still works).
|
|
282
|
+
|
|
283
|
+
## Development
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
pip install -e ".[dev]"
|
|
287
|
+
pytest
|
|
288
|
+
mypy receiverdotemail
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
Or from the repo root: `./scripts/test.sh python-sdk`.
|
|
292
|
+
|
|
293
|
+
## License
|
|
294
|
+
|
|
295
|
+
MIT
|
|
296
|
+
|
|
297
|
+
## Support
|
|
298
|
+
|
|
299
|
+
- **Documentation**: https://docs.receiver.email
|
|
300
|
+
- **Email**: support@receiver.email
|
|
301
|
+
- **Issues**: https://github.com/receiverdotemail/sdk-python/issues
|
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
# receiverdotemail
|
|
2
|
+
|
|
3
|
+
Official Python SDK for [Receiver.email](https://receiver.email): programmable email inboxes for end-to-end tests, AI agents and scripts. Create a unique address per test, trigger your sign-up, login or password-reset email, and get the OTP code or magic link back with one call. Built for pytest, Playwright for Python and CI.
|
|
4
|
+
|
|
5
|
+
Guides: [pytest](https://receiver.email/docs/guides/pytest) · [Playwright](https://receiver.email/docs/guides/playwright) · [OTP / 2FA](https://receiver.email/docs/guides/otp-verification) · [Magic links](https://receiver.email/docs/guides/magic-links) · [Password resets](https://receiver.email/docs/guides/password-reset)
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- **Unique inboxes on demand**: mint an address per test or agent run with `inboxes.create()`
|
|
10
|
+
- **Waits of any length**: `wait_for` and `wait_for_otp` loop the API's 60 s long-poll for you
|
|
11
|
+
- **OTP extraction**: the code, plus every candidate code found, newest first
|
|
12
|
+
- **Live stream**: `async for` over new emails (Server-Sent Events, reconnects automatically)
|
|
13
|
+
- **Link extraction, filtering, pagination, webhooks**
|
|
14
|
+
- **Type-safe**: Pydantic models with snake_case attributes
|
|
15
|
+
- **Async/await** API built on `httpx`
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install receiverdotemail
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Quick Start
|
|
24
|
+
|
|
25
|
+
```python
|
|
26
|
+
import asyncio
|
|
27
|
+
from receiverdotemail import ReceiverClient
|
|
28
|
+
|
|
29
|
+
async def main():
|
|
30
|
+
# Reads RECEIVER_API_KEY (and RECEIVER_API_URL, if set) from the environment
|
|
31
|
+
async with ReceiverClient() as receiver:
|
|
32
|
+
inbox = await receiver.inboxes.create(prefix="signup")
|
|
33
|
+
await my_app.sign_up(inbox.address)
|
|
34
|
+
|
|
35
|
+
otp = await receiver.emails.wait_for_otp(
|
|
36
|
+
recipient=inbox.address,
|
|
37
|
+
since=inbox.created_at,
|
|
38
|
+
timeout=60,
|
|
39
|
+
)
|
|
40
|
+
print(otp.code)
|
|
41
|
+
|
|
42
|
+
asyncio.run(main())
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
With an API key, `project_id` is optional on every email and inbox method: the SDK
|
|
46
|
+
calls `whoami()` once and caches the key's project. Pass `project_id=...` to skip that
|
|
47
|
+
call, or when authenticating with a dashboard session token.
|
|
48
|
+
|
|
49
|
+
## Configuration
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
client = ReceiverClient(
|
|
53
|
+
api_key="recv_live_...", # default: RECEIVER_API_KEY
|
|
54
|
+
base_url="https://api.receiver.email/api/v1", # default: RECEIVER_API_URL, else production
|
|
55
|
+
timeout=30, # HTTP timeout for ordinary requests (seconds)
|
|
56
|
+
user_agent="my-tool/1.0", # default: receiver-sdk-py/<version>
|
|
57
|
+
project_id="proj_abc123", # default: RECEIVER_PROJECT_ID, else looked up once via whoami()
|
|
58
|
+
)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
A missing API key raises `ReceiverError` with `code == "MISSING_API_KEY"`.
|
|
62
|
+
|
|
63
|
+
## Usage
|
|
64
|
+
|
|
65
|
+
### Who am I
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
me = await client.whoami()
|
|
69
|
+
print(me.auth_type) # "apikey" or "jwt"
|
|
70
|
+
print(me.project.email_suffix) # -a3kx9p2m@receiver.email
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Create an inbox
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
inbox = await client.inboxes.create(prefix="reset") # prefix is optional
|
|
77
|
+
print(inbox.address) # reset-k2m9qa-a3kx9p2m@receiver.email
|
|
78
|
+
print(inbox.created_at) # pass as `since` when waiting
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Nothing is stored until mail arrives. Always build addresses this way (or from
|
|
82
|
+
`project.email_suffix`), never by hand.
|
|
83
|
+
|
|
84
|
+
### `since`
|
|
85
|
+
|
|
86
|
+
`since` (a `datetime` or ISO string) matches mail received **strictly after** it.
|
|
87
|
+
Use `inbox.created_at` for the first email, and the previous email's `received_at`
|
|
88
|
+
for the next one. Naive datetimes are treated as local time. When omitted, waits
|
|
89
|
+
look back 60 seconds and `stream()` starts from now.
|
|
90
|
+
|
|
91
|
+
### Wait for an email
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
from receiverdotemail import ReceiverTimeoutError
|
|
95
|
+
|
|
96
|
+
try:
|
|
97
|
+
email = await client.emails.wait_for(
|
|
98
|
+
recipient=inbox.address,
|
|
99
|
+
subject="Reset", # substring, case-insensitive
|
|
100
|
+
since=inbox.created_at,
|
|
101
|
+
timeout=120, # any length; the SDK repeats 60 s server waits
|
|
102
|
+
)
|
|
103
|
+
reset_link = next(link for link in email.links if "reset" in link)
|
|
104
|
+
except ReceiverTimeoutError as e:
|
|
105
|
+
print(f"Nothing after {e.waited_seconds}s (since {e.since})")
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`wait_for` returns an `Email` (with `text_body` and `links`) or raises
|
|
109
|
+
`ReceiverTimeoutError`. It never returns `None`.
|
|
110
|
+
|
|
111
|
+
### One-time codes
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
otp = await client.emails.wait_for_otp(recipient=inbox.address, since=inbox.created_at, timeout=60)
|
|
115
|
+
print(otp.code, otp.code_length, otp.source) # "123456", 6, "subject"
|
|
116
|
+
print([c.code for c in otp.candidates]) # every code found, newest first
|
|
117
|
+
|
|
118
|
+
# No waiting: returns None when nothing matches
|
|
119
|
+
otp = await client.emails.get_otp(recipient=inbox.address, code_length=6)
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Stream new emails
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
async for event in client.emails.stream(recipient=inbox.address):
|
|
126
|
+
print(event.email.subject, event.email.links)
|
|
127
|
+
if event.otp:
|
|
128
|
+
print(event.otp.code)
|
|
129
|
+
break # stop whenever you like
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The server closes each connection after about 55 seconds; the SDK reconnects with
|
|
133
|
+
the `since` it reports, so no email is missed or repeated.
|
|
134
|
+
|
|
135
|
+
### Send a test email
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
await client.emails.send_test(to=inbox.address) # "Your Receiver.email test code: 123456"
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### List, get and delete emails
|
|
142
|
+
|
|
143
|
+
```python
|
|
144
|
+
response = await client.emails.list(recipient=inbox.address, limit=50)
|
|
145
|
+
for email in response.emails:
|
|
146
|
+
print(email.subject)
|
|
147
|
+
|
|
148
|
+
async for email in client.emails.list_all(sender="noreply@example.com"):
|
|
149
|
+
...
|
|
150
|
+
|
|
151
|
+
email = await client.emails.get("email_xyz789") # or get("proj_abc123", "email_xyz789")
|
|
152
|
+
print(email.text_body, email.html_body, email.attachments)
|
|
153
|
+
|
|
154
|
+
await client.emails.delete("email_xyz789")
|
|
155
|
+
|
|
156
|
+
emails = await client.emails.find_by_subject("Password Reset")
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### Webhooks (dashboard session only)
|
|
160
|
+
|
|
161
|
+
Webhook management needs a dashboard session token; API keys get `403`.
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
hook = await client.webhooks.create("proj_abc123", "https://ci.example.com/hooks/receiver")
|
|
165
|
+
print(hook.secret) # whsec_..., shown once
|
|
166
|
+
|
|
167
|
+
hooks = await client.webhooks.list("proj_abc123") # List[Webhook]
|
|
168
|
+
delivery = await client.webhooks.test("proj_abc123", hook.id)
|
|
169
|
+
deliveries = await client.webhooks.deliveries("proj_abc123", hook.id) # last 50
|
|
170
|
+
await client.webhooks.delete("proj_abc123", hook.id)
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Verify each delivery in your receiver with the raw request body:
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
from receiverdotemail import verify_webhook_signature
|
|
177
|
+
|
|
178
|
+
if not verify_webhook_signature(secret, request.headers["Receiver-Signature"], raw_body):
|
|
179
|
+
return 400
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Projects, organizations and API keys
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
projects = await client.projects.list("org_abc123")
|
|
186
|
+
project = await client.projects.get("proj_abc123")
|
|
187
|
+
await client.projects.create(organization_id="org_abc123", name="CI Tests")
|
|
188
|
+
|
|
189
|
+
orgs = await client.organizations.list()
|
|
190
|
+
|
|
191
|
+
response = await client.api_keys.create(project_id="proj_abc123", name="CI Pipeline")
|
|
192
|
+
print(response.key) # Full key, only shown once!
|
|
193
|
+
await client.api_keys.revoke("proj_abc123", "key_xyz789")
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Error Handling
|
|
197
|
+
|
|
198
|
+
```python
|
|
199
|
+
from receiverdotemail import (
|
|
200
|
+
ReceiverError,
|
|
201
|
+
ReceiverTimeoutError,
|
|
202
|
+
RateLimitError,
|
|
203
|
+
AuthenticationError,
|
|
204
|
+
NotFoundError,
|
|
205
|
+
)
|
|
206
|
+
|
|
207
|
+
try:
|
|
208
|
+
email = await client.emails.wait_for(recipient=inbox.address, timeout=30)
|
|
209
|
+
except ReceiverTimeoutError as e:
|
|
210
|
+
print(e.since, e.waited_seconds)
|
|
211
|
+
except RateLimitError as e:
|
|
212
|
+
print(f"Rate limited. Retry at: {e.reset_at}")
|
|
213
|
+
except AuthenticationError:
|
|
214
|
+
print("Invalid API key")
|
|
215
|
+
except NotFoundError:
|
|
216
|
+
print("Not found")
|
|
217
|
+
except ReceiverError as e:
|
|
218
|
+
print(e.message, e.status_code, e.code)
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
All errors derive from `ReceiverError`. `ReceiverTimeoutError` has `status_code == 408`
|
|
222
|
+
and `code == "WAIT_TIMEOUT"`.
|
|
223
|
+
|
|
224
|
+
## Pytest Integration
|
|
225
|
+
|
|
226
|
+
```python
|
|
227
|
+
import pytest
|
|
228
|
+
from receiverdotemail import ReceiverClient
|
|
229
|
+
|
|
230
|
+
@pytest.fixture
|
|
231
|
+
async def receiver():
|
|
232
|
+
async with ReceiverClient() as client: # RECEIVER_API_KEY from the environment
|
|
233
|
+
yield client
|
|
234
|
+
|
|
235
|
+
async def test_signup_email(receiver):
|
|
236
|
+
inbox = await receiver.inboxes.create(prefix="signup")
|
|
237
|
+
await my_app.signup(inbox.address)
|
|
238
|
+
|
|
239
|
+
email = await receiver.emails.wait_for(
|
|
240
|
+
recipient=inbox.address,
|
|
241
|
+
subject="Confirm your email",
|
|
242
|
+
since=inbox.created_at,
|
|
243
|
+
timeout=60,
|
|
244
|
+
)
|
|
245
|
+
assert any("confirm" in link for link in email.links)
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
## Upgrading from 1.x
|
|
249
|
+
|
|
250
|
+
See [CHANGELOG.md](CHANGELOG.md). In short: `wait_for` raises `ReceiverTimeoutError`
|
|
251
|
+
instead of returning `None`, `wait_for_otp` raises instead of returning `None`, and
|
|
252
|
+
`received_after` on waits is now `since` (the old name still works).
|
|
253
|
+
|
|
254
|
+
## Development
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
pip install -e ".[dev]"
|
|
258
|
+
pytest
|
|
259
|
+
mypy receiverdotemail
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Or from the repo root: `./scripts/test.sh python-sdk`.
|
|
263
|
+
|
|
264
|
+
## License
|
|
265
|
+
|
|
266
|
+
MIT
|
|
267
|
+
|
|
268
|
+
## Support
|
|
269
|
+
|
|
270
|
+
- **Documentation**: https://docs.receiver.email
|
|
271
|
+
- **Email**: support@receiver.email
|
|
272
|
+
- **Issues**: https://github.com/receiverdotemail/sdk-python/issues
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "receiverdotemail"
|
|
7
|
+
version = "2.0.0"
|
|
8
|
+
description = "Official Python SDK for Receiver.email: programmable email inboxes for tests and AI agents, with OTP and link extraction"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "Receiver.email", email = "support@receiver.email" }
|
|
14
|
+
]
|
|
15
|
+
keywords = ["receiverdotemail", "receiver.email", "email", "email-testing", "email-api", "inbound-email", "otp", "2fa", "magic-link", "testing", "test-automation", "e2e-testing", "pytest", "playwright", "ai-agents", "disposable-email"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 4 - Beta",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.9",
|
|
21
|
+
"Programming Language :: Python :: 3.10",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
]
|
|
25
|
+
dependencies = [
|
|
26
|
+
"httpx>=0.25.0",
|
|
27
|
+
"pydantic>=2.0.0",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
[project.optional-dependencies]
|
|
31
|
+
dev = [
|
|
32
|
+
"pytest>=7.0.0",
|
|
33
|
+
"pytest-asyncio>=0.21.0",
|
|
34
|
+
"pytest-cov>=4.0.0",
|
|
35
|
+
"black>=23.0.0",
|
|
36
|
+
"mypy>=1.0.0",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
[project.urls]
|
|
40
|
+
Homepage = "https://receiver.email"
|
|
41
|
+
Documentation = "https://receiver.email/docs/sdks/python"
|
|
42
|
+
Repository = "https://github.com/BUW91/mailingestion/tree/main/packages/python-sdk"
|
|
43
|
+
Issues = "https://github.com/BUW91/mailingestion/issues"
|
|
44
|
+
|
|
45
|
+
[tool.setuptools.packages.find]
|
|
46
|
+
where = ["."]
|
|
47
|
+
include = ["receiverdotemail*"]
|
|
48
|
+
|
|
49
|
+
[tool.black]
|
|
50
|
+
line-length = 100
|
|
51
|
+
target-version = ['py39']
|
|
52
|
+
|
|
53
|
+
[tool.mypy]
|
|
54
|
+
python_version = "3.9"
|
|
55
|
+
warn_return_any = true
|
|
56
|
+
warn_unused_configs = true
|
|
57
|
+
disallow_untyped_defs = true
|
|
58
|
+
|
|
59
|
+
[tool.pytest.ini_options]
|
|
60
|
+
asyncio_mode = "auto"
|
|
61
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
62
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Receiver.email Python SDK
|
|
3
|
+
Official SDK for the Receiver.email email testing platform
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from receiverdotemail._version import __version__
|
|
7
|
+
from receiverdotemail.client import ReceiverClient
|
|
8
|
+
from receiverdotemail.webhooks import verify_webhook_signature
|
|
9
|
+
from receiverdotemail.errors import (
|
|
10
|
+
ReceiverError,
|
|
11
|
+
ReceiverTimeoutError,
|
|
12
|
+
RateLimitError,
|
|
13
|
+
AuthenticationError,
|
|
14
|
+
NotFoundError,
|
|
15
|
+
)
|
|
16
|
+
from receiverdotemail.types import (
|
|
17
|
+
Email,
|
|
18
|
+
Inbox,
|
|
19
|
+
OtpResult,
|
|
20
|
+
OtpCandidate,
|
|
21
|
+
StreamEvent,
|
|
22
|
+
WhoAmI,
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
__all__ = [
|
|
26
|
+
"__version__",
|
|
27
|
+
"ReceiverClient",
|
|
28
|
+
"verify_webhook_signature",
|
|
29
|
+
"ReceiverError",
|
|
30
|
+
"ReceiverTimeoutError",
|
|
31
|
+
"RateLimitError",
|
|
32
|
+
"AuthenticationError",
|
|
33
|
+
"NotFoundError",
|
|
34
|
+
"Email",
|
|
35
|
+
"Inbox",
|
|
36
|
+
"OtpResult",
|
|
37
|
+
"OtpCandidate",
|
|
38
|
+
"StreamEvent",
|
|
39
|
+
"WhoAmI",
|
|
40
|
+
]
|