sendio 1.0.0__tar.gz

sendio-1.0.0/LICENSE.md

@@ -0,0 +1,23 @@
+Copyright (c) 2022 Derich Pacheco
+Copyright (c) 2026 send.io
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

sendio-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE.md
+include NOTICE
+include requirements.txt
+include sendio/py.typed

sendio-1.0.0/NOTICE

@@ -0,0 +1,2 @@
+This SDK is based on https://github.com/resend/resend-python (MIT License), Copyright (c) Resend.
+Original copyright notice: Copyright (c) 2022 Derich Pacheco. See LICENSE.md.

sendio-1.0.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: sendio
+Version: 1.0.0
+Summary: The official send.io Python SDK
+Home-page: https://send.io
+Author: send.io
+Author-email: support@send.io
+License: MIT
+Project-URL: Documentation, https://developer.send.io/docs/api
+Project-URL: Homepage, https://send.io
+Keywords: email,email api,transactional email,sendio,send.io
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+License-File: NOTICE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: typing_extensions>=4.4.0
+Provides-Extra: async
+Requires-Dist: httpx>=0.24.0; extra == "async"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# send.io Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/sendio)](https://pypi.org/project/sendio/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sendio)](https://pypi.org/project/sendio)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+The official Python SDK for the [send.io](https://send.io) email API.
+
+Full API reference: https://developer.send.io/docs/api
+
+## Installation
+
+> **Coming soon:** this send.io package is not published yet, so the install lines below are commented out. Do not install a package by this name until the send.io docs list it as available.
+
+```bash
+# pip install sendio
+```
+
+For async support (via `httpx`):
+
+```bash
+# pip install "sendio[async]"
+```
+
+Python 3.7 or newer is required.
+
+## Quick start
+
+Create an API key in the send.io dashboard (keys start with `mx_`), then send an email:
+
+```py
+import sendio
+
+sendio.api_key = "mx_your_api_key"
+
+params: sendio.Emails.SendParams = {
+    "from": "Acme <onboarding@yourdomain.com>",
+    "to": ["delivered@send.io"],
+    "subject": "Hello from send.io",
+    "html": "<strong>It works!</strong>",
+}
+
+email: sendio.Emails.SendResponse = sendio.Emails.send(params)
+print(email["id"])
+```
+
+You can also pass `cc`, `bcc`, `reply_to`, `text`, `headers`, `attachments`, `tags`,
+`scheduled_at` and a `template`. Pass an idempotency key to make retries safe:
+
+```py
+sendio.Emails.send(params, {"idempotency_key": "welcome-user-123"})
+```
+
+## Batch sending
+
+Send up to 100 emails in one request:
+
+```py
+batch: sendio.Batch.SendResponse = sendio.Batch.send([
+    {
+        "from": "Acme <onboarding@yourdomain.com>",
+        "to": ["delivered@send.io"],
+        "subject": "First",
+        "html": "<p>First email</p>",
+    },
+    {
+        "from": "Acme <onboarding@yourdomain.com>",
+        "to": ["delivered@send.io"],
+        "subject": "Second",
+        "html": "<p>Second email</p>",
+    },
+])
+print([item["id"] for item in batch["data"]])
+```
+
+## Retrieve an email
+
+```py
+email: sendio.Email = sendio.Emails.get("4ef9a417-02e9-4d39-ad75-9611e0fcc33c")
+print(email["last_event"])
+```
+
+List recent emails with `sendio.Emails.list()`, update a scheduled send with
+`sendio.Emails.update(...)` and cancel it with `sendio.Emails.cancel(email_id)`.
+
+## Domains
+
+```py
+domain = sendio.Domains.create({"name": "yourdomain.com"})
+print(domain["records"])          # DNS records to add at your DNS provider
+
+sendio.Domains.verify(domain["id"])
+print(sendio.Domains.get(domain["id"])["status"])
+
+for d in sendio.Domains.list()["data"]:
+    print(d["name"], d["status"])
+```
+
+### Receiving email on a domain
+
+Pass `capabilities` to also accept inbound email. The create response then
+includes a `Receiving` MX record to publish.
+
+```py
+domain = sendio.Domains.create(
+    {"name": "yourdomain.com", "capabilities": {"receiving": "enabled"}}
+)
+
+# Stop accepting email for the domain; you can then remove its MX record.
+sendio.Domains.update({"id": domain["id"], "capabilities": {"receiving": "disabled"}})
+
+# Turn it back on. This asks for the domain's MX record; publish it to start receiving email.
+sendio.Domains.update({"id": domain["id"], "capabilities": {"receiving": "enabled"}})
+```
+
+Sending can't be turned off: `{"sending": "disabled"}` is rejected with a 422.
+
+## Mailboxes
+
+Mailboxes are real email accounts with IMAP/SMTP login. Create one on a verified
+domain (an address that already exists raises a 409); `credentials` comes back
+once, when IMAP/SMTP is ready. The password is also an API key for that mailbox,
+so store it like one.
+
+```py
+mailbox = sendio.Mailboxes.create({"address": "ada@yourdomain.com"})
+print(mailbox["credentials"]["smtp"])   # {"host": ..., "port": 587, "security": "starttls"}
+
+for m in sendio.Mailboxes.list()["data"]:   # every mailbox, not paginated
+    print(m["address"], m["imap_smtp"], m["health"])
+
+sendio.Mailboxes.update({"id": mailbox["id"], "warmup_enabled": False})
+creds = sendio.Mailboxes.reset_password(mailbox["id"])  # the old password stops working
+sendio.Mailboxes.remove(mailbox["id"])                  # also removes an agent inbox on it
+```
+
+Pass `local_part` + `domain_id` instead of `address`, or `username` (with
+optional `org` and `display_name`) for a free mailbox without a domain.
+
+The SDK also covers API keys, contacts, segments, topics, broadcasts, templates,
+webhooks (including signature verification), suppressions, logs, mailboxes and more. See
+[`examples/`](examples) for a script per resource.
+
+## Async
+
+Every method has an `_async` twin once the `async` extra is installed:
+
+```py
+import asyncio
+import sendio
+
+sendio.api_key = "mx_your_api_key"
+
+async def main() -> None:
+    email = await sendio.Emails.send_async({
+        "from": "Acme <onboarding@yourdomain.com>",
+        "to": ["delivered@send.io"],
+        "subject": "Hello",
+        "html": "<p>Sent asynchronously</p>",
+    })
+    print(email["id"])
+
+asyncio.run(main())
+```
+
+To customise the async client (for example its timeout):
+
+```py
+sendio.default_async_http_client = sendio.HTTPXClient(timeout=60)
+```
+
+A custom synchronous client can be plugged in the same way through
+`sendio.default_http_client` (see `examples/with_custom_http_client.py`).
+
+## Configuration
+
+| Setting  | Environment variable | Module attribute  | Default               |
+|----------|----------------------|-------------------|-----------------------|
+| API key  | `SENDIO_API_KEY`     | `sendio.api_key`  | none                  |
+| Base URL | `SENDIO_BASE_URL`    | `sendio.api_url`  | `https://api.send.io` |
+
+Environment variables are read when `sendio` is imported; module attributes can be
+changed at any time. Point the SDK at a different endpoint (a staging environment or a
+local mock server for tests) with:
+
+```bash
+export SENDIO_BASE_URL=http://localhost:8080
+```
+
+or in code:
+
+```py
+sendio.api_url = "http://localhost:8080"
+```
+
+Every request carries a `User-Agent: sendio-python:<version>` header.
+
+## Error handling
+
+API errors raise a subclass of `sendio.exceptions.SendioError`:
+
+```py
+import sendio
+from sendio.exceptions import SendioError, RateLimitError
+
+try:
+    sendio.Emails.send({
+        "from": "Acme <onboarding@yourdomain.com>",
+        "to": ["delivered@send.io"],
+        "subject": "Hello",
+        "html": "<p>Hi</p>",
+    })
+except RateLimitError as e:
+    print("slow down, retry after", e.headers.get("retry-after"))
+except SendioError as e:
+    print(e.code, e.error_type, e.message, e.suggested_action)
+```
+
+Specific types include `MissingApiKeyError`, `InvalidApiKeyError`, `ValidationError`,
+`MissingRequiredFieldsError`, `RateLimitError` and `ApplicationError`. Response headers
+(request id, rate limit info) are available on `e.headers` and, for successful calls,
+on `response["http_headers"]`.
+
+## Development
+
+```bash
+pip install -r requirements.txt pytest pytest-asyncio
+pytest tests
+```
+
+`examples/smoke.py` is a live check against a real send.io environment (it sends one
+email); it is not part of the unit tests.
+
+## License
+
+MIT. See [LICENSE.md](LICENSE.md) and [NOTICE](NOTICE).

