sendclipper 0.1.0__tar.gz → 0.2.0__tar.gz

sendclipper-0.2.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.2.0 — 2026-10-18
+
+- `emails.send` and `sandboxes.send` take `replyTo` (one address or a list of up to 10) and `attachments` (a list of `{"filename", "content", "contentType"}`). Give `content` as `bytes`, `bytearray` or `memoryview` and the SDK base64-encodes it for you; a `str` is taken to be base64 already and sent as is. `contentType` is optional.
+- `batch.send` items take `replyTo` too. An item carrying `attachments` is failed by the server with `attachments_not_batchable`; send those messages with `emails.send`.
+- New type `sendclipper.types.Attachment`.
+- Needs the SendClipper API from 2026-10-18 on; an older API ignores both fields.
+
+## 0.1.1 — 2026-10-17
+
+- README: how to install in a uv workspace whose root has no `[project]` (`uv add --package`). No code change.
+
+## 0.1.0 — 2026-10-16
+
+First release.
+
+- `emails.send`, `batch.send`, `emails.get`, `emails.list`, `emails.iterate`, `emails.stats`.
+- Templates (with tags and image assets), domains, sandboxes (including the JSON door and `wait_for`), webhooks and their dispatches, contacts, audiences, suppressions, mailboxes, automations, workspace and API keys.
+- Every method returns a `Result` with `data`, `error` and `headers`; it unpacks to `(data, error)`.
+- Automatic `Idempotency-Key` on every JSON write; retries on network errors, 429 and 5xx.
+- `verify_webhook()` for `X-SendClipper-Signature-V2`, rotation-aware.
+- No runtime dependencies; typed (`py.typed`), Python 3.9 or newer.

