flowbox 0.1.0__tar.gz

flowbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flowmatic
+
+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.

flowbox-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: flowbox
+Version: 0.1.0
+Summary: A vendor-neutral email connector: read inboxes and send mail through the adapter you choose.
+Author: Flowmatic, UniForceMusic
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Flowmatic-AI/flowmatic-toolkit
+Project-URL: Repository, https://github.com/Flowmatic-AI/flowmatic-toolkit
+Project-URL: Issues, https://github.com/Flowmatic-AI/flowmatic-toolkit/issues
+Keywords: email,mail,inbox,outbox,smtp,imap,lettermint
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: settings
+Requires-Dist: pydantic-settings>=2.10; extra == "settings"
+Provides-Extra: dev
+Requires-Dist: pydantic-settings>=2.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: mypy>=2.0; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Dynamic: license-file
+
+# flowbox
+
+A vendor-neutral email connector: read inboxes and send mail through the adapter you choose. Standard library only.
+
+[`../project`](../project) is a small flowlab app that shows how to wire it into an application: settings, one factory module, a queued send job, polling and a webhook route.
+
+| Adapter             | Inbox | Webhooks | Outbox |
+|---------------------|:-----:|:--------:|:------:|
+| `IMAPAdapter`       |   ✓   |          |        |
+| `SMTPAdapter`       |       |          |   ✓    |
+| `LettermintAdapter` |   ✓   |    ✓     |   ✓    |
+| `LogAdapter`        |       |          |   ✓    |
+
+`LogAdapter` sends nothing; it logs each message on the `flowbox.log` logger, like Laravel's log mailer. Use it for local work, not production.
+
+`FlowOutbox` takes an `OutboxAdapterABC`. `FlowInbox` takes an `InboxAdapterABC` (a mailbox you read from), a `WebhookInboxAdapterABC` (a provider that pushes mail to you), or an adapter that is both. Using an adapter for something it cannot do — `FlowInbox(SMTPAdapter(...))`, or `parse_webhook()` on an IMAP inbox — is a type error, so mypy or your editor flags it before it runs.
+
+## Settings from the environment
+
+`pip install flowbox[settings]` adds `FlowboxSettings`, a pydantic-settings class that picks the adapters from environment variables and builds the flows. Subclass it for your app's own settings:
+
+```python
+from pydantic_settings import SettingsConfigDict
+
+from flowbox.settings import FlowboxSettings
+
+
+class Settings(FlowboxSettings):
+    model_config = SettingsConfigDict(env_file=".env")
+
+
+settings = Settings()
+
+with settings.outbox() as outbox:
+    outbox.send_mail(message)
+
+with settings.inbox() as inbox:
+    messages = inbox.retrieve_mails("INBOX", since)
+```
+
+Each `outbox()` / `inbox()` call builds a new flow: open one per job, command or request, since IMAP and SMTP adapters hold a socket and are not thread-safe. Construction fails when a selected driver is missing its credentials, and the error names the variables to set, never their values.
+
+| Variable | Default | Used for |
+|---|---|---|
+| `MAIL_OUTBOX` | `log` | `log`, `smtp` or `lettermint` |
+| `MAIL_INBOX` | unset | `imap` or `lettermint`; unset when the app reads no mail |
+| `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME` | unset | The sender of messages that set none |
+| `MAIL_TIMEOUT` | `30` | Seconds before a provider call gives up |
+| `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD` | | `MAIL_OUTBOX=smtp`; the port follows the encryption when unset |
+| `SMTP_ENCRYPTION` | `starttls` | `ssl`, `starttls` or `none` |
+| `IMAP_HOST`, `IMAP_PORT`, `IMAP_USERNAME`, `IMAP_PASSWORD` | | `MAIL_INBOX=imap` |
+| `IMAP_ENCRYPTION` | `ssl` | `ssl`, `starttls` or `none` |
+| `LETTERMINT_PROJECT_TOKEN`, `LETTERMINT_ROUTE` | | `MAIL_OUTBOX=lettermint` |
+| `LETTERMINT_TEAM_TOKEN`, `LETTERMINT_PROJECT_ID` | | `MAIL_INBOX=lettermint` |
+| `LETTERMINT_WEBHOOK_SECRET` | | `settings.lettermint_webhooks()` |
+
+Webhooks stay per vendor: `settings.lettermint_webhooks()` returns a `FlowInbox[LettermintAdapter]` for that vendor's webhook route. Your own adapter goes in by overriding `outbox_adapter()` or `inbox_adapter()`:
+
+```python
+class Settings(FlowboxSettings):
+    crm_api_key: str | None = None
+
+    def outbox_adapter(self) -> OutboxAdapterABC:
+        if self.crm_api_key:
+            return CRMAdapter(self.crm_api_key)
+        return super().outbox_adapter()
+```
+
+`flowbox.settings` is the only module that reads the environment, and the core never imports it.
+
+## Sending
+
+```python
+from flowbox import Address, Attachment, FlowOutbox, Message
+
+with FlowOutbox.connect_smtp("smtp.example.com", "user", "secret", sender=Address("noreply@acme.com", "Acme")) as outbox:
+    message_id = outbox.send_mail(
+        Message(
+            subject="Your invoice",
+            to=[Address("customer@example.com")],
+            text="Your invoice is attached.",
+            attachments=[Attachment.from_path("invoice.pdf")],
+        )
+    )
+```
+
+## Reading
+
+```python
+from datetime import datetime, timedelta
+
+from flowbox import FlowInbox
+
+with FlowInbox.connect_imap("imap.example.com", "user", "secret") as inbox:
+    print(inbox.get_mailboxes())
+
+    for message in inbox.retrieve_mails("INBOX", datetime.now() - timedelta(days=1)):
+        print(message.received_at, message.sender, message.subject)
+```
+
+`retrieve_mails()` returns everything received at or after `from_datetime`, oldest first, and never marks mail as read.
+
+## Webhooks
+
+Providers that push received mail to you sign and shape their webhooks differently; the adapter verifies the signature and translates the payload. Hand it the raw request body, before any JSON or form parsing, and the headers:
+
+```python
+from fastapi import FastAPI, HTTPException, Request
+
+from flowbox import FlowInbox, SignatureError
+
+app = FastAPI()
+inbox = FlowInbox.connect_lettermint(webhook_secret="whsec_...")
+
+
+@app.post("/webhooks/inbound")
+async def inbound(request: Request) -> None:
+    try:
+        message = inbox.parse_webhook(await request.body(), request.headers)
+    except SignatureError:
+        raise HTTPException(status_code=401)
+    ...
+```
+
+Responding is up to your app. Providers retry deliveries that get no 2xx, so the same message can arrive twice; `message.id` stays the same.
+
+## Lettermint
+
+One adapter covers everything; each part needs only its own credential. Sending uses a project token (`lm_...`), `retrieve_mails()` a team token (`lm_team_...`) with the team's inbound routes as the mailboxes, and `parse_webhook()` the inbound route webhook's signing secret (`whsec_...`).
+
+```python
+from flowbox import Address, FlowInbox, FlowOutbox
+from flowbox.adapters import LettermintAdapter
+
+lettermint = LettermintAdapter(project_token="lm_...", team_token="lm_team_...", webhook_secret="whsec_...")
+
+inbox = FlowInbox(lettermint)
+outbox = FlowOutbox(lettermint, sender=Address("noreply@acme.com"))
+```

