Add bulk sending api endpoints, attachment example

gregsvo · gregsvo · commit 8fedeebdf8f6 · 2026-02-27T15:27:49.000-05:00
diff --git a/examples/send_attachment.py b/examples/send_attachment.py
@@ -0,0 +1,63 @@
+"""
+Example for sending emails with attachments.
+
+Attachment content must be Base64-encoded before sending.
+The standard library's base64 module handles this for both
+in-memory content and files read from disk.
+
+"""
+
+import asyncio
+import base64
+import os
+
+import postmark
+from postmark.models.messages import Attachment, Email
+from dotenv import load_dotenv
+
+load_dotenv()
+client = postmark.ServerClient(os.environ["POSTMARK_SERVER_TOKEN"])
+SENDER = os.environ["POSTMARK_SENDER_EMAIL"]
+
+
+async def main():
+    # Building an attachment from a string (in-memory content)
+    report_txt = Attachment(
+        name="report.txt",
+        content=base64.b64encode(b"Q3 sales are up 12%.").decode("utf-8"),
+        content_type="text/plain",
+    )
+
+    # Building an attachments from a file, on disk
+    with open("/path/to/book.pdf", "rb") as f:
+        book_pdf = Attachment(
+            name="book.pdf",
+            content=base64.b64encode(f.read()).decode("utf-8"),
+            content_type="application/pdf",
+        )
+
+    # Building an attachment from an inline image
+    with open("/path/to/logo.png", "rb") as f:
+        inline_logo = Attachment(
+            name="logo.png",
+            content=base64.b64encode(f.read()).decode("utf-8"),
+            content_type="image/png",
+            content_id="cid:logo",  # reference this in html_body as <img src="cid:logo">
+        )
+
+    # --- Send ---
+    response = await client.outbound.send(
+        Email(
+            sender=SENDER,
+            to="receiver@example.com",
+            subject="Your report and resources",
+            text_body="Please find your report and resources attached.",
+            html_body='<p>Please find your report attached.</p><img src="cid:logo">',
+            attachments=[report_txt, book_pdf, inline_logo],
+        )
+    )
+
+    print(f"Sent: {response.message_id}")
+
+
+asyncio.run(main())
diff --git a/examples/send_batch.py b/examples/send_batch.py
@@ -0,0 +1,36 @@
+import asyncio
+import os
+
+import postmark
+from postmark import Email
+from dotenv import load_dotenv
+
+load_dotenv()
+client = postmark.ServerClient(os.environ["POSTMARK_SERVER_TOKEN"])
+SENDER = os.environ["POSTMARK_SENDER_EMAIL"]
+
+
+async def main():
+    # --- Send batch ---
+    responses = await client.outbound.send_batch(
+        [
+            {
+                "sender": SENDER,
+                "to": "receiver1@example.com",
+                "subject": "Batch 1",
+                "text_body": "Hello Receiver 1",
+            },
+            {
+                "sender": SENDER,
+                "to": "receiver2@example.com",
+                "subject": "Batch 2",
+                "text_body": "Hello Receiver 2",
+            },
+        ]
+    )
+    print(f"Batch: {len(responses)} sent")
+    for i, resp in enumerate(responses, start=1):
+        print(f"  {i}: {resp.message_id}")
+
+
+asyncio.run(main())
diff --git a/examples/send_bulk.py b/examples/send_bulk.py
@@ -0,0 +1,75 @@
+import asyncio
+import os
+
+import postmark
+from postmark.models.messages import BulkEmail, BulkRecipient
+from dotenv import load_dotenv
+
+load_dotenv()
+client = postmark.ServerClient(os.environ["POSTMARK_SERVER_TOKEN"])
+SENDER = os.environ["POSTMARK_SENDER_EMAIL"]
+
+
+async def main():
+    # --- It's recommended sending using BulkRecipient class models, for improved type safety. ---
+    response = await client.outbound.send_bulk(
+        BulkEmail(
+            sender=SENDER,
+            subject="Hello {{FirstName}}, your order is ready",
+            html_body="<p>Hi {{FirstName}}, your order <strong>{{OrderId}}</strong> is ready.</p>",
+            text_body="Hi {{FirstName}}, your order {{OrderId}} is ready.",
+            message_stream="broadcast",
+            messages=[
+                BulkRecipient(
+                    to="bob@example.com",
+                    template_model={"FirstName": "Bob", "OrderId": "ORD-001"},
+                ),
+                BulkRecipient(
+                    to="frieda@example.com",
+                    template_model={"FirstName": "Frieda", "OrderId": "ORD-002"},
+                ),
+                BulkRecipient(
+                    to="elijah@example.com",
+                    template_model={"FirstName": "Elijah", "OrderId": "ORD-003"},
+                ),
+            ],
+        )
+    )
+    print(f"Bulk request accepted — ID: {response.id}  Status: {response.status}")
+
+    # --- ...or send bulk via dict ---
+    response = await client.outbound.send_bulk(
+        {
+            "sender": SENDER,
+            "subject": "Hello {{FirstName}}, your order is ready",
+            "html_body": "<p>Hi {{FirstName}}, your order <strong>{{OrderId}}</strong> is ready.</p>",
+            "text_body": "Hi {{FirstName}}, your order {{OrderId}} is ready.",
+            "message_stream": "broadcast",
+            "track_opens": True,
+            "messages": [
+                {
+                    "to": "bob@example.com",
+                    "template_model": {"FirstName": "Bob", "OrderId": "ORD-001"},
+                },
+                {
+                    "to": "frieda@example.com",
+                    "template_model": {"FirstName": "Frieda", "OrderId": "ORD-002"},
+                },
+                {
+                    "to": "elijah@example.com",
+                    "template_model": {"FirstName": "Elijah", "OrderId": "ORD-003"},
+                    "cc": "manager@example.com",
+                },
+            ],
+        }
+    )
+    print(f"Bulk request accepted — ID: {response.id}  Status: {response.status}")
+
+    # --- Poll for completion ---
+    status = await client.outbound.get_bulk_status(response.id)
+    print(
+        f"Status: {status.status}  ({status.percentage_completed:.0f}% of {status.total_messages} messages sent)"
+    )
+
+
+asyncio.run(main())
diff --git a/examples/send_messages.py b/examples/send_messages.py
@@ -42,26 +42,5 @@ async def main():
     )
     print(f"Sent (model): {response.message_id}")
 
