Remove circular imports, flatten imports, simplify testing

Author: gregsvo

examples/get_messages.py

@@ -16,7 +16,7 @@ async def list_example():
     server = postmark.ServerClient(server_token=server_token)
 
     try:
-        messages, total = await server.messages.Outbound.list(count=10)
+        messages, total = await server.outbound.list(count=10)
 
         print(f"Total matches on server: {total}")
         print(f"Retrieved in this page: {len(messages)}")
@@ -48,7 +48,7 @@ async def stream_example():
         count = 0
 
         # Get 20 messages
-        async for msg in server.messages.Outbound.stream(max_messages=20):
+        async for msg in server.outbound.stream(max_messages=20):
             count += 1
 
             # Print details for the first 3...
@@ -76,7 +76,7 @@ async def get_details_example(message_id: str):
 
     try:
         # Get message details
-        message = await server.messages.Outbound.get(message_id)
+        message = await server.outbound.get(message_id)
 
         print("\n--- Message Details ---")
         print(f"Message ID:     {message.message_id}")

examples/send_messages.py

@@ -19,7 +19,7 @@ async def send_single_email_using_json():
     print("--- Sending Single Email (JSON) ---")
     try:
         # You can pass a dictionary matching the API fields
-        response = await server.messages.Outbound.send(
+        response = await server.outbound.send(
             {
                 "From": send_email,
                 "To": "receiver@example.com",
@@ -56,7 +56,7 @@ async def send_single_email_using_model():
             metadata={"user_id": "12345"},
         )
 
-        response = await server.messages.Outbound.send(email)
+        response = await server.outbound.send(email)
 
         print(f"Email sent! Message ID: {response.message_id}")
 
@@ -89,7 +89,7 @@ async def send_batch_emails():
             },
         ]
 
-        responses = await server.messages.Outbound.send_batch(messages)
+        responses = await server.outbound.send_batch(messages)
 
         print(f"Batch processed. Sent {len(responses)} emails.")
         for i, resp in enumerate(responses):

postmark/clients/server_client.py

@@ -1,7 +1,8 @@
 import json
 import logging
 import os
-from typing import Optional, Dict, Any, TYPE_CHECKING
+from typing import Optional, Dict, Any
+from postmark.models.messages import OutboundManager
 
 import httpx
 
@@ -13,8 +14,6 @@
     get_exception_class,
 )
 
-if TYPE_CHECKING:
-    from postmark.models.messages import MessageService
 
 logger = logging.getLogger(__name__)
 
@@ -41,11 +40,8 @@ def __init__(self, server_token: str):
         if not self.verify_ssl:
             logger.warning("SSL verification is disabled. Do not use in production!")
 