sendio-1.0.0/README.md

@@ -0,0 +1,236 @@
+# send.io Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/sendio)](https://pypi.org/project/sendio/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sendio)](https://pypi.org/project/sendio)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+The official Python SDK for the [send.io](https://send.io) email API.
+
+Full API reference: https://developer.send.io/docs/api
+
+## Installation
+
+> **Coming soon:** this send.io package is not published yet, so the install lines below are commented out. Do not install a package by this name until the send.io docs list it as available.
+
+```bash
+# pip install sendio
+```
+
+For async support (via `httpx`):
+
+```bash
+# pip install "sendio[async]"
+```
+
+Python 3.7 or newer is required.
+
+## Quick start
+
+Create an API key in the send.io dashboard (keys start with `mx_`), then send an email:
+
+```py
+import sendio
+
+sendio.api_key = "mx_your_api_key"
+
+params: sendio.Emails.SendParams = {
+    "from": "Acme <onboarding@yourdomain.com>",
+    "to": ["delivered@send.io"],
+    "subject": "Hello from send.io",
+    "html": "<strong>It works!</strong>",
+}
+
+email: sendio.Emails.SendResponse = sendio.Emails.send(params)
+print(email["id"])
+```
+
+You can also pass `cc`, `bcc`, `reply_to`, `text`, `headers`, `attachments`, `tags`,
+`scheduled_at` and a `template`. Pass an idempotency key to make retries safe:
+
+```py
+sendio.Emails.send(params, {"idempotency_key": "welcome-user-123"})
+```
+
+## Batch sending
+
+Send up to 100 emails in one request:
+
+```py
+batch: sendio.Batch.SendResponse = sendio.Batch.send([
+    {
+        "from": "Acme <onboarding@yourdomain.com>",
+        "to": ["delivered@send.io"],
+        "subject": "First",
+        "html": "<p>First email</p>",
+    },
+    {
+        "from": "Acme <onboarding@yourdomain.com>",
+        "to": ["delivered@send.io"],
+        "subject": "Second",
+        "html": "<p>Second email</p>",
+    },
+])
+print([item["id"] for item in batch["data"]])
+```
+
+## Retrieve an email
+
+```py
+email: sendio.Email = sendio.Emails.get("4ef9a417-02e9-4d39-ad75-9611e0fcc33c")
+print(email["last_event"])
+```
+
+List recent emails with `sendio.Emails.list()`, update a scheduled send with
+`sendio.Emails.update(...)` and cancel it with `sendio.Emails.cancel(email_id)`.
+
+## Domains
+
+```py
+domain = sendio.Domains.create({"name": "yourdomain.com"})
+print(domain["records"])          # DNS records to add at your DNS provider
+
+sendio.Domains.verify(domain["id"])
+print(sendio.Domains.get(domain["id"])["status"])
+
+for d in sendio.Domains.list()["data"]:
+    print(d["name"], d["status"])
+```
+
+### Receiving email on a domain
+
+Pass `capabilities` to also accept inbound email. The create response then
+includes a `Receiving` MX record to publish.
+
+```py
+domain = sendio.Domains.create(
+    {"name": "yourdomain.com", "capabilities": {"receiving": "enabled"}}
+)
+
+# Stop accepting email for the domain; you can then remove its MX record.
+sendio.Domains.update({"id": domain["id"], "capabilities": {"receiving": "disabled"}})
+
+# Turn it back on. This asks for the domain's MX record; publish it to start receiving email.
+sendio.Domains.update({"id": domain["id"], "capabilities": {"receiving": "enabled"}})
+```
+
+Sending can't be turned off: `{"sending": "disabled"}` is rejected with a 422.
+
+## Mailboxes
+
+Mailboxes are real email accounts with IMAP/SMTP login. Create one on a verified
+domain (an address that already exists raises a 409); `credentials` comes back
+once, when IMAP/SMTP is ready. The password is also an API key for that mailbox,
+so store it like one.
+
+```py
+mailbox = sendio.Mailboxes.create({"address": "ada@yourdomain.com"})
+print(mailbox["credentials"]["smtp"])   # {"host": ..., "port": 587, "security": "starttls"}
+
+for m in sendio.Mailboxes.list()["data"]:   # every mailbox, not paginated
+    print(m["address"], m["imap_smtp"], m["health"])
+
+sendio.Mailboxes.update({"id": mailbox["id"], "warmup_enabled": False})
+creds = sendio.Mailboxes.reset_password(mailbox["id"])  # the old password stops working
+sendio.Mailboxes.remove(mailbox["id"])                  # also removes an agent inbox on it
+```
+
+Pass `local_part` + `domain_id` instead of `address`, or `username` (with
+optional `org` and `display_name`) for a free mailbox without a domain.
+
+The SDK also covers API keys, contacts, segments, topics, broadcasts, templates,
+webhooks (including signature verification), suppressions, logs, mailboxes and more. See
+[`examples/`](examples) for a script per resource.
+
+## Async
+
+Every method has an `_async` twin once the `async` extra is installed:
+
+```py
+import asyncio
+import sendio
+
+sendio.api_key = "mx_your_api_key"
+
+async def main() -> None:
+    email = await sendio.Emails.send_async({
+        "from": "Acme <onboarding@yourdomain.com>",
+        "to": ["delivered@send.io"],
+        "subject": "Hello",
+        "html": "<p>Sent asynchronously</p>",
+    })
+    print(email["id"])
+
+asyncio.run(main())
+```
+
+To customise the async client (for example its timeout):
+
+```py
+sendio.default_async_http_client = sendio.HTTPXClient(timeout=60)
+```
+
+A custom synchronous client can be plugged in the same way through
+`sendio.default_http_client` (see `examples/with_custom_http_client.py`).
+
+## Configuration
+
+| Setting  | Environment variable | Module attribute  | Default               |
+|----------|----------------------|-------------------|-----------------------|
+| API key  | `SENDIO_API_KEY`     | `sendio.api_key`  | none                  |
+| Base URL | `SENDIO_BASE_URL`    | `sendio.api_url`  | `https://api.send.io` |
+
+Environment variables are read when `sendio` is imported; module attributes can be
+changed at any time. Point the SDK at a different endpoint (a staging environment or a
+local mock server for tests) with:
+
+```bash
+export SENDIO_BASE_URL=http://localhost:8080
+```
+
+or in code:
+
+```py
+sendio.api_url = "http://localhost:8080"
+```
+
+Every request carries a `User-Agent: sendio-python:<version>` header.
+
+## Error handling
+
+API errors raise a subclass of `sendio.exceptions.SendioError`:
+
+```py
+import sendio
+from sendio.exceptions import SendioError, RateLimitError
+
+try:
+    sendio.Emails.send({
+        "from": "Acme <onboarding@yourdomain.com>",
+        "to": ["delivered@send.io"],
+        "subject": "Hello",
+        "html": "<p>Hi</p>",
+    })
+except RateLimitError as e:
+    print("slow down, retry after", e.headers.get("retry-after"))
+except SendioError as e:
+    print(e.code, e.error_type, e.message, e.suggested_action)
+```
+
+Specific types include `MissingApiKeyError`, `InvalidApiKeyError`, `ValidationError`,
+`MissingRequiredFieldsError`, `RateLimitError` and `ApplicationError`. Response headers
+(request id, rate limit info) are available on `e.headers` and, for successful calls,
+on `response["http_headers"]`.
+
+## Development
+
+```bash
+pip install -r requirements.txt pytest pytest-asyncio
+pytest tests
+```
+
+`examples/smoke.py` is a live check against a real send.io environment (it sends one
+email); it is not part of the unit tests.
+
+## License
+
+MIT. See [LICENSE.md](LICENSE.md) and [NOTICE](NOTICE).

sendio-1.0.0/requirements.txt

@@ -0,0 +1,2 @@
+requests>=2.31.0
+typing_extensions>=4.4.0