{sendclipper-0.1.0 → sendclipper-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendclipper
-Version: 0.1.0
+Version: 0.2.0
 Summary: Official Python SDK for the SendClipper email API: send mail, manage domains, templates, sandboxes, webhooks, contacts and suppressions.
 Project-URL: Homepage, https://sendclipper.com
 Project-URL: Documentation, https://sendclipper.com/docs#sdk-python
@@ -39,6 +39,8 @@ uv add sendclipper
 poetry add sendclipper
 ```
 
+In a uv workspace whose root has no `[project]` table, `uv add` refuses at the root: name the member that sends mail with `uv add --package <member> sendclipper`.
+
 Python 3.9 or newer. No runtime dependencies. Fully typed.
 
 ## Setup
@@ -73,6 +75,26 @@ Parameters and responses are plain dicts whose keys are the API's own field name
 
 `from` must be a bare address on a domain you verified in SendClipper. Each message has one recipient in `to`; for several, use `batch.send`.
 
+## Reply-To and attachments
+
+```python
+with open("booking-42.pdf", "rb") as f:
+    pdf = f.read()
+
+data, error = sc.emails.send({
+    "from": "bookings@acme.io",
+    "to": "ada@lumen.io",
+    "subject": "Your booking",
+    "html": "<p>Your confirmation is attached.</p>",
+    "replyTo": "support@acme.io",
+    "attachments": [
+        {"filename": "booking-42.pdf", "content": pdf},
+    ],
+})
+```
+
+`replyTo` is one address or a list of up to 10. `content` is the file's bytes (`bytes`, `bytearray` or `memoryview`, which the SDK base64-encodes for you) or a `str` that is already base64; `contentType` is guessed from the filename when you leave it out. Limits: 10 MiB per file, 25 MiB of files per message, and your sending provider's own. Attachments are not accepted on a batch item; send those emails on their own. `sandboxes.send` takes the same two fields.
+
 ## Send with a template
 
 Design and publish a template in the dashboard, then send it by id or by its send name:

{sendclipper-0.1.0 → sendclipper-0.2.0}/README.md

@@ -10,6 +10,8 @@ uv add sendclipper
 poetry add sendclipper
 ```
 
+In a uv workspace whose root has no `[project]` table, `uv add` refuses at the root: name the member that sends mail with `uv add --package <member> sendclipper`.
+
 Python 3.9 or newer. No runtime dependencies. Fully typed.
 
 ## Setup
@@ -44,6 +46,26 @@ Parameters and responses are plain dicts whose keys are the API's own field name
 
 `from` must be a bare address on a domain you verified in SendClipper. Each message has one recipient in `to`; for several, use `batch.send`.
 
+## Reply-To and attachments
+
+```python
+with open("booking-42.pdf", "rb") as f:
+    pdf = f.read()
+
+data, error = sc.emails.send({
+    "from": "bookings@acme.io",
+    "to": "ada@lumen.io",
+    "subject": "Your booking",
+    "html": "<p>Your confirmation is attached.</p>",
+    "replyTo": "support@acme.io",
+    "attachments": [
+        {"filename": "booking-42.pdf", "content": pdf},
+    ],
+})
+```
+
+`replyTo` is one address or a list of up to 10. `content` is the file's bytes (`bytes`, `bytearray` or `memoryview`, which the SDK base64-encodes for you) or a `str` that is already base64; `contentType` is guessed from the filename when you leave it out. Limits: 10 MiB per file, 25 MiB of files per message, and your sending provider's own. Attachments are not accepted on a batch item; send those emails on their own. `sandboxes.send` takes the same two fields.
+
 ## Send with a template
 
 Design and publish a template in the dashboard, then send it by id or by its send name:

{sendclipper-0.1.0 → sendclipper-0.2.0}/src/sendclipper/_core.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import base64
 import json
 import os
 import random
@@ -427,6 +428,30 @@ def strip_none(params: Optional[Mapping[str, Any]]) -> Dict[str, Any]:
     return {k: v for k, v in (params or {}).items() if v is not None}
 
 
+def send_body(params: Mapping[str, Any]) -> Dict[str, Any]:
+    """
+    The JSON body of a send (``emails.send``, ``sandboxes.send``, each batch
+    item): a copy of ``params`` whose attachment ``content`` given as bytes is
+    base64-encoded. A ``str`` content is taken to be base64 already and sent as
+    is. The caller's dicts are never changed.
+    """
+    body = dict(params)
+    attachments = body.get("attachments")
+    if isinstance(attachments, (list, tuple)):
+        body["attachments"] = [_encode_attachment(a) for a in attachments]
+    return body
+
+
+def _encode_attachment(attachment: Any) -> Any:
+    if not isinstance(attachment, Mapping):
+        return attachment
+    out = dict(attachment)
+    content = out.get("content")
+    if isinstance(content, (bytes, bytearray, memoryview)):
+        out["content"] = base64.b64encode(bytes(content)).decode("ascii")
+    return out
+
+
 def multipart(fields: List[Tuple[str, str]], files: List[Tuple[str, str, str, bytes]]) -> Tuple[bytes, str]:
     """``multipart/form-data``: ``fields`` are (name, value), ``files`` are (name, filename, type, bytes)."""
     boundary = f"----sendclipper{uuid.uuid4().hex}"

{sendclipper-0.1.0 → sendclipper-0.2.0}/src/sendclipper/_version.py

@@ -1,3 +1,3 @@
 """Kept equal to the release tag by the publish workflow."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{sendclipper-0.1.0 → sendclipper-0.2.0}/src/sendclipper/resources/emails.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Iterator, List, Optional, cast
 
-from .._core import Result, seg, strip_none
+from .._core import Result, send_body, seg, strip_none
 from ._base import Resource
 
 if TYPE_CHECKING:
@@ -20,8 +20,11 @@ class Emails(Resource):
 
         Every call carries an ``Idempotency-Key``, so the SDK's own retries never
         send twice. Pass ``idempotency_key=`` yourself to make YOUR retries safe too.
+
+        ``replyTo`` takes one address or a list of up to 10. An attachment's
+        ``content`` may be ``bytes`` (encoded for you) or a base64 ``str``.
         """
-        return self._http.call("POST", "/emails", body=dict(params), **options)
+        return self._http.call("POST", "/emails", body=send_body(params), **options)
 
     def send_batch(self, emails: List[SendEmailParams], **options: Unpack[RequestOptions]) -> Result[SendBatchResponse]:
         """Same as ``batch.send()``."""
@@ -60,9 +63,12 @@ class Batch(Resource):
         """
         Up to 500 messages in one request (one recipient each). Every item is
         accepted or refused on its own; a refused item costs its siblings nothing.
+
+        An item may carry ``replyTo``; one carrying ``attachments`` fails with
+        ``attachments_not_batchable``, so send those messages with ``emails.send()``.
         """
         return _send_batch(self, emails, **options)
 
 
 def _send_batch(resource: Resource, emails: List[SendEmailParams], **options: Unpack[RequestOptions]) -> Result[SendBatchResponse]:
-    return resource._http.call("POST", "/emails/batch", body={"emails": [dict(e) for e in emails]}, **options)
+    return resource._http.call("POST", "/emails/batch", body={"emails": [send_body(e) for e in emails]}, **options)

{sendclipper-0.1.0 → sendclipper-0.2.0}/src/sendclipper/resources/sandboxes.py

@@ -4,7 +4,7 @@ import time
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional
 
-from .._core import ErrorResponse, Result, seg, strip_none
+from .._core import ErrorResponse, Result, send_body, seg, strip_none
 from ._base import Resource
 
 if TYPE_CHECKING:
@@ -125,9 +125,10 @@ class Sandboxes(Resource):
     def send(self, sandbox_token: str, params: SendEmailParams, **options: Unpack[RequestOptions]) -> Result[SandboxSendResult]:
         """
         Send to a sandbox through its JSON door, with the sandbox's own
-        ``sc_sbx_...`` token. Same fields as ``emails.send()``; nothing is delivered.
+        ``sc_sbx_...`` token. Same fields as ``emails.send()`` (``replyTo`` and
+        ``attachments`` included, bytes encoded for you); nothing is delivered.
         """
-        return self._http.call("POST", "/sandbox/emails", body=dict(params), bearer=sandbox_token, **options)
+        return self._http.call("POST", "/sandbox/emails", body=send_body(params), bearer=sandbox_token, **options)
 
 
 def _epoch(iso: str) -> float:

{sendclipper-0.1.0 → sendclipper-0.2.0}/src/sendclipper/types.py

@@ -41,6 +41,21 @@ _SendEmailRequired = TypedDict(
 )
 
 
+class _AttachmentRequired(TypedDict):
+    #: The name the recipient sees, e.g. ``"booking-42.pdf"``.
+    filename: str
+    #: The file's bytes (``bytes``, ``bytearray`` or ``memoryview``, which the SDK
+    #: base64-encodes for you) or a ``str`` that is already standard base64 (sent as is).
+    content: Union[str, bytes, bytearray, memoryview]
+
+
+class Attachment(_AttachmentRequired, total=False):
+    """One file on a message. Limits: 10 MiB per file, 25 MiB of files per message, 20 files."""
+
+    #: A MIME type such as ``"application/pdf"``. Guessed from ``filename`` when left out.
+    contentType: str
+
+
 class SendEmailParams(_SendEmailRequired, total=False):
     """
     One message. Give it a body (``subject`` + ``html``) or a published template
@@ -63,6 +78,11 @@ class SendEmailParams(_SendEmailRequired, total=False):
     trackOpens: bool
     #: ``False`` leaves links unwrapped. Default ``True``.
     trackClicks: bool
+    #: The Reply-To header: one bare address, or a list of 1-10.
+    replyTo: Union[str, List[str]]
+    #: Files to attach. Not accepted on a batch item: the server fails that item
+    #: with ``attachments_not_batchable`` (a batch item does accept ``replyTo``).
+    attachments: List[Attachment]
 
 
 EmailStatus = Literal["queued", "sent", "delivered", "opened", "clicked", "bounced", "complained", "failed"]

{sendclipper-0.1.0 → sendclipper-0.2.0}/tests/test_client.py

@@ -233,6 +233,78 @@ def test_sandboxes_send_uses_the_sandbox_token_instead_of_the_api_key(make_clien
     assert t.calls[0].headers["Authorization"] == "Bearer sc_sbx_abc"
 
 
+PDF = b"%PDF-1.7\n\x00\xff binary"
+PDF_B64 = "JVBERi0xLjcKAP8gYmluYXJ5"
+
+
+def test_send_carries_reply_to_and_encodes_bytes_attachments_while_a_base64_str_is_sent_as_is(make_client: Any) -> None:
+    sc, t = make_client([json(201, SENT)])
+    params: Any = {
+        **MSG,
+        "replyTo": ["support@acme.io", "billing@acme.io"],
+        "attachments": [
+            {"filename": "booking-42.pdf", "content": PDF, "contentType": "application/pdf"},
+            {"filename": "notes.txt", "content": "aGVsbG8="},
+        ],
+    }
+    sc.emails.send(params)
+    assert t.calls[0].body == {
+        **MSG,
+        "replyTo": ["support@acme.io", "billing@acme.io"],
+        "attachments": [
+            {"filename": "booking-42.pdf", "content": PDF_B64, "contentType": "application/pdf"},
+            {"filename": "notes.txt", "content": "aGVsbG8="},
+        ],
+    }
+    # The caller's own dicts are left alone.
+    assert params["attachments"][0]["content"] == PDF
+
+
+def test_bytearray_and_memoryview_content_are_encoded_too(make_client: Any) -> None:
+    sc, t = make_client([json(201, SENT)])
+    sc.emails.send(
+        {
+            **MSG,
+            "replyTo": "support@acme.io",
+            "attachments": [
+                {"filename": "a.bin", "content": bytearray(PDF)},
+                {"filename": "b.bin", "content": memoryview(PDF)},
+            ],
+        }
+    )
+    assert t.calls[0].body["replyTo"] == "support@acme.io"
+    assert [a["content"] for a in t.calls[0].body["attachments"]] == [PDF_B64, PDF_B64]
+
+
+def test_sandboxes_send_encodes_attachments_like_emails_send(make_client: Any) -> None:
+    sc, t = make_client([json(201, {"id": "sbx-msg"})])
+    sc.sandboxes.send(
+        "sc_sbx_abc",
+        {**MSG, "replyTo": "support@acme.io", "attachments": [{"filename": "booking-42.pdf", "content": PDF}]},
+    )
+    assert t.calls[0].body == {
+        **MSG,
+        "replyTo": "support@acme.io",
+        "attachments": [{"filename": "booking-42.pdf", "content": PDF_B64}],
+    }
+
+
+def test_batch_items_carry_reply_to_and_any_attachments_are_encoded(make_client: Any) -> None:
+    sc, t = make_client([json(200, {"data": [], "summary": {"submitted": 2, "accepted": 0, "failed": 0}})])
+    sc.batch.send(
+        [
+            {**MSG, "replyTo": "support@acme.io"},
+            {**MSG, "attachments": [{"filename": "x.pdf", "content": PDF}]},
+        ]
+    )
+    assert t.calls[0].body == {
+        "emails": [
+            {**MSG, "replyTo": "support@acme.io"},
+            {**MSG, "attachments": [{"filename": "x.pdf", "content": PDF_B64}]},
+        ]
+    }
+
+
 def test_contacts_import_is_multipart_carries_no_idempotency_key_and_is_never_retried(make_client: Any) -> None:
     sc, t = make_client([json(503, {"error": {"code": "unavailable", "message": "down"}})])
     _, error = sc.contacts.import_({"file": "name,email\nAda,ada@lumen.io\n", "filename": "contacts.csv", "onDuplicate": "update"})

sendclipper-0.1.0/CHANGELOG.md

@@ -1,12 +0,0 @@
-# Changelog
-
-## 0.1.0 — 2026-10-16
-
-First release.
-
-- `emails.send`, `batch.send`, `emails.get`, `emails.list`, `emails.iterate`, `emails.stats`.
-- Templates (with tags and image assets), domains, sandboxes (including the JSON door and `wait_for`), webhooks and their dispatches, contacts, audiences, suppressions, mailboxes, automations, workspace and API keys.
-- Every method returns a `Result` with `data`, `error` and `headers`; it unpacks to `(data, error)`.
-- Automatic `Idempotency-Key` on every JSON write; retries on network errors, 429 and 5xx.
-- `verify_webhook()` for `X-SendClipper-Signature-V2`, rotation-aware.
-- No runtime dependencies; typed (`py.typed`), Python 3.9 or newer.