flowbox-0.1.0/README.md

@@ -0,0 +1,139 @@
+# flowbox
+
+A vendor-neutral email connector: read inboxes and send mail through the adapter you choose. Standard library only.
+
+[`../project`](../project) is a small flowlab app that shows how to wire it into an application: settings, one factory module, a queued send job, polling and a webhook route.
+
+| Adapter             | Inbox | Webhooks | Outbox |
+|---------------------|:-----:|:--------:|:------:|
+| `IMAPAdapter`       |   ✓   |          |        |
+| `SMTPAdapter`       |       |          |   ✓    |
+| `LettermintAdapter` |   ✓   |    ✓     |   ✓    |
+| `LogAdapter`        |       |          |   ✓    |
+
+`LogAdapter` sends nothing; it logs each message on the `flowbox.log` logger, like Laravel's log mailer. Use it for local work, not production.
+
+`FlowOutbox` takes an `OutboxAdapterABC`. `FlowInbox` takes an `InboxAdapterABC` (a mailbox you read from), a `WebhookInboxAdapterABC` (a provider that pushes mail to you), or an adapter that is both. Using an adapter for something it cannot do — `FlowInbox(SMTPAdapter(...))`, or `parse_webhook()` on an IMAP inbox — is a type error, so mypy or your editor flags it before it runs.
+
+## Settings from the environment
+
+`pip install flowbox[settings]` adds `FlowboxSettings`, a pydantic-settings class that picks the adapters from environment variables and builds the flows. Subclass it for your app's own settings:
+
+```python
+from pydantic_settings import SettingsConfigDict
+
+from flowbox.settings import FlowboxSettings
+
+
+class Settings(FlowboxSettings):
+    model_config = SettingsConfigDict(env_file=".env")
+
+
+settings = Settings()
+
+with settings.outbox() as outbox:
+    outbox.send_mail(message)
+
+with settings.inbox() as inbox:
+    messages = inbox.retrieve_mails("INBOX", since)
+```
+
+Each `outbox()` / `inbox()` call builds a new flow: open one per job, command or request, since IMAP and SMTP adapters hold a socket and are not thread-safe. Construction fails when a selected driver is missing its credentials, and the error names the variables to set, never their values.
+
+| Variable | Default | Used for |
+|---|---|---|
+| `MAIL_OUTBOX` | `log` | `log`, `smtp` or `lettermint` |
+| `MAIL_INBOX` | unset | `imap` or `lettermint`; unset when the app reads no mail |
+| `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME` | unset | The sender of messages that set none |
+| `MAIL_TIMEOUT` | `30` | Seconds before a provider call gives up |
+| `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD` | | `MAIL_OUTBOX=smtp`; the port follows the encryption when unset |
+| `SMTP_ENCRYPTION` | `starttls` | `ssl`, `starttls` or `none` |
+| `IMAP_HOST`, `IMAP_PORT`, `IMAP_USERNAME`, `IMAP_PASSWORD` | | `MAIL_INBOX=imap` |
+| `IMAP_ENCRYPTION` | `ssl` | `ssl`, `starttls` or `none` |
+| `LETTERMINT_PROJECT_TOKEN`, `LETTERMINT_ROUTE` | | `MAIL_OUTBOX=lettermint` |
+| `LETTERMINT_TEAM_TOKEN`, `LETTERMINT_PROJECT_ID` | | `MAIL_INBOX=lettermint` |
+| `LETTERMINT_WEBHOOK_SECRET` | | `settings.lettermint_webhooks()` |
+
+Webhooks stay per vendor: `settings.lettermint_webhooks()` returns a `FlowInbox[LettermintAdapter]` for that vendor's webhook route. Your own adapter goes in by overriding `outbox_adapter()` or `inbox_adapter()`:
+
+```python
+class Settings(FlowboxSettings):
+    crm_api_key: str | None = None
+
+    def outbox_adapter(self) -> OutboxAdapterABC:
+        if self.crm_api_key:
+            return CRMAdapter(self.crm_api_key)
+        return super().outbox_adapter()
+```
+
+`flowbox.settings` is the only module that reads the environment, and the core never imports it.
+
+## Sending
+
+```python
+from flowbox import Address, Attachment, FlowOutbox, Message
+
+with FlowOutbox.connect_smtp("smtp.example.com", "user", "secret", sender=Address("noreply@acme.com", "Acme")) as outbox:
+    message_id = outbox.send_mail(
+        Message(
+            subject="Your invoice",
+            to=[Address("customer@example.com")],
+            text="Your invoice is attached.",
+            attachments=[Attachment.from_path("invoice.pdf")],
+        )
+    )
+```
+
+## Reading
+
+```python
+from datetime import datetime, timedelta
+
+from flowbox import FlowInbox
+
+with FlowInbox.connect_imap("imap.example.com", "user", "secret") as inbox:
+    print(inbox.get_mailboxes())
+
+    for message in inbox.retrieve_mails("INBOX", datetime.now() - timedelta(days=1)):
+        print(message.received_at, message.sender, message.subject)
+```
+
+`retrieve_mails()` returns everything received at or after `from_datetime`, oldest first, and never marks mail as read.
+
+## Webhooks
+
+Providers that push received mail to you sign and shape their webhooks differently; the adapter verifies the signature and translates the payload. Hand it the raw request body, before any JSON or form parsing, and the headers:
+
+```python
+from fastapi import FastAPI, HTTPException, Request
+
+from flowbox import FlowInbox, SignatureError
+
+app = FastAPI()
+inbox = FlowInbox.connect_lettermint(webhook_secret="whsec_...")
+
+
+@app.post("/webhooks/inbound")
+async def inbound(request: Request) -> None:
+    try:
+        message = inbox.parse_webhook(await request.body(), request.headers)
+    except SignatureError:
+        raise HTTPException(status_code=401)
+    ...
+```
+
+Responding is up to your app. Providers retry deliveries that get no 2xx, so the same message can arrive twice; `message.id` stays the same.
+
+## Lettermint
+
+One adapter covers everything; each part needs only its own credential. Sending uses a project token (`lm_...`), `retrieve_mails()` a team token (`lm_team_...`) with the team's inbound routes as the mailboxes, and `parse_webhook()` the inbound route webhook's signing secret (`whsec_...`).
+
+```python
+from flowbox import Address, FlowInbox, FlowOutbox
+from flowbox.adapters import LettermintAdapter
+
+lettermint = LettermintAdapter(project_token="lm_...", team_token="lm_team_...", webhook_secret="whsec_...")
+
+inbox = FlowInbox(lettermint)
+outbox = FlowOutbox(lettermint, sender=Address("noreply@acme.com"))
+```