-    # --- Send batch ---
-    responses = await client.outbound.send_batch(
-        [
-            {
-                "sender": SENDER,
-                "to": "receiver1@example.com",
-                "subject": "Batch 1",
-                "text_body": "Hello Receiver 1",
-            },
-            {
-                "sender": SENDER,
-                "to": "receiver2@example.com",
-                "subject": "Batch 2",
-                "text_body": "Hello Receiver 2",
-            },
-        ]
-    )
-    print(f"Batch: {len(responses)} sent")
-    for i, resp in enumerate(responses, start=1):
-        print(f"  {i}: {resp.message_id}")
-
 
 asyncio.run(main())
diff --git a/postmark/models/messages/__init__.py b/postmark/models/messages/__init__.py
@@ -1,30 +1,40 @@
 from .enums import MessageStatus, TrackLinksOption, MessageEventType, Platform
 from .schemas import (
+    # Single / batch
     Email,
     SendResponse,
     Outbound,
     OutboundMessageDetails,
     Attachment,
     Header,
     EmailAddress,
+    # Bulk
+    BulkEmail,
+    BulkRecipient,
+    BulkSendResponse,
+    BulkSendStatus,
 )
-from .manager import OutboundManager  # InboundManager
+from .manager import OutboundManager
 
 __all__ = [
-    # Schemas
+    # Schemas — single / batch
     "Email",
     "SendResponse",
     "Outbound",
     "OutboundMessageDetails",
     "Attachment",
     "Header",
     "EmailAddress",
+    # Schemas — bulk
+    "BulkEmail",
+    "BulkRecipient",
+    "BulkSendResponse",
+    "BulkSendStatus",
     # Enums
     "MessageStatus",
     "TrackLinksOption",
     "MessageEventType",
     "Platform",
     # Managers
     "OutboundManager",
-    # "InboundManager,",
 ]
diff --git a/postmark/models/messages/manager.py b/postmark/models/messages/manager.py
@@ -7,16 +7,23 @@
 from postmark.exceptions import InvalidEmailPayloadException
 from postmark.utils.types import HTTPClient
 
