mailflat 0.6.0__tar.gz → 0.7.0__tar.gz

{mailflat-0.6.0 → mailflat-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailflat
-Version: 0.6.0
+Version: 0.7.0
 Summary: Official Python SDK for MailFlat — disposable, automation-friendly email inboxes with one-line OTP retrieval.
 Project-URL: Homepage, https://mailflat.net
 Project-URL: Documentation, https://mailflat.net
@@ -104,8 +104,14 @@ SDK in tests without a network (e.g. `httpx.MockTransport`).
 - `.latest(*, direction="in") -> Message | None` — most recent message.
 - `.wait_for_otp(*, timeout=30, poll_interval=1.0) -> str` — poll until an OTP arrives; returns the code.
 - `.wait_for_message(*, timeout=30, poll_interval=1.0, direction="in") -> Message` — poll until a message arrives.
-- `.send(to, *, subject="", body="", html=None, in_reply_to=None) -> dict` — send a
-  DKIM-signed email from this inbox. Pass `in_reply_to` (a `Message-ID`) to stay in a thread.
+- `.send(to, *, subject="", body="", html=None, in_reply_to=None, cc=None, bcc=None, attachments=None) -> dict` —
+  send a DKIM-signed email from this inbox. Returns once the mail is **accepted for
+  delivery**, not once it is delivered (see below). Pass `in_reply_to` (a `Message-ID`) to
+  stay in a thread.
+- `.message(message_id) -> Message` — fetch one message; the way to check what happened to a send.
+- `.wait_until_sent(message_id, *, timeout=120, poll_interval=2.0) -> Message` — block until
+  delivery finishes. Raises `SendFailedError` if it permanently failed, `SendTimeoutError`
+  if it is still queued at the deadline.
 - `.mark_read(message_id) -> dict` — mark a message read so later polls can skip it.
 - `.burn() -> dict` — delete every message but keep the address.
 - `.download_attachment(message_id, attachment_id) -> bytes` — fetch an attachment's bytes.
@@ -117,12 +123,15 @@ SDK in tests without a network (e.g. `httpx.MockTransport`).
 
 ### `Message`
 `.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`,
-`.links`, `.attachments`, `.spam`, `.headers`, `.is_read`, `.raw`.
+`.links`, `.attachments`, `.spam`, `.headers`, `.is_read`, `.message_id`, `.reply_to_address`, `.raw`.
+
+- ⚠️ `.sender` is the **SMTP envelope sender** (MAIL FROM). On transactional mail that is
+  usually a bounce address such as `bounces+abc@sendgrid.net`, so `send(to=msg.sender, …)`
+  delivers your reply to a bounce processor. Use `.reply_to_address` (or just `.reply()`),
+  which resolves `Reply-To` → `From` → envelope sender.
 
 - `.links` — URLs found in the body (HTML hrefs first). For "click the verification link" flows.
 - `.attachments` — metadata; `msg.attachments[0].download()` fetches the bytes.
-  ⚠️ `send()` cannot attach files yet, so you cannot produce an attachment from the SDK
-  alone — send one from a normal mail client to test this path.
 - `.spam` — `{score, required, is_spam, rules, scanner}`, or `None` when never scanned
   (which is not the same as a score of 0). ⚠️ Spam scanning is currently **disabled** on
   mailflat.net, so today this is `None` for every message.
@@ -135,6 +144,41 @@ SDK in tests without a network (e.g. `httpx.MockTransport`).
   conversation instead, which does not look like a reply.
 - `.mark_read()` / `.delete()` — act on this message directly.
 
+## Attachments, cc and bcc
+
+```python
+inbox.send(
+    "customer@example.com",
+    subject="Your invoice",
+    body="Attached.",
+    cc=["billing@example.com"],
+    bcc=["audit@example.com"],
+    attachments=["/tmp/invoice.pdf"],          # a path — the SDK reads and encodes it
+)
+```
+
+An attachment can be a file path, `{"filename": ..., "content": b"..."}`, or
+`{"filename": ..., "content_b64": "..."}`. Size and count limits depend on your plan
+(the free plan is deliberately small); going over raises with the limit spelled out
+rather than silently dropping the file.
+
+`bcc` recipients receive the mail but never appear in its headers — not even in their own
+copy. `reply()` accepts all three too, so you can answer a thread with a file attached.
+
+## Did it actually go out?
+
+`send()` returns as soon as the mail is **accepted**; delivery runs on a queue, so nothing
+is delivered yet when it returns:
+
+```python
+res = inbox.send("customer@example.com", subject="Your invoice",
+                 attachments=["/tmp/invoice.pdf"])
+inbox.wait_until_sent(res["message_id"], timeout=120)   # raises if it failed
+```
+
+For anything long-running, subscribe to the `message.delivered` / `message.failed`
+webhooks instead of polling.
+
 ## Errors
 
 All errors subclass `MailFlatError`: `AuthenticationError` (401), `MailFlatPermissionError` (403,

{mailflat-0.6.0 → mailflat-0.7.0}/README.md

@@ -69,8 +69,14 @@ SDK in tests without a network (e.g. `httpx.MockTransport`).
 - `.latest(*, direction="in") -> Message | None` — most recent message.
 - `.wait_for_otp(*, timeout=30, poll_interval=1.0) -> str` — poll until an OTP arrives; returns the code.
 - `.wait_for_message(*, timeout=30, poll_interval=1.0, direction="in") -> Message` — poll until a message arrives.
-- `.send(to, *, subject="", body="", html=None, in_reply_to=None) -> dict` — send a
-  DKIM-signed email from this inbox. Pass `in_reply_to` (a `Message-ID`) to stay in a thread.
+- `.send(to, *, subject="", body="", html=None, in_reply_to=None, cc=None, bcc=None, attachments=None) -> dict` —
+  send a DKIM-signed email from this inbox. Returns once the mail is **accepted for
+  delivery**, not once it is delivered (see below). Pass `in_reply_to` (a `Message-ID`) to
+  stay in a thread.
+- `.message(message_id) -> Message` — fetch one message; the way to check what happened to a send.
+- `.wait_until_sent(message_id, *, timeout=120, poll_interval=2.0) -> Message` — block until
+  delivery finishes. Raises `SendFailedError` if it permanently failed, `SendTimeoutError`
+  if it is still queued at the deadline.
 - `.mark_read(message_id) -> dict` — mark a message read so later polls can skip it.
 - `.burn() -> dict` — delete every message but keep the address.
 - `.download_attachment(message_id, attachment_id) -> bytes` — fetch an attachment's bytes.
@@ -82,12 +88,15 @@ SDK in tests without a network (e.g. `httpx.MockTransport`).
 
 ### `Message`
 `.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`,
-`.links`, `.attachments`, `.spam`, `.headers`, `.is_read`, `.raw`.
+`.links`, `.attachments`, `.spam`, `.headers`, `.is_read`, `.message_id`, `.reply_to_address`, `.raw`.
+
+- ⚠️ `.sender` is the **SMTP envelope sender** (MAIL FROM). On transactional mail that is
+  usually a bounce address such as `bounces+abc@sendgrid.net`, so `send(to=msg.sender, …)`
+  delivers your reply to a bounce processor. Use `.reply_to_address` (or just `.reply()`),
+  which resolves `Reply-To` → `From` → envelope sender.
 
 - `.links` — URLs found in the body (HTML hrefs first). For "click the verification link" flows.
 - `.attachments` — metadata; `msg.attachments[0].download()` fetches the bytes.
-  ⚠️ `send()` cannot attach files yet, so you cannot produce an attachment from the SDK
-  alone — send one from a normal mail client to test this path.
 - `.spam` — `{score, required, is_spam, rules, scanner}`, or `None` when never scanned
   (which is not the same as a score of 0). ⚠️ Spam scanning is currently **disabled** on
   mailflat.net, so today this is `None` for every message.
@@ -100,6 +109,41 @@ SDK in tests without a network (e.g. `httpx.MockTransport`).
   conversation instead, which does not look like a reply.
 - `.mark_read()` / `.delete()` — act on this message directly.
 
+## Attachments, cc and bcc
+
+```python
+inbox.send(
+    "customer@example.com",
+    subject="Your invoice",
+    body="Attached.",
+    cc=["billing@example.com"],
+    bcc=["audit@example.com"],
+    attachments=["/tmp/invoice.pdf"],          # a path — the SDK reads and encodes it
+)
+```
+
+An attachment can be a file path, `{"filename": ..., "content": b"..."}`, or
+`{"filename": ..., "content_b64": "..."}`. Size and count limits depend on your plan
+(the free plan is deliberately small); going over raises with the limit spelled out
+rather than silently dropping the file.
+
+`bcc` recipients receive the mail but never appear in its headers — not even in their own
+copy. `reply()` accepts all three too, so you can answer a thread with a file attached.
+
+## Did it actually go out?
+
+`send()` returns as soon as the mail is **accepted**; delivery runs on a queue, so nothing
+is delivered yet when it returns:
+
+```python
+res = inbox.send("customer@example.com", subject="Your invoice",
+                 attachments=["/tmp/invoice.pdf"])
+inbox.wait_until_sent(res["message_id"], timeout=120)   # raises if it failed
+```
+
+For anything long-running, subscribe to the `message.delivered` / `message.failed`
+webhooks instead of polling.
+
 ## Errors
 
 All errors subclass `MailFlatError`: `AuthenticationError` (401), `MailFlatPermissionError` (403,

{mailflat-0.6.0 → mailflat-0.7.0}/src/mailflat/__init__.py

@@ -10,7 +10,8 @@ Key exports:
   - `MailFlat` — client
   - `Inbox`, `Message`, `Attachment` — domain types
   - errors: `MailFlatError`, `AuthenticationError`, `MailFlatPermissionError`,
-    `NotFoundError`, `RateLimitError`, `APIError`, `OTPTimeoutError`, `EncryptedInboxError`
+    `NotFoundError`, `RateLimitError`, `APIError`, `OTPTimeoutError`,
+    `SendFailedError`, `SendTimeoutError`, `EncryptedInboxError`
   - `redact_secrets()` — strips secret fields from agent tool output (used by MCP/LangChain)
 """
 from __future__ import annotations
@@ -26,13 +27,16 @@ from .errors import (
     OTPTimeoutError,
     PermissionError,
     RateLimitError,
+    SendError,
+    SendFailedError,
+    SendTimeoutError,
 )
 from .inbox import Attachment, Inbox, Message
 from .redact import redact_secrets
 
 # The package's ONLY version source — pyproject.toml reads it via [tool.hatch.version].
 # Releasing = bump this line and nothing else.
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "MailFlat",
@@ -47,6 +51,9 @@ __all__ = [
     "RateLimitError",
     "APIError",
     "OTPTimeoutError",
+    "SendError",
+    "SendFailedError",
+    "SendTimeoutError",
     "EncryptedInboxError",
     "redact_secrets",
     "__version__",

{mailflat-0.6.0 → mailflat-0.7.0}/src/mailflat/errors.py

@@ -11,6 +11,8 @@ Key exports:
   - `RateLimitError` — 429 (carries `retry_after` when the server sent it)
   - `APIError` — any other 4xx/5xx
   - `OTPTimeoutError` — wait_for_otp / wait_for_message timed out
+  - `SendFailedError` — a sent mail permanently failed to be delivered
+  - `SendTimeoutError` — wait_until_sent gave up while the mail was still queued
   - `EncryptedInboxError` — end-to-end encrypted inbox cannot be read through the API
 """
 from __future__ import annotations
@@ -65,6 +67,38 @@ class OTPTimeoutError(MailFlatError):
     """No OTP (or message) arrived before the timeout elapsed."""
 
 
+class SendError(MailFlatError):
+    """Base for the two ways `wait_until_sent()` can end badly.
+
+    Separate from `OTPTimeoutError` on purpose. That one means *"the mail I was waiting
+    for never arrived"*; these mean *"the mail I sent did not go out"*. Reusing one name
+    for both would let a single `except` clause hide two unrelated faults.
+    """
+
+    def __init__(self, message: str, *, message_id: int | None = None,
+                 status: str | None = None) -> None:
+        super().__init__(message)
+        self.message_id = message_id
+        #: Last delivery status seen — `"queued"` on timeout, `"failed"` on failure.
+        self.status = status
+
+
+class SendFailedError(SendError):
+    """Delivery permanently failed; the queue will not retry it.
+
+    `.message` carries the server's reason (a `5xx` from the recipient's MX, an unknown
+    mailbox, and so on).
+    """
+
+
+class SendTimeoutError(SendError):
+    """Still queued when `wait_until_sent()` gave up.
+
+    NOT the same as failure: the queue keeps retrying with exponential backoff, so the
+    mail may still be delivered. Greylisting alone can hold a mail for several minutes.
+    """
+
+
 class EncryptedInboxError(MailFlatError):
     """The inbox is end-to-end encrypted, so the server cannot read its contents."""
 

{mailflat-0.6.0 → mailflat-0.7.0}/src/mailflat/inbox.py

@@ -9,17 +9,25 @@ Connected to:
 
 Key exports:
   - `Inbox` — `.address`, `.messages()`, `.latest()`, `.wait_for_message()`,
-    `.wait_for_otp()`, `.send()`, `.mark_read()`, `.burn()`, `.download_attachment()`
+    `.wait_for_otp()`, `.send()`, `.wait_until_sent()`, `.mark_read()`, `.burn()`,
+    `.download_attachment()`
   - `Message` — `.otp`, `.subject`, `.text`, `.html`, `.links`, `.attachments`, `.spam`, ...
   - `Attachment` — `.filename`, `.size_bytes`, `.download()`
 """
 from __future__ import annotations
 
+import base64
+import mimetypes
+import os
 import time
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-from .errors import EncryptedInboxError, MailFlatError, OTPTimeoutError
+from email.utils import parseaddr
+
+from .errors import (EncryptedInboxError, MailFlatError, OTPTimeoutError, SendFailedError,
+                     SendTimeoutError)
 
 if TYPE_CHECKING:  # avoid a circular import (type hint only)
     from .client import MailFlat
@@ -41,6 +49,76 @@ def _reply_subject(subject: str | None) -> str:
     return text if text.lower().startswith("re:") else f"Re: {text}"
 
 
+def _encode_attachment(item: Any) -> dict[str, str]:
+    """One attachment → the wire shape `{filename, content_type, content_b64}`.
+
+    Accepts a filesystem path or a dict, because an agent should never have to base64 a
+    file by hand — hiding that is most of what an SDK is for. A path is the common case
+    (the file is on disk next to the agent) and the type is guessed from the extension so
+    the recipient's client shows a PDF as a PDF rather than a nameless blob.
+
+    The JS SDK deliberately does NOT accept paths: it can run in a browser, where there is
+    no filesystem. Same feature, different runtimes — see `docs`.
+    """
+    if isinstance(item, (str, os.PathLike)):
+        path = Path(item)
+        try:
+            data = path.read_bytes()
+        except OSError as exc:
+            raise ValueError(f"Could not read attachment {path}: {exc}") from exc
+        ctype = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+        return {"filename": path.name, "content_type": ctype,
+                "content_b64": base64.b64encode(data).decode("ascii")}
+
+    if not isinstance(item, dict):
+        raise TypeError(
+            "Each attachment must be a file path or a dict with 'filename' and "
+            f"'content' (bytes) or 'content_b64' (str), got {type(item).__name__}.")
+
+    filename = str(item.get("filename") or "").strip()
+    if not filename:
+        raise ValueError("Attachment dicts need a 'filename'.")
+
+    if "content_b64" in item:
+        content_b64 = item["content_b64"]
+        if not isinstance(content_b64, str):
+            raise TypeError("'content_b64' must be a base64 string.")
+    else:
+        content = item.get("content")
+        if not isinstance(content, (bytes, bytearray, memoryview)):
+            raise TypeError(
+                f"Attachment '{filename}' needs 'content' as bytes (or 'content_b64' as "
+                "a base64 string).")
+        content_b64 = base64.b64encode(bytes(content)).decode("ascii")
+
+    ctype = item.get("content_type") or mimetypes.guess_type(filename)[0] \
+        or "application/octet-stream"
+    return {"filename": filename, "content_type": ctype, "content_b64": content_b64}
+
+
+def _send_payload(to: str, subject: str, body: str, html: str | None,
+                  in_reply_to: str | None, cc: list[str] | None, bcc: list[str] | None,
+                  attachments: list[Any] | None) -> dict[str, Any]:
+    """Shared body builder for `send()` and `reply()`.
+
+    One builder because `reply()` must accept exactly what `send()` accepts (K6): an agent
+    answering a mail with an invoice attached is the normal case, not an edge case. Two
+    builders would drift the first time a field is added to one of them.
+    """
+    payload: dict[str, Any] = {"to": to, "subject": subject, "body": body}
+    if html is not None:
+        payload["html"] = html
+    if in_reply_to is not None:
+        payload["in_reply_to"] = in_reply_to
+    if cc:
+        payload["cc"] = list(cc)
+    if bcc:
+        payload["bcc"] = list(bcc)
+    if attachments:
+        payload["attachments"] = [_encode_attachment(a) for a in attachments]
+    return payload
+
+
 def _check_direction(direction: str) -> str:
     if direction not in DIRECTIONS:
         raise ValueError(f"direction must be one of {DIRECTIONS!r}, got {direction!r}")
@@ -158,27 +236,60 @@ class Message:
         """This message's `Message-ID`, or None when headers were not stored."""
         return self.header("message-id")
 
+    @property
+    def reply_to_address(self) -> str | None:
+        """Where a reply should actually go: `Reply-To`, else `From`, else the envelope sender.
+
+        `.sender` is the SMTP envelope sender (MAIL FROM). For transactional mail that is
+        usually a bounce address such as `bounces+abc@sendgrid.net`, so replying to it reaches
+        a bounce processor rather than a person. RFC 5322 says a reply goes to `Reply-To` when
+        present and to `From` otherwise; the envelope address is only a last resort.
+        """
+        for name in ("reply-to", "from"):
+            value = self.header(name)
+            if isinstance(value, list):
+                value = value[0] if value else None
+            if value:
+                addr = parseaddr(str(value))[1]
+                if addr and "@" in addr:
+                    return addr
+        return self.sender
+
     def reply(self, body: str = "", *, html: str | None = None,
-              subject: str | None = None) -> dict[str, Any]:
+              subject: str | None = None, cc: list[str] | None = None,
+              bcc: list[str] | None = None,
+              attachments: list[Any] | None = None) -> dict[str, Any]:
         """Reply to this message, keeping it in the same conversation.
 
         Fills in what a reply needs and is easy to get wrong by hand: the recipient, an
         `Re:` subject that is not doubled up, and the `In-Reply-To` / `References` headers
         Gmail and Outlook use to thread. Without those headers a reply shows up as a separate
         conversation, which is what a hand-rolled `send()` produces.
+
+        The recipient comes from `reply_to_address`, not from `.sender`: the envelope sender of
+        transactional mail is usually a bounce address, so `send(to=msg.sender, ...)` quietly
+        delivers the reply to a machine.
+
+        Takes everything `send()` takes, attachments included — answering a mail with a
+        file attached is the normal case, and an agent should not have to drop back to
+        `send()` (losing the threading headers) just to attach one.
         """
         if self._inbox is None:
             raise ValueError(
                 "This message isn't attached to an inbox. Use inbox.send(...) instead."
             )
-        if not self.sender:
+        target = self.reply_to_address
+        if not target:
             raise ValueError("This message has no sender to reply to.")
         return self._inbox.send(
-            self.sender,
+            target,
             subject=subject if subject is not None else _reply_subject(self.subject),
             body=body,
             html=html,
             in_reply_to=self.message_id,
+            cc=cc,
+            bcc=bcc,
+            attachments=attachments,
         )
 
     def mark_read(self) -> dict[str, Any]:
@@ -259,6 +370,17 @@ class Inbox:
             f"/api/v1/inboxes/{self.address}/messages?direction={direction}")
         return [self._wrap(e) for e in (res.get("emails") or [])]
 
+    def message(self, message_id: int) -> Message:
+        """Fetch one message by id — the way to ask "what happened to this send?".
+
+        Without it the only way to check a sent mail's status was to pull the whole
+        outbound list and find the id by hand, which for an agent that sent 100 mails
+        meant 100 messages per check.
+        """
+        res = self._client._get(
+            f"/api/v1/inboxes/{self.address}/messages/{message_id}")
+        return self._wrap(res.get("email") or {})
+
     def latest(self, *, direction: str = "in") -> Message | None:
         """Return the most recent message, or None when the inbox is empty.
 
@@ -368,23 +490,68 @@ class Inbox:
     # ----------------------------------------------------------------- yazma
     def send(
         self, to: str, *, subject: str = "", body: str = "", html: str | None = None,
-        in_reply_to: str | None = None,
+        in_reply_to: str | None = None, cc: list[str] | None = None,
+        bcc: list[str] | None = None, attachments: list[Any] | None = None,
     ) -> dict[str, Any]:
         """Send mail from this inbox's address (DKIM-signed, through our own MTA).
 
+        Returns as soon as the mail is **accepted for delivery** — not once it is
+        delivered. Delivery happens on a queue, so the response carries `message_id` and
+        `queued: true`; use `wait_until_sent(message_id)` (or a `message.delivered`
+        webhook) to find out how it ended. Blocking here would put back the exact stall
+        the queue was built to remove.
+
+        `attachments` takes file paths or dicts — the base64 encoding is done here:
+
+            inbox.send(to, attachments=["/tmp/invoice.pdf"])
+            inbox.send(to, attachments=[{"filename": "a.pdf", "content": raw_bytes}])
+
+        Size and count limits depend on the plan (free is deliberately small); going over
+        raises with the limit spelled out rather than silently dropping the file.
+
+        `bcc` recipients receive the mail but never appear in its headers — not even in
+        their own copy.
+
         Pass `in_reply_to` (a `Message-ID`) to keep the mail in an existing conversation;
         without it the recipient's client starts a new thread. `Message.reply()` fills this
         in for you.
 
         Not retried on gateway errors: a retried send can deliver the same mail twice.
         """
-        payload: dict[str, Any] = {"to": to, "subject": subject, "body": body}
-        if html is not None:
-            payload["html"] = html
-        if in_reply_to is not None:
-            payload["in_reply_to"] = in_reply_to
+        payload = _send_payload(to, subject, body, html, in_reply_to, cc, bcc, attachments)
         return self._client._post(f"/api/v1/inboxes/{self.address}/send", payload)
 
+    def wait_until_sent(self, message_id: int, *, timeout: float = 120.0,
+                        poll_interval: float = 2.0) -> Message:
+        """Block until a sent mail reaches a final delivery state.
+
+        `send()` is asynchronous, so "did it actually go out?" has no synchronous answer.
+        This polls the message until the server reports one, which is the pull half of the
+        contract (the push half is the `message.delivered` / `message.failed` webhook —
+        prefer that when you can receive one).
+
+        Returns the message on success. Raises `SendFailedError` if delivery permanently
+        failed and `SendTimeoutError` if it is still queued when the timeout elapses.
+        It does NOT return quietly on failure: a helper called `wait_until_sent` that
+        hands back a failed mail as if nothing happened is how mail goes missing.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            message = self.message(message_id)
+            status = message.send_status
+            if status in ("sent", "unsigned"):
+                return message
+            if status == "failed":
+                raise SendFailedError(
+                    message.send_error or "Delivery failed",
+                    message_id=message_id, status=status)
+            if time.monotonic() >= deadline:
+                raise SendTimeoutError(
+                    f"Message {message_id} was still {status or 'queued'} after "
+                    f"{timeout:g}s. It may still be delivered; the queue keeps retrying.",
+                    message_id=message_id, status=status)
+            time.sleep(min(poll_interval, max(0.0, deadline - time.monotonic())))
+
     def mark_read(self, message_id: int) -> dict[str, Any]:
         """Mark one message as read.
 

{mailflat-0.6.0 → mailflat-0.7.0}/src/mailflat/langchain.py

@@ -14,6 +14,11 @@ Usage:
 ⚠️ Tool output goes through `redact_secrets()`: a per-inbox `api_key` must never reach the
 model's context (and from there LangSmith traces) — see B-055.
 
+⚠️ `send_email` / `reply` take `cc` and `bcc` but NOT attachments. An address is a short
+string; file bytes would have to travel through the model's context, which costs tokens
+and is simply impossible for a multi-megabyte file. Attach files from the SDK
+(`inbox.send(..., attachments=[...])`) — the code surface, not the model surface.
+
 Connected to:
   - imports from: mailflat.client (MailFlat), mailflat.redact, langchain_core.tools
   - imported by:  user code (LangChain agents)
@@ -146,23 +151,31 @@ class MailFlatToolkit:
                 return {"email": None, "error": str(e)}
 
         def send_email(
-            address: str, to: str, subject: str = "", body: str = "", html: str = ""
+            address: str, to: str, subject: str = "", body: str = "", html: str = "",
+            cc: list[str] | None = None, bcc: list[str] | None = None,
         ) -> dict:
             """Send an email FROM the given inbox address (DKIM-signed via MailFlat's MTA).
 
+            Returns once the mail is ACCEPTED for delivery, not once it is delivered.
+
             Args:
                 address: The inbox address to send from (must belong to this API key).
                 to: Recipient email address.
                 subject: Email subject line.
                 body: Plain-text body.
                 html: Optional HTML body.
+                cc: Addresses to copy. They appear in the mail's headers.
+                bcc: Addresses to copy privately. They never appear in the headers.
             """
             try:
-                return redact_secrets(client.inbox(address).send(to, subject=subject, body=body, html=html or None))
+                return redact_secrets(client.inbox(address).send(
+                    to, subject=subject, body=body, html=html or None,
+                    cc=cc or None, bcc=bcc or None))
             except MailFlatError as e:
                 return {"error": str(e)}
 
-        def reply(address: str, message_id: int, body: str = "", html: str = "") -> dict:
+        def reply(address: str, message_id: int, body: str = "", html: str = "",
+                  cc: list[str] | None = None, bcc: list[str] | None = None) -> dict:
             """Reply to a message so it stays in the SAME conversation.
 
             Prefer this over send_email when answering: it fills in the recipient, an `Re:`
@@ -174,13 +187,16 @@ class MailFlatToolkit:
                 message_id: The id of the message to answer, as returned by read_messages.
                 body: Plain-text reply body.
                 html: Optional HTML body.
+                cc: Addresses to copy. They appear in the mail's headers.
+                bcc: Addresses to copy privately. They never appear in the headers.
             """
             try:
                 inbox = client.inbox(address)
                 target = next((m for m in inbox.messages(direction="all") if m.id == message_id), None)
                 if target is None:
                     return {"error": f"Message {message_id} not found in {address}"}
-                return redact_secrets(target.reply(body, html=html or None))
+                return redact_secrets(target.reply(body, html=html or None,
+                                                   cc=cc or None, bcc=bcc or None))
             except (MailFlatError, ValueError) as e:
                 return {"error": str(e)}