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.
Files changed (37) hide show
  1. receiverdotemail-2.0.0/PKG-INFO +301 -0
  2. receiverdotemail-2.0.0/README.md +272 -0
  3. receiverdotemail-2.0.0/pyproject.toml +62 -0
  4. receiverdotemail-2.0.0/receiverdotemail/__init__.py +40 -0
  5. receiverdotemail-2.0.0/receiverdotemail/_context.py +50 -0
  6. receiverdotemail-2.0.0/receiverdotemail/_sse.py +39 -0
  7. receiverdotemail-2.0.0/receiverdotemail/_utils.py +26 -0
  8. receiverdotemail-2.0.0/receiverdotemail/_version.py +3 -0
  9. receiverdotemail-2.0.0/receiverdotemail/client.py +91 -0
  10. receiverdotemail-2.0.0/receiverdotemail/errors.py +58 -0
  11. receiverdotemail-2.0.0/receiverdotemail/http.py +169 -0
  12. receiverdotemail-2.0.0/receiverdotemail/resources/__init__.py +12 -0
  13. receiverdotemail-2.0.0/receiverdotemail/resources/api_keys.py +85 -0
  14. receiverdotemail-2.0.0/receiverdotemail/resources/emails.py +492 -0
  15. receiverdotemail-2.0.0/receiverdotemail/resources/inboxes.py +37 -0
  16. receiverdotemail-2.0.0/receiverdotemail/resources/organizations.py +90 -0
  17. receiverdotemail-2.0.0/receiverdotemail/resources/projects.py +88 -0
  18. receiverdotemail-2.0.0/receiverdotemail/resources/webhooks.py +58 -0
  19. receiverdotemail-2.0.0/receiverdotemail/types/__init__.py +69 -0
  20. receiverdotemail-2.0.0/receiverdotemail/types/api_key.py +42 -0
  21. receiverdotemail-2.0.0/receiverdotemail/types/base.py +17 -0
  22. receiverdotemail-2.0.0/receiverdotemail/types/email.py +126 -0
  23. receiverdotemail-2.0.0/receiverdotemail/types/inbox.py +15 -0
  24. receiverdotemail-2.0.0/receiverdotemail/types/organization.py +64 -0
  25. receiverdotemail-2.0.0/receiverdotemail/types/project.py +27 -0
  26. receiverdotemail-2.0.0/receiverdotemail/types/webhook.py +48 -0
  27. receiverdotemail-2.0.0/receiverdotemail/types/whoami.py +44 -0
  28. receiverdotemail-2.0.0/receiverdotemail/webhooks.py +47 -0
  29. receiverdotemail-2.0.0/receiverdotemail.egg-info/PKG-INFO +301 -0
  30. receiverdotemail-2.0.0/receiverdotemail.egg-info/SOURCES.txt +35 -0
  31. receiverdotemail-2.0.0/receiverdotemail.egg-info/dependency_links.txt +1 -0
  32. receiverdotemail-2.0.0/receiverdotemail.egg-info/requires.txt +9 -0
  33. receiverdotemail-2.0.0/receiverdotemail.egg-info/top_level.txt +1 -0
  34. receiverdotemail-2.0.0/setup.cfg +4 -0
  35. receiverdotemail-2.0.0/tests/test_agent_api.py +446 -0
  36. receiverdotemail-2.0.0/tests/test_client.py +213 -0
  37. 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
+ ]