-        # Initializing the import here, inside __init__ to avoid potential circular import issues at the module level
-        # if messages.py ends up importing this file (but like...don't).
-        from postmark.models.messages import MessageService
-
-        self.messages = MessageService(self)
+        self.outbound = OutboundManager(self)
+        # self.inbound = InboundManager(self)
 
     async def request(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
         """
@@ -108,3 +104,8 @@ async def put(
         self, endpoint: str, json: Optional[Dict[str, Any]] = None
     ) -> httpx.Response:
         return await self.request("PUT", endpoint, json=json)
+
+    async def delete(
+        self, endpoint: str, params: Optional[Dict[str, Any]] = None
+    ) -> httpx.Response:
+        return await self.request("DELETE", endpoint, params=params)

postmark/exceptions.py

@@ -1,6 +1,6 @@
 """Postmark API exceptions."""
 
-from typing import Any, Dict, Optional
+from typing import Any, Optional
 
 
 class PostmarkException(Exception):
@@ -15,11 +15,35 @@ def __init__(
         super().__init__(message)
         self.error_code = error_code
         self.http_status = http_status
-        self.message = message
+
+    @property
+    def message(self) -> str:
+        """The error message. Alias for self.args[0]."""
+        return self.args[0]
+
+
+class InvalidEmailPayloadException(PostmarkException):
+    """
+    Raised when an email dict or model fails Pydantic validation
+    before it is ever sent to the API.
+
+    Distinct from ValidationException, which maps to HTTP 422 responses
+    from the Postmark API after a request was made.
+    """
+
+    def __init__(self, errors: list[dict[str, Any]]):
+        self.errors = errors
+        summary = " | ".join(
+            f"{' -> '.join(str(loc) for loc in e['loc'])}: {e['msg']}" for e in errors
+        )
+        super().__init__(f"Invalid email payload: {summary}")
 
 
 class PostmarkAPIException(PostmarkException):
-    """API errors with error codes from Postmark."""
+    """
+    Raised for errors returned by the Postmark API.
+    Always carries both a Postmark error_code and an http_status.
+    """
 
     def __init__(self, message: str, error_code: int, http_status: int):
         super().__init__(message, error_code, http_status)
@@ -28,7 +52,6 @@ def __str__(self):
         return f"[{self.error_code}] {self.message} (HTTP {self.http_status})"
 
 
-# Specific exception types for common errors
 class InvalidAPIKeyException(PostmarkAPIException):
     """401 - Invalid or missing API key."""
 
@@ -42,7 +65,7 @@ class InactiveRecipientException(PostmarkAPIException):
 
 
 class ValidationException(PostmarkAPIException):
-    """422 - Invalid request parameters."""
+    """422 - Invalid request parameters (rejected by Postmark API)."""
 
     pass
 
@@ -54,46 +77,47 @@ class RateLimitException(PostmarkAPIException):
 
 
 class ServerException(PostmarkAPIException):
-    """500/503 - Server errors."""
+    """500 / 503 - Server-side error."""
 
     pass
 
 
 class TimeoutException(PostmarkException):
-    """Request timeout."""
+    """Raised when a request to the Postmark API times out."""
 
     pass
 
 
-# Error code mapping
-ERROR_CODE_MAPPING = {
+# Postmark API error codes (from response body), not HTTP status codes.
+# See: https://postmarkapp.com/developer/api/overview#error-codes
+_ERROR_CODE_MAP: dict[int, type[PostmarkAPIException]] = {
     10: InvalidAPIKeyException,
-    406: InactiveRecipientException,
     300: ValidationException,
     405: ValidationException,  # Not allowed to send
+    406: InactiveRecipientException,
     701: ValidationException,  # Illegal attachment type
-    429: RateLimitException,
-    500: ServerException,
-    503: ServerException,
 }
 
 
 def get_exception_class(
     error_code: int, http_status: int
 ) -> type[PostmarkAPIException]:
-    """Get the appropriate exception class for an error code."""
-    # Check specific error codes first
-    if error_code in ERROR_CODE_MAPPING:
-        return ERROR_CODE_MAPPING[error_code]
+    """
+    Resolve the most specific exception class for a failed API response.
+
+    Checks Postmark error codes first (more specific), then falls back
+    to HTTP status codes, and finally to the generic PostmarkAPIException.
+    """
+    if error_code in _ERROR_CODE_MAP:
+        return _ERROR_CODE_MAP[error_code]
 
-    # Fall back to HTTP status
     if http_status == 401:
         return InvalidAPIKeyException
-    elif http_status == 422:
+    if http_status == 422:
         return ValidationException
-    elif http_status == 429:
+    if http_status == 429:
         return RateLimitException
-    elif http_status in (500, 503):
+    if http_status in (500, 503):
         return ServerException
 
     return PostmarkAPIException

postmark/models/__init__.py

@@ -8,16 +8,23 @@
     Header,
     EmailAddress,
 )
-from .manager import MessageService, OutboundManager
+from .manager import OutboundManager  # InboundManager
 
 __all__ = [
+    # Schemas
     "Email",
     "SendResponse",
     "Outbound",
     "OutboundMessageDetails",
-    "MessageStatus",
     "Attachment",
     "Header",
-    "MessageService",
+    "EmailAddress",
+    # Enums
+    "MessageStatus",
+    "TrackLinksOption",
+    "MessageEventType",
+    "Platform",
+    # Managers
     "OutboundManager",
+    # "InboundManager,",
 ]