flowbox-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flowbox"
+version = "0.1.0"
+description = "A vendor-neutral email connector: read inboxes and send mail through the adapter you choose."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["email", "mail", "inbox", "outbox", "smtp", "imap", "lettermint"]
+
+authors = [
+    {name = "Flowmatic"},
+    {name = "UniForceMusic"},
+]
+
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Email",
+    "Typing :: Typed",
+]
+
+# Standard library only, Lettermint included: its API is plain JSON over HTTPS.
+# flowbox.settings, which reads the environment, is the one extra.
+dependencies = []
+
+[project.optional-dependencies]
+settings = ["pydantic-settings>=2.10"]
+dev = [
+    "pydantic-settings>=2.10",
+    "build>=1.2",
+    "twine>=5.0",
+    "pytest>=9.0",
+    "mypy>=2.0",
+    "ruff>=0.16",
+]
+
+[project.urls]
+Homepage = "https://github.com/Flowmatic-AI/flowmatic-toolkit"
+Repository = "https://github.com/Flowmatic-AI/flowmatic-toolkit"
+Issues = "https://github.com/Flowmatic-AI/flowmatic-toolkit/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+flowbox = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.mypy]
+strict = true
+python_version = "3.14"
+ignore_missing_imports = true
+
+[tool.ruff]
+target-version = "py314"
+line-length = 120

flowbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flowbox-0.1.0/src/flowbox/__init__.py

@@ -0,0 +1,14 @@
+from flowbox._exceptions import AdapterError, MessageError, SignatureError
+from flowbox._flowbox import FlowInbox, FlowOutbox
+from flowbox._message import Address, Attachment, Message
+
+__all__ = [
+    "AdapterError",
+    "Address",
+    "Attachment",
+    "FlowInbox",
+    "FlowOutbox",
+    "Message",
+    "MessageError",
+    "SignatureError",
+]

flowbox-0.1.0/src/flowbox/_exceptions.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+
+class AdapterError(Exception):
+    pass
+
+
+class SignatureError(AdapterError):
+    pass
+
+
+class MessageError(Exception):
+    pass

flowbox-0.1.0/src/flowbox/_flowbox.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from datetime import datetime
+from types import TracebackType
+from typing import TYPE_CHECKING, Self
+
+from flowbox._exceptions import MessageError
+
+if TYPE_CHECKING:
+    import ssl
+
+    from flowbox._message import Address, Message
+    from flowbox.adapters import (
+        Encryption,
+        IMAPAdapter,
+        InboxAdapterABC,
+        LettermintAdapter,
+        OutboxAdapterABC,
+        WebhookInboxAdapterABC,
+    )
+
+
+class FlowInbox[AdapterT: InboxAdapterABC | WebhookInboxAdapterABC]:
+    """Reads mail through a mailbox adapter, a webhook adapter, or one that is both.
+
+    Each method is annotated with the adapter kind it needs, so calling one the
+    adapter cannot serve -- parse_webhook() on an IMAP inbox, say -- is flagged
+    by the type checker rather than failing at runtime."""
+
+    def __init__(self, adapter: AdapterT) -> None:
+        self._adapter = adapter
+
+    @staticmethod
+    def connect_imap(
+        host: str,
+        username: str,
+        password: str,
+        port: int | None = None,
+        encryption: Encryption = "ssl",
+        timeout: float | None = 30.0,
+        ssl_context: ssl.SSLContext | None = None,
+    ) -> FlowInbox[IMAPAdapter]:
+        from flowbox.adapters import IMAPAdapter
+
+        return FlowInbox(IMAPAdapter(host, username, password, port, encryption, timeout, ssl_context))
+
+    @staticmethod
+    def connect_lettermint(
+        team_token: str | None = None,
+        webhook_secret: str | None = None,
+        project_id: str | None = None,
+        timeout: float = 30.0,
+    ) -> FlowInbox[LettermintAdapter]:
+        """``team_token`` is for retrieve_mails(), ``webhook_secret`` (``whsec_...``)
+        for parse_webhook(); pass whichever this inbox uses."""
+        from flowbox.adapters import LettermintAdapter
+
+        adapter = LettermintAdapter(
+            team_token=team_token, webhook_secret=webhook_secret, project_id=project_id, timeout=timeout
+        )
+        return FlowInbox(adapter)
+
+    @property
+    def adapter(self) -> AdapterT:
+        return self._adapter
+
+    def get_mailboxes(self: FlowInbox[InboxAdapterABC]) -> list[str]:
+        return self._adapter.get_mailboxes()
+
+    def retrieve_mails(self: FlowInbox[InboxAdapterABC], mailbox: str, from_datetime: datetime) -> list[Message]:
+        return self._adapter.retrieve_mails(mailbox, from_datetime)
+
+    def parse_webhook(self: FlowInbox[WebhookInboxAdapterABC], body: bytes, headers: Mapping[str, str]) -> Message:
+        """Pass the raw request body, before any JSON or form parsing."""
+        return self._adapter.parse_webhook(body, headers)
+
+    def close(self) -> None:
+        self._adapter.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, traceback: TracebackType | None
+    ) -> None:
+        self.close()
+
+
+class FlowOutbox:
+    def __init__(self, adapter: OutboxAdapterABC, sender: Address | None = None) -> None:
+        self._adapter = adapter
+        #: Used for every message that does not set its own sender.
+        self._sender = sender
+
+    @classmethod
+    def connect_smtp(
+        cls,
+        host: str,
+        username: str | None = None,
+        password: str | None = None,
+        port: int | None = None,
+        encryption: Encryption = "starttls",
+        timeout: float = 30.0,
+        sender: Address | None = None,
+        ssl_context: ssl.SSLContext | None = None,
+    ) -> Self:
+        from flowbox.adapters import SMTPAdapter
+
+        adapter = SMTPAdapter(host, username, password, port, encryption, timeout, ssl_context=ssl_context)
+        return cls(adapter, sender)
+
+    @classmethod
+    def connect_lettermint(
+        cls,
+        project_token: str,
+        route: str | None = None,
+        sender: Address | None = None,
+        timeout: float = 30.0,
+    ) -> Self:
+        from flowbox.adapters import LettermintAdapter
+
+        return cls(LettermintAdapter(project_token=project_token, route=route, timeout=timeout), sender)
+
+    @property
+    def adapter(self) -> OutboxAdapterABC:
+        return self._adapter
+
+    @property
+    def sender(self) -> Address | None:
+        return self._sender
+
+    def send_mail(self, message: Message) -> str:
+        """Send the message and return the provider's id for it."""
+        if message.sender is None:
+            if self._sender is None:
+                raise MessageError("the message has no sender and the outbox has no default sender")
+            message = replace(message, sender=self._sender)
+
+        if not message.to:
+            raise MessageError("the message has no recipients in 'to'")
+        if message.text is None and message.html is None:
+            raise MessageError("the message has neither a text nor an html body")
+
+        return self._adapter.send_mail(message)
+
+    def close(self) -> None:
+        self._adapter.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, traceback: TracebackType | None
+    ) -> None:
+        self.close()