-from .schemas import Email, Outbound, OutboundMessageDetails, SendResponse
+from .schemas import (
+    BulkEmail,
+    BulkSendResponse,
+    BulkSendStatus,
+    Email,
+    Outbound,
+    OutboundMessageDetails,
+    SendResponse,
+)
 
 logger = logging.getLogger(__name__)
 
 
 def _parse_email(message: Union[Email, Dict[str, Any]]) -> Email:
     """
     Coerce a dict to an Email model using snake_case field names,
-    raising InvalidEmailPayloadException on validation failure.
-    Passes through an Email instance unchanged.
+    or raise InvalidEmailPayloadException
     """
     if isinstance(message, Email):
         return message
@@ -26,10 +33,27 @@ def _parse_email(message: Union[Email, Dict[str, Any]]) -> Email:
         raise InvalidEmailPayloadException(e.errors()) from e
 
 
+def _parse_bulk_email(message: Union[BulkEmail, Dict[str, Any]]) -> BulkEmail:
+    """
+    Coerce a dict to a BulkEmail model, raising InvalidEmailPayloadException
+    on validation failure. Passes through a BulkEmail instance unchanged.
+    """
+    if isinstance(message, BulkEmail):
+        return message
+    try:
+        return BulkEmail.model_validate(message)
+    except ValidationError as e:
+        raise InvalidEmailPayloadException(e.errors()) from e
+
+
 class OutboundManager:
     def __init__(self, client: HTTPClient):
         self.client = client
 
+    # -------------------------------------------------------------------------
+    # Single send
+    # -------------------------------------------------------------------------
+
     async def send(self, message: Union[Email, Dict[str, Any]]) -> SendResponse:
         """Send a single email."""
         email_payload = _parse_email(message)
@@ -41,14 +65,21 @@ async def send(self, message: Union[Email, Dict[str, Any]]) -> SendResponse:
         )
         return SendResponse(**response.json())
 
+    # -------------------------------------------------------------------------
+    # Batch send — different messages, one request (max 500)
+    # -------------------------------------------------------------------------
+
     async def send_batch(
         self, messages: List[Union[Email, Dict[str, Any]]]
     ) -> List[SendResponse]:
-        """Send different emails in a single batch (max 500)."""
+        """
+        Send up to 500 different emails in a single request.
+        Use this when each recipient needs a **completely different** message.
+        For sending the **same message** to many recipients, use send_bulk().
+        """
         if len(messages) > 500:
             raise ValueError("Batch size cannot exceed 500 messages")
 
-        # Validate all messages up front so we fail before making any HTTP call
         payload = []
         for i, msg in enumerate(messages):
             try:
@@ -68,6 +99,41 @@ async def send_batch(
         response = await self.client.post("/email/batch", json=payload)
         return [SendResponse(**item) for item in response.json()]
 
+    # -------------------------------------------------------------------------
+    # Bulk send — same message, many recipients, one request
+    # -------------------------------------------------------------------------
+
+    async def send_bulk(
+        self, message: Union[BulkEmail, Dict[str, Any]]
+    ) -> BulkSendResponse:
+        """
+        Send the **same message** to multiple recipients in a single request.
+        """
+        bulk_payload = _parse_bulk_email(message)
+
+        if not bulk_payload.messages:
+            raise ValueError(
+                "Bulk email must include at least one recipient in messages"
+            )
+
+        logger.debug(f"Sending bulk email to {len(bulk_payload.messages)} recipients")
+        response = await self.client.post(
+            "/email/bulk",
+            json=bulk_payload.model_dump(by_alias=True, exclude_none=True),
+        )
+        return BulkSendResponse(**response.json())
+
+    async def get_bulk_status(self, bulk_id: str) -> BulkSendStatus:
+        """
+        Poll the status of a bulk send request.
+        """
+        response = await self.client.get(f"/email/bulk/{bulk_id}")
+        return BulkSendStatus(**response.json())
+
+    # -------------------------------------------------------------------------
+    # List / stream / get
+    # -------------------------------------------------------------------------
+
     async def list(
         self,
         count: int = 100,
diff --git a/postmark/models/messages/schemas.py b/postmark/models/messages/schemas.py
diff --git a/tests/test_bulk_messages.py b/tests/test_bulk_messages.py
