dex-connector-postmark 0.1.0__py3-none-any.whl

dex_connector_postmark-0.1.0.dist-info/METADATA

@@ -0,0 +1,50 @@
+Metadata-Version: 2.5
+Name: dex-connector-postmark
+Version: 0.1.0
+Summary: Postmark connector for Dex Flows
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: dex-connectors-sdk==0.1.0
+Requires-Dist: dex-python-sdk>=1.28.0
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# Postmark connector for Python
+
+Install with `pip install dex-connector-postmark==0.1.0`. The package requires
+`dex-connectors-sdk==0.1.0` and `dex-python-sdk>=1.28.0`, and implements the
+manifest Queries `listOutboundMessages` and `getMessageDetails` with the same
+branches, defaults, and failure classification as the Go module.
+
+## Operations
+
+| Operation | Factory | Happy branch | Optional branches |
+| --- | --- | --- | --- |
+| `listOutboundMessages` | `new_list_outbound_messages_step` | `listed` | `providerRejected`, `invalidResponse`, `defect` |
+| `getMessageDetails` | `new_get_message_details_step` | `found` | `notFound`, `providerRejected`, `invalidResponse`, `defect` |
+
+`listOutboundMessages` sends `count` (zero means 50, at most 500) and `offset`;
+`count + offset` must stay within Postmark's 10,000-message search window.
+`getMessageDetails` selects `notFound` for HTTP 404 or Postmark error code 701.
+408, 429, 5xx, and transport failures retry; other 4xx responses select
+`providerRejected`.
+
+## Authorization
+
+Create a Dex Web connection named `postmark` as described in the
+[connector README](../README.md#authorization). The Server API token travels
+only in the `X-Postmark-Server-Token` header and is resolved for every attempt.
+
+## Example
+
+[`examples/outbound_lookup`](examples/outbound_lookup/flow.py) checks the page
+window, lists outbound messages with `new_list_outbound_messages_step`, and
+records the page. Run the Worker with
+`uv run python -m examples.outbound_lookup.worker` after `dexcli dev` has
+loaded a project containing the `postmark` connection.
+
+## Tests
+
+`postmarkmock.Mock` scripts both Queries and defaults to the manifest mock
+answers. Run `uv run pytest tests` for provider parity and manifest contract
+checks.

dex_connector_postmark-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+dex_connectors/postmark/__init__.py,sha256=_-6rphGp1B5jm4pplvG41pEQyN0rdcYIcwd1sfKYkOc,1368
+dex_connectors/postmark/client.py,sha256=fr0F7Top4DMusNlhq7reqnGhOnu1dvCVfYvaq9uaXwY,14296
+dex_connectors/postmark/connection.py,sha256=_zzu6nP9iCV5vk1S6HOeOWHRV1h2-TNScpsijXQt5SY,5746
+dex_connectors/postmark/dex-connector.json,sha256=lCZYDCAHAxL8WjAJN1YMy5vOonwcYWYkg8M63TmfBR4,1906
+dex_connectors/postmark/models.py,sha256=oBWOKOh2PZOZmNv7Z_oIr6AqvEcu0I7lUwJnR3xo_wg,1252
+dex_connectors/postmark/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dex_connectors/postmark/steps.py,sha256=FYDZ8aRLGkaqq3nmoyBkA_yxidKmX_qOsxTUli3Q6nU,4995
+dex_connectors/postmark/postmarkmock/__init__.py,sha256=mNgxsoSFW28qfRkhRhgWk5Ff5IXEwxYNc_wCHckzlVg,3219
+dex_connector_postmark-0.1.0.dist-info/METADATA,sha256=eoQLvRX6tzkY6m8S0f1OQ8L4Wsz4Ma07S3iT6jTKP0o,2064
+dex_connector_postmark-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+dex_connector_postmark-0.1.0.dist-info/RECORD,,

dex_connector_postmark-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dex_connectors/postmark/__init__.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Postmark outbound message operations for Dex connector Steps."""
+
+from .client import (
+    CONNECTOR_ID,
+    DEFECT,
+    FOUND,
+    GET_MESSAGE_DETAILS_DEFINITION,
+    INVALID_RESPONSE,
+    LIST_OUTBOUND_MESSAGES_DEFINITION,
+    LISTED,
+    NOT_FOUND,
+    PROVIDER_REJECTED,
+    Client,
+    Config,
+    Credentials,
+    GetMessageDetailsOperation,
+    ListOutboundMessagesOperation,
+)
+from .connection import Connection, new_connection, new_connection_with_operations, new_project_connection
+from .models import GetMessageDetailsInput, ListOutboundMessagesInput, MessageDetails, MessagePage
+from .steps import new_get_message_details_step, new_list_outbound_messages_step
+
+__all__ = [
+    "Client",
+    "Config",
+    "Connection",
+    "Credentials",
+    "GetMessageDetailsInput",
+    "GetMessageDetailsOperation",
+    "ListOutboundMessagesInput",
+    "ListOutboundMessagesOperation",
+    "MessageDetails",
+    "MessagePage",
+    "new_connection",
+    "new_connection_with_operations",
+    "new_get_message_details_step",
+    "new_list_outbound_messages_step",
+    "new_project_connection",
+    "CONNECTOR_ID",
+    "DEFECT",
+    "FOUND",
+    "GET_MESSAGE_DETAILS_DEFINITION",
+    "INVALID_RESPONSE",
+    "LIST_OUTBOUND_MESSAGES_DEFINITION",
+    "LISTED",
+    "NOT_FOUND",
+    "PROVIDER_REJECTED",
+]

dex_connectors/postmark/client.py

@@ -0,0 +1,375 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Postmark provider calls and Go-compatible branch classification."""
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any, TypeVar
+from urllib.parse import quote
+
+import httpx
+from dex_connectors.sdk import (
+    BranchDefinition,
+    Call,
+    CredentialProvider,
+    Failure,
+    FailureKind,
+    OperationRef,
+    QueryAttempt,
+    QueryDefinition,
+    ReauthorizationRequiredError,
+    Receipt,
+    SecretString,
+    StepDefaults,
+)
+from dex_connectors.sdk.providerhttp import (
+    MAX_ERROR_BODY_BYTES,
+    BodyTooLargeError,
+    ProviderTransportError,
+    is_header_safe_credential,
+    new_provider_http_client,
+    parse_retry_after,
+    read_bounded_body,
+    send_traced,
+    validate_base_url,
+)
+from dex_connectors.sdk.retry_policy import default_connector_step_execute_retry_policy
+
+from .models import GetMessageDetailsInput, ListOutboundMessagesInput, MessageDetails, MessagePage
+
+CONNECTOR_ID = "postmark"
+LIST_OUTBOUND_MESSAGES_OPERATION_ID = "listOutboundMessages"
+GET_MESSAGE_DETAILS_OPERATION_ID = "getMessageDetails"
+LISTED = "listed"
+FOUND = "found"
+NOT_FOUND = "notFound"
+PROVIDER_REJECTED = "providerRejected"
+INVALID_RESPONSE = "invalidResponse"
+DEFECT = "defect"
+_DEFAULT_BASE_URL = "https://api.postmarkapp.com"
+_DEFAULT_TIMEOUT_SECONDS = 15
+_DEFAULT_MAX_RESPONSE_BYTES = 2_097_152
+_MESSAGE_NOT_FOUND_ERROR_CODE = 701
+_STEP_DEFAULTS = StepDefaults(
+    timedelta(seconds=30), 2, execute_retry=default_connector_step_execute_retry_policy()
+)
+_SHARED_BRANCHES = (
+    BranchDefinition(PROVIDER_REJECTED, "The provider definitively rejected the request.", True),
+    BranchDefinition(INVALID_RESPONSE, "The provider returned malformed or oversized JSON.", True),
+    BranchDefinition(DEFECT, "Local input or connection credentials are invalid.", True),
+)
+LIST_OUTBOUND_MESSAGES_DEFINITION = QueryDefinition(
+    OperationRef(CONNECTOR_ID, LIST_OUTBOUND_MESSAGES_OPERATION_ID),
+    (BranchDefinition(LISTED, "Postmark returned the requested result."), *_SHARED_BRANCHES),
+    _STEP_DEFAULTS,
+)
+GET_MESSAGE_DETAILS_DEFINITION = QueryDefinition(
+    OperationRef(CONNECTOR_ID, GET_MESSAGE_DETAILS_OPERATION_ID),
+    (
+        BranchDefinition(FOUND, "Postmark returned the requested result."),
+        BranchDefinition(NOT_FOUND, "The requested resource does not exist.", True),
+        *_SHARED_BRANCHES,
+    ),
+    _STEP_DEFAULTS,
+)
+
+Output = TypeVar("Output")
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    """Postmark HTTP settings; zero or blank values use manifest defaults."""
+
+    base_url: str = _DEFAULT_BASE_URL
+    timeout_seconds: float = _DEFAULT_TIMEOUT_SECONDS
+    max_response_bytes: int = _DEFAULT_MAX_RESPONSE_BYTES
+
+
+@dataclass(frozen=True, slots=True)
+class Credentials:
+    """Postmark Server API token, resolved anew for every provider attempt."""
+
+    api_key: SecretString
+
+
+class Client:
+    """One redirect-safe HTTP client and call-time credential source."""
+
+    def __init__(
+        self,
+        config: Config,
+        credentials: CredentialProvider[Credentials],
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if config is None:
+            raise ValueError("Postmark configuration is required")
+        if credentials is None:
+            raise ValueError("Postmark credential source is required")
+        self.base_url = validate_base_url(config.base_url or _DEFAULT_BASE_URL)
+        if config.timeout_seconds < 0 or config.max_response_bytes < 0:
+            raise ValueError("Postmark timeout and max response bytes must be positive")
+        self.max_response_bytes = config.max_response_bytes or _DEFAULT_MAX_RESPONSE_BYTES
+        self.credentials = credentials
+        self.http_client = http_client or new_provider_http_client(
+            config.timeout_seconds or _DEFAULT_TIMEOUT_SECONDS
+        )
+
+    def list_outbound_messages(self) -> "ListOutboundMessagesOperation":
+        """Bind the outbound message search Query to this client."""
+        return ListOutboundMessagesOperation(self)
+
+    def get_message_details(self) -> "GetMessageDetailsOperation":
+        """Bind the message details Query to this client."""
+        return GetMessageDetailsOperation(self)
+
+    async def aclose(self) -> None:
+        """Close the owned provider HTTP client after application shutdown."""
+        await self.http_client.aclose()
+
+    async def _run_query(
+        self,
+        call: Call,
+        operation: str,
+        path: str,
+        empty: Output,
+        success: str,
+        decode: Callable[[dict[str, Any]], Output],
+        is_message_lookup: bool = False,
+    ) -> QueryAttempt[Output]:
+        """Send one GET and classify it exactly like the Go runQuery helper."""
+        try:
+            credentials = await self.credentials.resolve(call)
+        except (ValueError, LookupError, OSError, ReauthorizationRequiredError):
+            return _branch(
+                operation, DEFECT, empty, FailureKind.AUTHENTICATION, "connection credentials are unavailable"
+            )
+        token = credentials.api_key.reveal()
+        if not token.strip() or not is_header_safe_credential(token):
+            return _branch(
+                operation, DEFECT, empty, FailureKind.AUTHENTICATION, "connection credentials are invalid"
+            )
+        headers = {
+            "X-Postmark-Server-Token": token,
+            "Accept": "application/json",
+            "User-Agent": "superdurable-postmark/0.1",
+        }
+        try:
+            request = self.http_client.build_request("GET", self.base_url + path, headers=headers)
+        except (httpx.HTTPError, ValueError):
+            return _branch(
+                operation, DEFECT, empty, FailureKind.LOCAL_DEFECT, "Postmark request could not be built"
+            )
+        try:
+            response, _ = await send_traced(self.http_client, request)
+        except ProviderTransportError:
+            return QueryAttempt.retry(
+                _failure(operation, FailureKind.AVAILABILITY, "provider request failed")
+            )
+        try:
+            status = response.status_code
+            if status == 429:
+                return QueryAttempt.retry(
+                    _failure(operation, FailureKind.RATE_LIMIT, "provider rate limited the request"),
+                    _retry_after_seconds(response),
+                )
+            if status == 408 or status >= 500:
+                return QueryAttempt.retry(
+                    _failure(operation, FailureKind.AVAILABILITY, "provider is temporarily unavailable"),
+                    _retry_after_seconds(response),
+                )
+            if is_message_lookup and status == 422:
+                if await _is_message_not_found(response):
+                    return _branch(
+                        operation, NOT_FOUND, empty, FailureKind.NOT_FOUND, "Postmark message was not found"
+                    )
+                return _branch(
+                    operation,
+                    PROVIDER_REJECTED,
+                    empty,
+                    FailureKind.PROVIDER_REJECTION,
+                    "Postmark rejected the message request",
+                )
+            if status == 404 and is_message_lookup:
+                return _branch(
+                    operation, NOT_FOUND, empty, FailureKind.NOT_FOUND, "provider resource was not found"
+                )
+            if status != 200:
+                return _branch(
+                    operation,
+                    PROVIDER_REJECTED,
+                    empty,
+                    FailureKind.PROVIDER_REJECTION,
+                    f"provider rejected the request with HTTP {status}",
+                )
+            try:
+                content = await read_bounded_body(response, self.max_response_bytes)
+            except BodyTooLargeError:
+                return _branch(
+                    operation,
+                    INVALID_RESPONSE,
+                    empty,
+                    FailureKind.RESPONSE_TOO_LARGE,
+                    "provider response exceeded the configured limit",
+                )
+            except ProviderTransportError:
+                return QueryAttempt.retry(
+                    _failure(operation, FailureKind.AVAILABILITY, "provider response was interrupted")
+                )
+            try:
+                document = json.loads(content)
+                if not isinstance(document, dict):
+                    raise ValueError
+                value = decode(document)
+            except (ValueError, TypeError, UnicodeDecodeError):
+                return _branch(
+                    operation,
+                    INVALID_RESPONSE,
+                    empty,
+                    FailureKind.PROTOCOL,
+                    "provider response is incomplete or malformed",
+                )
+            return QueryAttempt.branch_result(success, value, Receipt())
+        finally:
+            await response.aclose()
+
+
+class ListOutboundMessagesOperation:
+    """Search one page of Postmark outbound messages."""
+
+    def __init__(self, client: Client) -> None:
+        if client is None:
+            raise ValueError("Postmark client is required")
+        self.client = client
+
+    def definition(self) -> QueryDefinition:
+        """Return manifest identity, branches, and retry defaults."""
+        return LIST_OUTBOUND_MESSAGES_DEFINITION
+
+    async def invoke(self, call: Call, input: ListOutboundMessagesInput) -> QueryAttempt[MessagePage]:
+        """Validate the search window, read once, then select a branch or safe retry."""
+        operation = LIST_OUTBOUND_MESSAGES_OPERATION_ID
+        if (
+            not isinstance(input, ListOutboundMessagesInput)
+            or type(input.count) is not int
+            or type(input.offset) is not int
+        ):
+            return _branch(
+                operation, DEFECT, MessagePage(), FailureKind.VALIDATION, "search input is invalid"
+            )
+        count = input.count or 50
+        if count < 1 or count > 500 or input.offset < 0 or count + input.offset > 10_000:
+            return _branch(
+                operation,
+                DEFECT,
+                MessagePage(),
+                FailureKind.VALIDATION,
+                "count and offset must fit Postmark's 10,000-message search window",
+            )
+        path = f"/messages/outbound?count={count}&offset={input.offset}"
+        return await self.client._run_query(
+            call, operation, path, MessagePage(), LISTED, _decode_message_page
+        )
+
+
+class GetMessageDetailsOperation:
+    """Read one Postmark outbound message by ID."""
+
+    def __init__(self, client: Client) -> None:
+        if client is None:
+            raise ValueError("Postmark client is required")
+        self.client = client
+
+    def definition(self) -> QueryDefinition:
+        """Return manifest identity, branches, and retry defaults."""
+        return GET_MESSAGE_DETAILS_DEFINITION
+
+    async def invoke(self, call: Call, input: GetMessageDetailsInput) -> QueryAttempt[MessageDetails]:
+        """Validate the message ID, read once, then select a branch or safe retry."""
+        operation = GET_MESSAGE_DETAILS_OPERATION_ID
+        if (
+            not isinstance(input, GetMessageDetailsInput)
+            or not isinstance(input.message_id, str)
+            or not input.message_id
+        ):
+            return _branch(
+                operation, DEFECT, MessageDetails(), FailureKind.VALIDATION, "message ID is required"
+            )
+        path = "/messages/outbound/" + quote(input.message_id, safe="") + "/details"
+        return await self.client._run_query(
+            call, operation, path, MessageDetails(), FOUND, _decode_required_message, is_message_lookup=True
+        )
+
+
+async def _is_message_not_found(response: httpx.Response) -> bool:
+    if response.headers.get("X-PM-ApiErrorCode") == str(_MESSAGE_NOT_FOUND_ERROR_CODE):
+        return True
+    try:
+        body = await read_bounded_body(response, MAX_ERROR_BODY_BYTES)
+        document = json.loads(body)
+    except (BodyTooLargeError, ProviderTransportError, ValueError, UnicodeDecodeError):
+        return False
+    code = _field(document, "ErrorCode") if isinstance(document, dict) else None
+    return type(code) is int and code == _MESSAGE_NOT_FOUND_ERROR_CODE
+
+
+def _retry_after_seconds(response: httpx.Response) -> float:
+    return parse_retry_after(response.headers.get("Retry-After", ""), datetime.now(UTC))
+
+
+def _failure(operation: str, kind: FailureKind, message: str) -> Failure:
+    return Failure(kind, CONNECTOR_ID, operation, message)
+
+
+def _branch(
+    operation: str, branch: str, value: Output, kind: FailureKind, message: str
+) -> QueryAttempt[Output]:
+    return QueryAttempt.branch_result(branch, value, Receipt(), _failure(operation, kind, message))
+
+
+def _decode_message_page(document: dict[str, Any]) -> MessagePage:
+    messages = _field(document, "Messages")
+    if not isinstance(messages, list):
+        raise ValueError
+    total = _field(document, "TotalCount")
+    if total is None:
+        total = 0
+    if type(total) is not int:
+        raise ValueError
+    return MessagePage(total, tuple(_decode_message(message) for message in messages))
+
+
+def _decode_required_message(document: dict[str, Any]) -> MessageDetails:
+    message = _decode_message(document)
+    if not message.message_id:
+        raise ValueError
+    return message
+
+
+def _decode_message(document: Any) -> MessageDetails:
+    if not isinstance(document, dict):
+        raise ValueError
+    return MessageDetails(
+        _string(document, "MessageID"), _string(document, "Subject"), _string(document, "Status")
+    )
+
+
+def _field(document: dict[str, Any], name: str) -> Any:
+    """Match Go's case-insensitive JSON field lookup, preferring an exact key."""
+    if name in document:
+        return document[name]
+    folded = name.casefold()
+    for key, value in document.items():
+        if key.casefold() == folded:
+            return value
+    return None
+
+
+def _string(document: dict[str, Any], name: str) -> str:
+    value = _field(document, name)
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise ValueError
+    return value

dex_connectors/postmark/connection.py

@@ -0,0 +1,135 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Postmark connection and project credential binding."""
+
+from typing import Any
+
+import httpx
+from dex_connectors.sdk import Call, ConnectionRef, Query, SecretString
+from dex_connectors.sdk.projectconfig import ConnectionKey, LoadedProject
+
+from .client import (
+    CONNECTOR_ID,
+    GET_MESSAGE_DETAILS_DEFINITION,
+    LIST_OUTBOUND_MESSAGES_DEFINITION,
+    Client,
+    Config,
+    Credentials,
+)
+from .models import GetMessageDetailsInput, ListOutboundMessagesInput, MessageDetails, MessagePage
+
+
+class Connection:
+    """Nonserializable Postmark operation bindings for a named project connection."""
+
+    __slots__ = ("_list_outbound_messages", "_get_message_details", "_client", "reference")
+
+    def __init__(
+        self,
+        reference: ConnectionRef,
+        list_outbound_messages: Query[ListOutboundMessagesInput, MessagePage],
+        get_message_details: Query[GetMessageDetailsInput, MessageDetails],
+        client: Client | None = None,
+    ) -> None:
+        reference.validate()
+        if (
+            reference.provider != CONNECTOR_ID
+            or list_outbound_messages is None
+            or get_message_details is None
+        ):
+            raise ValueError("Postmark connection provider and operations are required")
+        if (
+            list_outbound_messages.definition().operation != LIST_OUTBOUND_MESSAGES_DEFINITION.operation
+            or get_message_details.definition().operation != GET_MESSAGE_DETAILS_DEFINITION.operation
+        ):
+            raise ValueError("Postmark connection operation identity differs")
+        self.reference = reference
+        self._list_outbound_messages = list_outbound_messages
+        self._get_message_details = get_message_details
+        self._client = client
+
+    def list_outbound_messages(self) -> Query[ListOutboundMessagesInput, MessagePage]:
+        """Return the outbound message search Query used by an application Step."""
+        return self._list_outbound_messages
+
+    def get_message_details(self) -> Query[GetMessageDetailsInput, MessageDetails]:
+        """Return the message details Query used by an application Step."""
+        return self._get_message_details
+
+    async def aclose(self) -> None:
+        """Close the owned provider transport after Worker shutdown."""
+        if self._client is not None:
+            await self._client.aclose()
+
+    def __repr__(self) -> str:
+        """Keep provider transport and credentials out of logs."""
+        return "postmark.Connection([REDACTED])"
+
+    def __reduce__(self) -> tuple[object, ...]:
+        """Prevent a live connection from entering durable Flow state."""
+        raise TypeError("Postmark connections cannot be serialized")
+
+
+def new_connection(client: Client, reference: ConnectionRef) -> Connection:
+    """Bind a client to an explicit logical connection reference."""
+    if client is None:
+        raise ValueError("Postmark client is required")
+    return Connection(reference, client.list_outbound_messages(), client.get_message_details(), client)
+
+
+def new_connection_with_operations(
+    list_outbound_messages: Query[ListOutboundMessagesInput, MessagePage],
+    get_message_details: Query[GetMessageDetailsInput, MessageDetails],
+    reference: ConnectionRef,
+) -> Connection:
+    """Bind mock operations to the same connection identity as the real provider."""
+    return Connection(reference, list_outbound_messages, get_message_details)
+
+
+class _ProjectCredentialSource:
+    def __init__(self, project: LoadedProject, key: ConnectionKey) -> None:
+        self.project = project
+        self.key = key
+
+    async def resolve(self, call: Call) -> Credentials:
+        material = await self.project.resolve_credential(self.key, str(call.id))
+        value = material.get("api_key")
+        if not isinstance(value, str) or not value:
+            raise ValueError("Postmark credential api_key is required")
+        return Credentials(SecretString(value))
+
+
+def new_project_connection(
+    project: LoadedProject, connection_name: str, http_client: httpx.AsyncClient | None = None
+) -> Connection:
+    """Open declared ordinary settings and resolve the current private key per call."""
+    if project is None:
+        raise ValueError("Postmark connection requires loaded project configuration")
+    reference = ConnectionRef(CONNECTOR_ID, connection_name)
+    reference.validate()
+    key = ConnectionKey(CONNECTOR_ID, connection_name)
+    matching = [
+        entry
+        for entry in project.configuration.connections
+        if entry.connector_id == CONNECTOR_ID and entry.connection_name == connection_name
+    ]
+    if len(matching) != 1:
+        raise ValueError("Postmark project connection is missing or duplicated")
+    if matching[0].provider != CONNECTOR_ID:
+        raise ValueError("Postmark project connection provider differs")
+    config = _decode_config(matching[0].configuration)
+    client = Client(config, _ProjectCredentialSource(project, key), http_client)
+    return new_connection(client, reference)
+
+
+def _decode_config(value: dict[str, Any]) -> Config:
+    if set(value) - {"baseUrl", "timeout", "maxResponseBytes"}:
+        raise ValueError("Postmark configuration has unknown fields")
+    base_url = value.get("baseUrl", "")
+    timeout = value.get("timeout", 0)
+    max_response_bytes = value.get("maxResponseBytes", 0)
+    if not isinstance(base_url, str):
+        raise ValueError("Postmark configuration baseUrl must be a string")
+    if type(timeout) is not int or type(max_response_bytes) is not int:
+        raise ValueError("Postmark configuration timeout and maxResponseBytes must be integers")
+    return Config(base_url, timeout / 1_000_000_000, max_response_bytes)

dex_connectors/postmark/dex-connector.json

@@ -0,0 +1,82 @@
+{
+  "connectorId": "postmark",
+  "releaseTag": "connectors/postmark/go/v0.2.0",
+  "package": {
+    "ecosystem": "pypi",
+    "name": "dex-connector-postmark",
+    "version": "0.1.0"
+  },
+  "factories": [
+    {
+      "name": "new_list_outbound_messages_step",
+      "kind": "query",
+      "operationId": "listOutboundMessages",
+      "fields": {
+        "stepType": "step_type",
+        "annotations": "annotations",
+        "connectionName": "connection_name",
+        "resultAttribute": "result_attribute"
+      },
+      "branches": [
+        {
+          "id": "listed",
+          "field": "listed",
+          "optional": false
+        },
+        {
+          "id": "providerRejected",
+          "field": "provider_rejected",
+          "optional": true
+        },
+        {
+          "id": "invalidResponse",
+          "field": "invalid_response",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "field": "defect",
+          "optional": true
+        }
+      ]
+    },
+    {
+      "name": "new_get_message_details_step",
+      "kind": "query",
+      "operationId": "getMessageDetails",
+      "fields": {
+        "stepType": "step_type",
+        "annotations": "annotations",
+        "connectionName": "connection_name",
+        "resultAttribute": "result_attribute"
+      },
+      "branches": [
+        {
+          "id": "found",
+          "field": "found",
+          "optional": false
+        },
+        {
+          "id": "notFound",
+          "field": "not_found",
+          "optional": true
+        },
+        {
+          "id": "providerRejected",
+          "field": "provider_rejected",
+          "optional": true
+        },
+        {
+          "id": "invalidResponse",
+          "field": "invalid_response",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "field": "defect",
+          "optional": true
+        }
+      ]
+    }
+  ]
+}

dex_connectors/postmark/models.py

@@ -0,0 +1,37 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Typed Postmark outbound message searches and details."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class ListOutboundMessagesInput:
+    """One page of outbound messages; count zero means 50, and count plus offset is at most 10,000."""
+
+    count: int = 0
+    offset: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class GetMessageDetailsInput:
+    """Postmark outbound message ID."""
+
+    message_id: str = field(default="", metadata={"dex_json_name": "messageId"})
+
+
+@dataclass(frozen=True, slots=True)
+class MessageDetails:
+    """Outbound message summary with Postmark's delivery status text."""
+
+    message_id: str = field(default="", metadata={"dex_json_name": "MessageID"})
+    subject: str = field(default="", metadata={"dex_json_name": "Subject"})
+    status: str = field(default="", metadata={"dex_json_name": "Status"})
+
+
+@dataclass(frozen=True, slots=True)
+class MessagePage:
+    """One page of outbound messages and Postmark's total match count."""
+
+    total_count: int = field(default=0, metadata={"dex_json_name": "TotalCount"})
+    messages: tuple[MessageDetails, ...] = field(default=(), metadata={"dex_json_name": "Messages"})

dex_connectors/postmark/postmarkmock/__init__.py

@@ -0,0 +1,88 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Manifest-backed Postmark scripts for consuming Flow tests."""
+
+from dex_connectors.sdk import ConnectionRef, Failure
+from dex_connectors.sdk.connectormock import Case, Query
+
+from ..client import (
+    CONNECTOR_ID,
+    FOUND,
+    GET_MESSAGE_DETAILS_DEFINITION,
+    LIST_OUTBOUND_MESSAGES_DEFINITION,
+    LISTED,
+    NOT_FOUND,
+    PROVIDER_REJECTED,
+)
+from ..connection import Connection, new_connection_with_operations
+from ..models import GetMessageDetailsInput, ListOutboundMessagesInput, MessageDetails, MessagePage
+
+_DEFAULT_MESSAGE = MessageDetails("0ac29aee-e1cd-480d-b08d-4f48548ff48d", "Welcome", "Sent")
+
+
+def list_outbound_messages_listed(value: MessagePage, failure: Failure | None = None) -> Case[MessagePage]:
+    """Script the successful listed route."""
+    return Case.branch_result(LISTED, value, failure)
+
+
+def list_outbound_messages_provider_rejected(
+    value: MessagePage, failure: Failure | None = None
+) -> Case[MessagePage]:
+    """Script a definite provider rejection of the search."""
+    return Case.branch_result(PROVIDER_REJECTED, value, failure)
+
+
+def list_outbound_messages_default() -> Case[MessagePage]:
+    """Return the manifest's listOutboundMessagesDefault answer."""
+    return list_outbound_messages_listed(MessagePage(1, (_DEFAULT_MESSAGE,)))
+
+
+def get_message_details_found(value: MessageDetails, failure: Failure | None = None) -> Case[MessageDetails]:
+    """Script the successful found route."""
+    return Case.branch_result(FOUND, value, failure)
+
+
+def get_message_details_not_found(
+    value: MessageDetails, failure: Failure | None = None
+) -> Case[MessageDetails]:
+    """Script a missing outbound message."""
+    return Case.branch_result(NOT_FOUND, value, failure)
+
+
+def get_message_details_default() -> Case[MessageDetails]:
+    """Return the manifest's getMessageDetailsDefault answer."""
+    return get_message_details_found(_DEFAULT_MESSAGE)
+
+
+class Mock:
+    """Script Postmark operations, defaulting to their manifest answers."""
+
+    def __init__(self, connection_name: str = "postmark") -> None:
+        self.list_outbound_messages_script: Query[ListOutboundMessagesInput, MessagePage] = Query(
+            LIST_OUTBOUND_MESSAGES_DEFINITION
+        )
+        self.list_outbound_messages_script.default(list_outbound_messages_default())
+        self.get_message_details_script: Query[GetMessageDetailsInput, MessageDetails] = Query(
+            GET_MESSAGE_DETAILS_DEFINITION
+        )
+        self.get_message_details_script.default(get_message_details_default())
+        self._connection = new_connection_with_operations(
+            self.list_outbound_messages_script,
+            self.get_message_details_script,
+            ConnectionRef(CONNECTOR_ID, connection_name),
+        )
+
+    def connection(self) -> Connection:
+        """Return this mock's named connection for Step registration."""
+        return self._connection
+
+
+__all__ = [
+    "Mock",
+    "list_outbound_messages_listed",
+    "list_outbound_messages_provider_rejected",
+    "list_outbound_messages_default",
+    "get_message_details_found",
+    "get_message_details_not_found",
+    "get_message_details_default",
+]

dex_connectors/postmark/steps.py

@@ -0,0 +1,111 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Operation-specific Dex Step factories for Postmark outbound message operations."""
+
+from collections.abc import Callable, Mapping
+from typing import TypeVar
+
+import dex
+from dex_connectors.sdk import QueryResult, QueryStep, QueryStepConfig, StepAnnotations
+
+from .connection import Connection
+from .models import GetMessageDetailsInput, ListOutboundMessagesInput, MessageDetails, MessagePage
+
+StepInput = TypeVar("StepInput")
+BranchTarget = TypeVar("BranchTarget")
+
+
+def new_list_outbound_messages_step(
+    *,
+    step_type: str,
+    step_input_type: type[StepInput],
+    annotations: StepAnnotations | Mapping[str, str],
+    connection: Connection,
+    connection_name: str,
+    map_to_operation_input: Callable[[StepInput], ListOutboundMessagesInput],
+    listed: dex.StepTarget[QueryResult[MessagePage]],
+    not_listed: dex.StepTarget[QueryResult[MessagePage]] | None = None,
+    provider_rejected: dex.StepTarget[QueryResult[MessagePage]] | None = None,
+    invalid_response: dex.StepTarget[QueryResult[MessagePage]] | None = None,
+    defect: dex.StepTarget[QueryResult[MessagePage]] | None = None,
+    result_attribute: dex.Attribute[QueryResult[MessagePage]] | None = None,
+    step_options_override: dex.StepOptions | None = None,
+) -> QueryStep[StepInput, ListOutboundMessagesInput, MessagePage]:
+    """Create the typed outbound message search Step; unwired optional outcomes fail the Flow."""
+    _require_connection(connection, connection_name)
+    return QueryStep(
+        QueryStepConfig(
+            step_type=step_type,
+            step_input_type=step_input_type,
+            annotations=_step_annotations(annotations),
+            operation=connection.list_outbound_messages(),
+            connection=connection.reference,
+            map_to_operation_input=map_to_operation_input,
+            branches=_branches(
+                ("listed", listed),
+                ("providerRejected", provider_rejected),
+                ("invalidResponse", invalid_response),
+                ("defect", defect),
+            ),
+            result_attribute=result_attribute,
+            step_options_override=step_options_override,
+        )
+    )
+
+
+def new_get_message_details_step(
+    *,
+    step_type: str,
+    step_input_type: type[StepInput],
+    annotations: StepAnnotations | Mapping[str, str],
+    connection: Connection,
+    connection_name: str,
+    map_to_operation_input: Callable[[StepInput], GetMessageDetailsInput],
+    found: dex.StepTarget[QueryResult[MessageDetails]],
+    not_found: dex.StepTarget[QueryResult[MessageDetails]] | None = None,
+    provider_rejected: dex.StepTarget[QueryResult[MessageDetails]] | None = None,
+    invalid_response: dex.StepTarget[QueryResult[MessageDetails]] | None = None,
+    defect: dex.StepTarget[QueryResult[MessageDetails]] | None = None,
+    result_attribute: dex.Attribute[QueryResult[MessageDetails]] | None = None,
+    step_options_override: dex.StepOptions | None = None,
+) -> QueryStep[StepInput, GetMessageDetailsInput, MessageDetails]:
+    """Create the typed message details Step; unwired optional outcomes fail the Flow."""
+    _require_connection(connection, connection_name)
+    return QueryStep(
+        QueryStepConfig(
+            step_type=step_type,
+            step_input_type=step_input_type,
+            annotations=_step_annotations(annotations),
+            operation=connection.get_message_details(),
+            connection=connection.reference,
+            map_to_operation_input=map_to_operation_input,
+            branches=_branches(
+                ("found", found),
+                ("notFound", not_found),
+                ("providerRejected", provider_rejected),
+                ("invalidResponse", invalid_response),
+                ("defect", defect),
+            ),
+            result_attribute=result_attribute,
+            step_options_override=step_options_override,
+        )
+    )
+
+
+def _require_connection(connection: Connection, connection_name: str) -> None:
+    if connection is None or connection.reference.name != connection_name:
+        raise ValueError("Postmark Step connection name must match its connection reference")
+
+
+def _step_annotations(annotations: StepAnnotations | Mapping[str, str]) -> StepAnnotations:
+    if isinstance(annotations, StepAnnotations):
+        return annotations
+    if not isinstance(annotations, Mapping) or set(annotations) != {"groupId", "groupLabel", "explanation"}:
+        raise ValueError("Postmark Step annotations require groupId, groupLabel, and explanation")
+    if any(not isinstance(value, str) for value in annotations.values()):
+        raise ValueError("Postmark Step annotations must be strings")
+    return StepAnnotations(annotations["groupId"], annotations["groupLabel"], annotations["explanation"])
+
+
+def _branches(*targets: tuple[str, BranchTarget | None]) -> dict[str, BranchTarget]:
+    return {branch: target for branch, target in targets if target is not None}