inboundr 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.
@@ -0,0 +1,9 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .mypy_cache/
8
+ .pytest_cache/
9
+ .DS_Store
inboundr-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Inboundr
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,237 @@
1
+ Metadata-Version: 2.5
2
+ Name: inboundr
3
+ Version: 0.1.0
4
+ Summary: Python SDK for the Inboundr API: receive email over signed webhooks, read and reply to it.
5
+ Project-URL: Homepage, https://inboundr.net
6
+ Project-URL: Documentation, https://inboundr.net/docs
7
+ Project-URL: Repository, https://github.com/inboundr-net/inboundr-python
8
+ Project-URL: Issues, https://github.com/inboundr-net/inboundr-python/issues
9
+ Author-email: Inboundr <dev@inboundr.net>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: email,inbound-email,inboundr,webhook,webhook-verification
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Communications :: Email
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: >=3.10
26
+ Requires-Dist: httpx<1,>=0.27
27
+ Requires-Dist: typing-extensions>=4.10
28
+ Description-Content-Type: text/markdown
29
+
30
+ ![Inboundr](https://raw.githubusercontent.com/inboundr-net/inboundr-python/refs/heads/main/assets/banner.png)
31
+
32
+ # Inboundr Python SDK
33
+
34
+ [![PyPI](https://img.shields.io/pypi/v/inboundr?color=0f766e&label=pypi)](https://pypi.org/project/inboundr/)
35
+ [![license](https://img.shields.io/badge/license-MIT-0f766e)](./LICENSE)
36
+
37
+ Python library for the [Inboundr](https://inboundr.net) API: receive email over signed webhooks, read and reply to it, and manage domains, addresses and endpoints.
38
+
39
+ - [Quickstart](https://inboundr.net/docs/quickstart)
40
+ - [API reference](https://inboundr.net/docs/api-reference/introduction)
41
+ - [Verifying webhooks](https://inboundr.net/docs/webhooks/verifying-signatures)
42
+
43
+ ## Install
44
+
45
+ ```bash
46
+ pip install inboundr
47
+ ```
48
+
49
+ Python 3.10+. Depends on `httpx`.
50
+
51
+ ## Setup
52
+
53
+ Create an API key in the console under **API keys**, then:
54
+
55
+ ```python
56
+ from inboundr import Inboundr
57
+
58
+ client = Inboundr("inb_123456789")
59
+ ```
60
+
61
+ With no argument, the key is read from `INBOUNDR_API_KEY`.
62
+
63
+ ## Receive email
64
+
65
+ Every inbound email is delivered to your endpoint as a signed `POST`. Verify it with the raw request body and the request's headers:
66
+
67
+ ```python
68
+ from flask import Flask, request
69
+ from inboundr import InboundrSignatureError, verify_webhook
70
+
71
+ app = Flask(__name__)
72
+
73
+ @app.post("/inbound")
74
+ def inbound():
75
+ try:
76
+ event = verify_webhook(request.get_data(), request.headers, WEBHOOK_SECRET)
77
+ except InboundrSignatureError:
78
+ return "", 400
79
+
80
+ email = event["email"]
81
+ print(email["from"], email["subject"], email["text"])
82
+ return "", 204
83
+ ```
84
+
85
+ The secret is the `whsec_` value returned when you create the endpoint. Pass the body as bytes, exactly as received: parsing and re-serializing the JSON changes it and breaks the signature.
86
+
87
+ `request.headers` can be any headers object (Flask, Django, FastAPI/Starlette) or a plain dict.
88
+
89
+ ### Retries
90
+
91
+ Failed deliveries are retried with the same delivery id. Use it to skip deliveries you have already handled:
92
+
93
+ ```python
94
+ from inboundr import read_webhook_headers
95
+
96
+ delivery_id = read_webhook_headers(request.headers).delivery_id
97
+ ```
98
+
99
+ ### Missing body
100
+
101
+ Some hosts drop the request body. The delivery still carries a signed email id, so you can fetch the email instead:
102
+
103
+ ```python
104
+ from inboundr import verify_webhook_ids
105
+
106
+ # when verify_webhook raises with err.reason == "missing_body"
107
+ ids = verify_webhook_ids(request.headers, WEBHOOK_SECRET)
108
+ email = client.emails.get(ids.email_id)
109
+ ```
110
+
111
+ ### Failure reasons
112
+
113
+ `InboundrSignatureError.reason` is one of:
114
+
115
+ | Reason | Meaning |
116
+ | --- | --- |
117
+ | `missing_secret` | No secret was passed. |
118
+ | `missing_header` | No signature header. |
119
+ | `malformed_header` | The signature header can't be parsed. |
120
+ | `invalid_signature` | The signature doesn't match. |
121
+ | `timestamp_out_of_tolerance` | Signed more than 5 minutes ago (set `tolerance_seconds` to change). |
122
+ | `missing_body` | Signed, but the body is empty. |
123
+ | `invalid_payload` | Verified, but not a known event. |
124
+
125
+ ## Read email
126
+
127
+ ```python
128
+ page = client.emails.list({"direction": "inbound", "limit": 20})
129
+
130
+ email = client.emails.get(page["data"][0]["id"])
131
+ thread = client.threads.get(email["threadId"])
132
+ ```
133
+
134
+ To go through every page:
135
+
136
+ ```python
137
+ for email in client.emails.list_all({"direction": "inbound"}):
138
+ print(email["subject"])
139
+ ```
140
+
141
+ Requests and responses are plain dicts with the API's field names, typed with `TypedDict`.
142
+
143
+ ## Reply and send
144
+
145
+ ```python
146
+ client.emails.reply(email["id"], {"text": "Thanks, we're on it."})
147
+
148
+ client.emails.send({
149
+ "from": "agent@yourdomain.com",
150
+ "to": ["customer@example.com"],
151
+ "subject": "Your order shipped",
152
+ "html": "<p>It's on the way.</p>",
153
+ })
154
+ ```
155
+
156
+ Sending needs a connected sender or a verified domain with sending enabled.
157
+
158
+ ## Attachments
159
+
160
+ ```python
161
+ # A signed URL, valid for 15 minutes
162
+ url = client.emails.attachment_url(email["id"], 0)["url"]
163
+
164
+ # Or the file itself
165
+ data = client.emails.download_attachment(email["id"], 0)
166
+ ```
167
+
168
+ ## Async
169
+
170
+ `AsyncInboundr` has the same methods:
171
+
172
+ ```python
173
+ from inboundr import AsyncInboundr
174
+
175
+ async with AsyncInboundr() as client:
176
+ page = await client.emails.list({"limit": 20})
177
+ async for email in client.emails.list_all():
178
+ ...
179
+ ```
180
+
181
+ ## Resources
182
+
183
+ | Resource | Methods |
184
+ | --- | --- |
185
+ | `emails` | `list`, `list_all`, `get`, `send`, `reply`, `delete`, `retry`, `attachment_url`, `download_attachment` |
186
+ | `threads` | `get` |
187
+ | `domains` | `list`, `create`, `get`, `update`, `delete` |
188
+ | `addresses` | `list`, `create`, `get`, `update`, `delete` |
189
+ | `endpoints` | `list`, `create`, `get`, `update`, `delete`, `test`, `deliveries`, `list_all_deliveries` |
190
+ | `shield_rules` | `list`, `create`, `get`, `update`, `delete`, `move`, `reorder` |
191
+ | `senders` | `list` |
192
+ | `suppressions` | `list`, `create`, `delete` |
193
+ | `forward_destinations` | `list`, `create`, `delete` |
194
+
195
+ See the [API reference](https://inboundr.net/docs/api-reference/introduction) for parameters and responses. All types are exported:
196
+
197
+ ```python
198
+ from inboundr import Email, Endpoint, SendEmailParams
199
+ ```
200
+
201
+ ## Errors
202
+
203
+ | Error | Raised when | Attributes |
204
+ | --- | --- | --- |
205
+ | `InboundrAPIError` | The API returns a non-2xx status | `status`, `body`, `request_id` |
206
+ | `InboundrRateLimitError` | The API returns `429` | `retry_after_seconds` |
207
+ | `InboundrError` | The request fails or times out | |
208
+
209
+ ```python
210
+ from inboundr import InboundrAPIError
211
+
212
+ try:
213
+ client.domains.create({"domain": "example.com"})
214
+ except InboundrAPIError as err:
215
+ print(err.status, err.body)
216
+ ```
217
+
218
+ Requests are not retried automatically.
219
+
220
+ ## Options
221
+
222
+ ```python
223
+ client = Inboundr(
224
+ "inb_123456789",
225
+ base_url="https://inboundr.net", # default
226
+ timeout=30.0, # seconds, default
227
+ http_client=httpx.Client(), # optional, your own client
228
+ )
229
+ ```
230
+
231
+ ## Contributing
232
+
233
+ See [CONTRIBUTING.md](./CONTRIBUTING.md).
234
+
235
+ ## License
236
+
237
+ MIT
@@ -0,0 +1,208 @@
1
+ ![Inboundr](https://raw.githubusercontent.com/inboundr-net/inboundr-python/refs/heads/main/assets/banner.png)
2
+
3
+ # Inboundr Python SDK
4
+
5
+ [![PyPI](https://img.shields.io/pypi/v/inboundr?color=0f766e&label=pypi)](https://pypi.org/project/inboundr/)
6
+ [![license](https://img.shields.io/badge/license-MIT-0f766e)](./LICENSE)
7
+
8
+ Python library for the [Inboundr](https://inboundr.net) API: receive email over signed webhooks, read and reply to it, and manage domains, addresses and endpoints.
9
+
10
+ - [Quickstart](https://inboundr.net/docs/quickstart)
11
+ - [API reference](https://inboundr.net/docs/api-reference/introduction)
12
+ - [Verifying webhooks](https://inboundr.net/docs/webhooks/verifying-signatures)
13
+
14
+ ## Install
15
+
16
+ ```bash
17
+ pip install inboundr
18
+ ```
19
+
20
+ Python 3.10+. Depends on `httpx`.
21
+
22
+ ## Setup
23
+
24
+ Create an API key in the console under **API keys**, then:
25
+
26
+ ```python
27
+ from inboundr import Inboundr
28
+
29
+ client = Inboundr("inb_123456789")
30
+ ```
31
+
32
+ With no argument, the key is read from `INBOUNDR_API_KEY`.
33
+
34
+ ## Receive email
35
+
36
+ Every inbound email is delivered to your endpoint as a signed `POST`. Verify it with the raw request body and the request's headers:
37
+
38
+ ```python
39
+ from flask import Flask, request
40
+ from inboundr import InboundrSignatureError, verify_webhook
41
+
42
+ app = Flask(__name__)
43
+
44
+ @app.post("/inbound")
45
+ def inbound():
46
+ try:
47
+ event = verify_webhook(request.get_data(), request.headers, WEBHOOK_SECRET)
48
+ except InboundrSignatureError:
49
+ return "", 400
50
+
51
+ email = event["email"]
52
+ print(email["from"], email["subject"], email["text"])
53
+ return "", 204
54
+ ```
55
+
56
+ The secret is the `whsec_` value returned when you create the endpoint. Pass the body as bytes, exactly as received: parsing and re-serializing the JSON changes it and breaks the signature.
57
+
58
+ `request.headers` can be any headers object (Flask, Django, FastAPI/Starlette) or a plain dict.
59
+
60
+ ### Retries
61
+
62
+ Failed deliveries are retried with the same delivery id. Use it to skip deliveries you have already handled:
63
+
64
+ ```python
65
+ from inboundr import read_webhook_headers
66
+
67
+ delivery_id = read_webhook_headers(request.headers).delivery_id
68
+ ```
69
+
70
+ ### Missing body
71
+
72
+ Some hosts drop the request body. The delivery still carries a signed email id, so you can fetch the email instead:
73
+
74
+ ```python
75
+ from inboundr import verify_webhook_ids
76
+
77
+ # when verify_webhook raises with err.reason == "missing_body"
78
+ ids = verify_webhook_ids(request.headers, WEBHOOK_SECRET)
79
+ email = client.emails.get(ids.email_id)
80
+ ```
81
+
82
+ ### Failure reasons
83
+
84
+ `InboundrSignatureError.reason` is one of:
85
+
86
+ | Reason | Meaning |
87
+ | --- | --- |
88
+ | `missing_secret` | No secret was passed. |
89
+ | `missing_header` | No signature header. |
90
+ | `malformed_header` | The signature header can't be parsed. |
91
+ | `invalid_signature` | The signature doesn't match. |
92
+ | `timestamp_out_of_tolerance` | Signed more than 5 minutes ago (set `tolerance_seconds` to change). |
93
+ | `missing_body` | Signed, but the body is empty. |
94
+ | `invalid_payload` | Verified, but not a known event. |
95
+
96
+ ## Read email
97
+
98
+ ```python
99
+ page = client.emails.list({"direction": "inbound", "limit": 20})
100
+
101
+ email = client.emails.get(page["data"][0]["id"])
102
+ thread = client.threads.get(email["threadId"])
103
+ ```
104
+
105
+ To go through every page:
106
+
107
+ ```python
108
+ for email in client.emails.list_all({"direction": "inbound"}):
109
+ print(email["subject"])
110
+ ```
111
+
112
+ Requests and responses are plain dicts with the API's field names, typed with `TypedDict`.
113
+
114
+ ## Reply and send
115
+
116
+ ```python
117
+ client.emails.reply(email["id"], {"text": "Thanks, we're on it."})
118
+
119
+ client.emails.send({
120
+ "from": "agent@yourdomain.com",
121
+ "to": ["customer@example.com"],
122
+ "subject": "Your order shipped",
123
+ "html": "<p>It's on the way.</p>",
124
+ })
125
+ ```
126
+
127
+ Sending needs a connected sender or a verified domain with sending enabled.
128
+
129
+ ## Attachments
130
+
131
+ ```python
132
+ # A signed URL, valid for 15 minutes
133
+ url = client.emails.attachment_url(email["id"], 0)["url"]
134
+
135
+ # Or the file itself
136
+ data = client.emails.download_attachment(email["id"], 0)
137
+ ```
138
+
139
+ ## Async
140
+
141
+ `AsyncInboundr` has the same methods:
142
+
143
+ ```python
144
+ from inboundr import AsyncInboundr
145
+
146
+ async with AsyncInboundr() as client:
147
+ page = await client.emails.list({"limit": 20})
148
+ async for email in client.emails.list_all():
149
+ ...
150
+ ```
151
+
152
+ ## Resources
153
+
154
+ | Resource | Methods |
155
+ | --- | --- |
156
+ | `emails` | `list`, `list_all`, `get`, `send`, `reply`, `delete`, `retry`, `attachment_url`, `download_attachment` |
157
+ | `threads` | `get` |
158
+ | `domains` | `list`, `create`, `get`, `update`, `delete` |
159
+ | `addresses` | `list`, `create`, `get`, `update`, `delete` |
160
+ | `endpoints` | `list`, `create`, `get`, `update`, `delete`, `test`, `deliveries`, `list_all_deliveries` |
161
+ | `shield_rules` | `list`, `create`, `get`, `update`, `delete`, `move`, `reorder` |
162
+ | `senders` | `list` |
163
+ | `suppressions` | `list`, `create`, `delete` |
164
+ | `forward_destinations` | `list`, `create`, `delete` |
165
+
166
+ See the [API reference](https://inboundr.net/docs/api-reference/introduction) for parameters and responses. All types are exported:
167
+
168
+ ```python
169
+ from inboundr import Email, Endpoint, SendEmailParams
170
+ ```
171
+
172
+ ## Errors
173
+
174
+ | Error | Raised when | Attributes |
175
+ | --- | --- | --- |
176
+ | `InboundrAPIError` | The API returns a non-2xx status | `status`, `body`, `request_id` |
177
+ | `InboundrRateLimitError` | The API returns `429` | `retry_after_seconds` |
178
+ | `InboundrError` | The request fails or times out | |
179
+
180
+ ```python
181
+ from inboundr import InboundrAPIError
182
+
183
+ try:
184
+ client.domains.create({"domain": "example.com"})
185
+ except InboundrAPIError as err:
186
+ print(err.status, err.body)
187
+ ```
188
+
189
+ Requests are not retried automatically.
190
+
191
+ ## Options
192
+
193
+ ```python
194
+ client = Inboundr(
195
+ "inb_123456789",
196
+ base_url="https://inboundr.net", # default
197
+ timeout=30.0, # seconds, default
198
+ http_client=httpx.Client(), # optional, your own client
199
+ )
200
+ ```
201
+
202
+ ## Contributing
203
+
204
+ See [CONTRIBUTING.md](./CONTRIBUTING.md).
205
+
206
+ ## License
207
+
208
+ MIT
@@ -0,0 +1,52 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.26"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "inboundr"
7
+ dynamic = ["version"]
8
+ description = "Python SDK for the Inboundr API: receive email over signed webhooks, read and reply to it."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "Inboundr", email = "dev@inboundr.net" }]
14
+ keywords = ["email", "inbound-email", "webhook", "webhook-verification", "inboundr"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Intended Audience :: Developers",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Programming Language :: Python :: 3.10",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Programming Language :: Python :: 3.14",
26
+ "Topic :: Communications :: Email",
27
+ "Typing :: Typed",
28
+ ]
29
+ dependencies = ["httpx>=0.27,<1", "typing_extensions>=4.10"]
30
+
31
+ [project.urls]
32
+ Homepage = "https://inboundr.net"
33
+ Documentation = "https://inboundr.net/docs"
34
+ Repository = "https://github.com/inboundr-net/inboundr-python"
35
+ Issues = "https://github.com/inboundr-net/inboundr-python/issues"
36
+
37
+ [tool.hatch.version]
38
+ path = "src/inboundr/_version.py"
39
+
40
+ [tool.hatch.build.targets.wheel]
41
+ packages = ["src/inboundr"]
42
+
43
+ [tool.hatch.build.targets.sdist]
44
+ include = ["src/inboundr", "README.md", "LICENSE"]
45
+
46
+ [tool.pytest.ini_options]
47
+ testpaths = ["tests"]
48
+
49
+ [tool.mypy]
50
+ strict = true
51
+ python_version = "3.10"
52
+ files = ["src/inboundr", "tests/typecheck"]
@@ -0,0 +1,65 @@
1
+ """Python SDK for the Inboundr API.
2
+
3
+ ::
4
+
5
+ from inboundr import Inboundr, verify_webhook
6
+
7
+ client = Inboundr() # reads INBOUNDR_API_KEY
8
+ page = client.emails.list({"direction": "inbound", "limit": 20})
9
+ """
10
+
11
+ from ._async_client import AsyncInboundr
12
+ from ._base import API_KEY_ENV_VAR, DEFAULT_BASE_URL
13
+ from ._client import Inboundr
14
+ from ._errors import (
15
+ InboundrAPIError,
16
+ InboundrError,
17
+ InboundrRateLimitError,
18
+ InboundrSignatureError,
19
+ SignatureFailureReason,
20
+ )
21
+ from ._types import * # noqa: F403
22
+ from ._types import __all__ as _types_all
23
+ from ._version import __version__
24
+ from ._webhooks import (
25
+ DEFAULT_TOLERANCE_SECONDS,
26
+ DELIVERY_ID_HEADER,
27
+ EMAIL_ID_HEADER,
28
+ EVENT_HEADER,
29
+ ID_SIGNATURE_HEADER,
30
+ LEGACY_DELIVERY_ID_HEADER,
31
+ LEGACY_SIGNATURE_HEADER,
32
+ SIGNATURE_HEADER,
33
+ WebhookHeaders,
34
+ WebhookIds,
35
+ read_webhook_headers,
36
+ verify_webhook,
37
+ verify_webhook_ids,
38
+ )
39
+
40
+ __all__ = [
41
+ "API_KEY_ENV_VAR",
42
+ "AsyncInboundr",
43
+ "DEFAULT_BASE_URL",
44
+ "DEFAULT_TOLERANCE_SECONDS",
45
+ "DELIVERY_ID_HEADER",
46
+ "EMAIL_ID_HEADER",
47
+ "EVENT_HEADER",
48
+ "ID_SIGNATURE_HEADER",
49
+ "Inboundr",
50
+ "InboundrAPIError",
51
+ "InboundrError",
52
+ "InboundrRateLimitError",
53
+ "InboundrSignatureError",
54
+ "LEGACY_DELIVERY_ID_HEADER",
55
+ "LEGACY_SIGNATURE_HEADER",
56
+ "SIGNATURE_HEADER",
57
+ "SignatureFailureReason",
58
+ "WebhookHeaders",
59
+ "WebhookIds",
60
+ "__version__",
61
+ "read_webhook_headers",
62
+ "verify_webhook",
63
+ "verify_webhook_ids",
64
+ *_types_all,
65
+ ]