flowbox-0.1.0/src/flowbox/_message.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import mimetypes
+from dataclasses import dataclass, field
+from datetime import datetime
+from email.utils import formataddr, parseaddr
+from pathlib import Path
+
+
+@dataclass(slots=True, frozen=True)
+class Address:
+    email: str
+    name: str | None = None
+
+    @classmethod
+    def parse(cls, value: str) -> Address:
+        """``"Jane Doe <jane@example.com>"`` or a bare ``"jane@example.com"``."""
+        name, email = parseaddr(value)
+        return cls(email=email, name=name or None)
+
+    def __str__(self) -> str:
+        return formataddr((self.name, self.email)) if self.name else self.email
+
+
+@dataclass(slots=True)
+class Attachment:
+    filename: str
+    content: bytes
+    #: Guessed from the filename when left empty.
+    content_type: str = ""
+    #: Makes the attachment inline: the HTML body references it as ``cid:<content_id>``.
+    content_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.content_type:
+            self.content_type = mimetypes.guess_type(self.filename)[0] or "application/octet-stream"
+
+    @classmethod
+    def from_path(cls, path: str | Path, content_id: str | None = None) -> Attachment:
+        path = Path(path)
+        return cls(filename=path.name, content=path.read_bytes(), content_id=content_id)
+
+
+@dataclass(slots=True)
+class Message:
+    subject: str
+    to: list[Address] = field(default_factory=list)
+    #: Falls back to the outbox's default sender when sending.
+    sender: Address | None = None
+    cc: list[Address] = field(default_factory=list)
+    bcc: list[Address] = field(default_factory=list)
+    reply_to: list[Address] = field(default_factory=list)
+    text: str | None = None
+    html: str | None = None
+    attachments: list[Attachment] = field(default_factory=list)
+    headers: dict[str, str] = field(default_factory=dict)
+    #: Set by the adapter on retrieved mail: the provider's id for the message.
+    id: str | None = None
+    #: Set by the adapter on retrieved mail: when the provider received it.
+    received_at: datetime | None = None