messagebird-sdk 0.2.0__tar.gz → 0.2.2__tar.gz

{messagebird_sdk-0.2.0 → messagebird_sdk-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: messagebird-sdk
-Version: 0.2.0
+Version: 0.2.2
 Summary: The official Python SDK for the Bird email platform.
 Project-URL: Homepage, https://bird.com
 Project-URL: Documentation, https://bird.com/docs/sdks/python
@@ -25,12 +25,16 @@ Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.0
 Provides-Extra: dev
+Requires-Dist: django>=4.2; extra == 'dev'
+Requires-Dist: fastapi>=0.111; extra == 'dev'
+Requires-Dist: flask>=3.0; extra == 'dev'
 Requires-Dist: pyright>=1.1; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: pyyaml>=6; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: starlette>=0.37; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Bird Python SDK

{messagebird_sdk-0.2.0 → messagebird_sdk-0.2.2}/pyproject.toml

@@ -45,6 +45,13 @@ dev = [
     "ruff>=0.6",
     "pyright>=1.1",
     "pyyaml>=6",
+    # Web frameworks used only by the homepage integration examples under
+    # examples/python/ — dev-only so they type-check (pyright) but never ship
+    # in the wheel (runtime deps stay httpx + pydantic).
+    "django>=4.2",
+    "flask>=3.0",
+    "fastapi>=0.111",
+    "starlette>=0.37",
 ]
 
 [tool.hatch.version]

{messagebird_sdk-0.2.0 → messagebird_sdk-0.2.2}/src/bird/__init__.py

@@ -32,6 +32,7 @@ from bird._exceptions import (
     APITimeoutError,
     BirdError,
     ErrorDetail,
+    ErrorNextAction,
     ErrorType,
     RateLimitError,
     ValidationError,
@@ -66,6 +67,7 @@ __all__ = [
     "APITimeoutError",
     "WebhookVerificationError",
     "ErrorDetail",
+    "ErrorNextAction",
     "ErrorType",
     "__version__",
 ]

{messagebird_sdk-0.2.0 → messagebird_sdk-0.2.2}/src/bird/_base_client.py

@@ -27,9 +27,23 @@ from bird._version import __version__
 
 USER_AGENT = f"bird-sdk-python/{__version__} ({platform.python_implementation().lower()}/{platform.python_version()})"
 
+# Bird-* client-identity headers (ADR-0074): the API attributes the SDK
+# surface from these, not the User-Agent. Telemetry labels only; computed once.
+# Keys use the canonical wire casing (matching the Go/TS SDKs).
+_CLIENT_HEADERS = {
+    "Bird-Surface": "sdk-python",
+    "Bird-Version": __version__,
+    "Bird-Lang": platform.python_implementation().lower(),
+    "Bird-Os": platform.system().lower(),
+    "Bird-Arch": platform.machine().lower(),
+}
+
 _MUTATING_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
-# SDK-owned headers a caller's extra_headers must never override.
-_RESERVED_HEADERS = {"authorization", "user-agent", "x-bird-api-version", "idempotency-key"}
+# SDK-owned headers a caller's extra_headers must never override. Derived from
+# _CLIENT_HEADERS so the two can't drift; matched case-insensitively.
+_RESERVED_HEADERS = {"authorization", "user-agent", "x-bird-api-version", "idempotency-key"} | {
+    key.lower() for key in _CLIENT_HEADERS
+}
 
 # Bound to the concrete client so `with`/`async with` preserve the subclass type
 # (e.g. `with Bird(...) as c` keeps `c` typed as Bird, not SyncAPIClient).
@@ -83,6 +97,7 @@ class BaseClient:
                 headers[key] = value
         headers["Authorization"] = f"Bearer {self.api_key}"
         headers["User-Agent"] = USER_AGENT
+        headers.update(_CLIENT_HEADERS)
         if self.api_version:
             headers["X-Bird-API-Version"] = self.api_version
         if idempotency_key:

{messagebird_sdk-0.2.0 → messagebird_sdk-0.2.2}/src/bird/_client.py

@@ -95,12 +95,10 @@ class Bird(SyncAPIClient):
     (`with Bird(...) as client`) to close the underlying HTTP client.
 
     ```python
-    # bird:snippet:start client.verbs
     from bird import EmailMessage
 
     message = client.get("/v1/email/messages/em_01krd...", cast_to=EmailMessage)
     client.post("/v1/some/new/endpoint", body={"key": "value"})
-    # bird:snippet:end client.verbs
     ```
 
     A single `Bird` instance is safe to share across threads — the `httpx` client

{messagebird_sdk-0.2.0 → messagebird_sdk-0.2.2}/src/bird/_event_types.py

@@ -18,6 +18,7 @@ class WebhookEventType:
     DOMAIN_VERIFIED: Final = "domain.verified"
     EMAIL_ACCEPTED: Final = "email.accepted"
     EMAIL_BOUNCED: Final = "email.bounced"
+    EMAIL_CANCELED: Final = "email.canceled"
     EMAIL_CLICKED: Final = "email.clicked"
     EMAIL_COMPLAINED: Final = "email.complained"
     EMAIL_DEFERRED: Final = "email.deferred"
@@ -28,6 +29,7 @@ class WebhookEventType:
     EMAIL_PROCESSED: Final = "email.processed"
     EMAIL_RECEIVED: Final = "email.received"
     EMAIL_REJECTED: Final = "email.rejected"
+    EMAIL_SCHEDULED: Final = "email.scheduled"
     EMAIL_SUPPRESSION_CREATED: Final = "email_suppression.created"
     EMAIL_UNSUBSCRIBED: Final = "email.unsubscribed"
     SMS_ACCEPTED: Final = "sms.accepted"

{messagebird_sdk-0.2.0 → messagebird_sdk-0.2.2}/src/bird/_exceptions.py

@@ -48,6 +48,16 @@ class ErrorDetail:
     message: str
 
 
+@dataclass(frozen=True)
+class ErrorNextAction:
+    """One recovery operation the server suggests (ADR-0073): call it to resolve
+    the error, then retry the original request."""
+
+    operation: str
+    description: str | None = None
+    scope: str | None = None
+
+
 class BirdError(Exception):
     """Base class for every error raised by the SDK."""
 
@@ -101,6 +111,8 @@ class APIStatusError(APIError):
         request_id: str | None = None,
         param: str | None = None,
         vendor_code: str | None = None,
+        remediation: str | None = None,
+        next: list[ErrorNextAction] | None = None,
     ) -> None:
         super().__init__(message)
         self.status_code = status_code
@@ -111,6 +123,8 @@ class APIStatusError(APIError):
         self.request_id = request_id
         self.param = param
         self.vendor_code = vendor_code
+        self.remediation = remediation
+        self.next = next or []
 
     def __str__(self) -> str:
         return f"{self.message} (status {self.status_code}, type {self.type}, request_id {self.request_id})"
@@ -196,6 +210,16 @@ def from_response(status_code: int, body: bytes | str, headers: Mapping[str, str
         "request_id": request_id,
         "param": data.get("param"),
         "vendor_code": data.get("vendor_code"),
+        "remediation": data.get("remediation"),
+        "next": [
+            ErrorNextAction(
+                operation=n.get("operation", ""),
+                description=n.get("description"),
+                scope=n.get("scope"),
+            )
+            for n in (data.get("next") or [])  # `or []` handles both an absent key and an explicit null
+            if isinstance(n, dict)
+        ],
     }
 
     if type_ == ErrorType.rate_limit:

{messagebird_sdk-0.2.0 → messagebird_sdk-0.2.2}/src/bird/_generated.py

@@ -25,6 +25,33 @@ class ErrorDetail(BaseModel):
     ]
 
 
+class ErrorNextAction(BaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    operation: Annotated[
+        str,
+        Field(
+            description='The operationId of a follow-up operation that resolves this error. Call it, then retry the original request.',
+            min_length=1,
+        ),
+    ]
+    description: Annotated[
+        str | None,
+        Field(
+            description='Short human-readable label for the recovery step.',
+            min_length=1,
+        ),
+    ] = None
+    scope: Annotated[
+        str | None,
+        Field(
+            description='The permission scope the recovery operation requires, when it is scoped. Omitted for operations that need no scope.',
+            min_length=1,
+        ),
+    ] = None
+
+
 class Type(str, Enum):
     auth_error = 'auth_error'
     bad_request_error = 'bad_request_error'
@@ -107,6 +134,19 @@ class ErrorBody(BaseModel):
             description='Per-field validation errors. Present only on validation_error responses.'
         ),
     ] = None
+    remediation: Annotated[
+        str | None,
+        Field(
+            description='A human-readable next step to resolve this error. Present when a recovery is known.',
+            min_length=1,
+        ),
+    ] = None
+    next: Annotated[
+        list[ErrorNextAction] | None,
+        Field(
+            description='Operations that resolve this error, in the order to try them. Present for errors with a well-defined recovery, such as unmet preconditions and conflicts.'
+        ),
+    ] = None
 
 
 class Error(BaseModel):
@@ -250,6 +290,7 @@ class Category(str, Enum):
 
 
 class Status(str, Enum):
+    scheduled = 'scheduled'
     accepted = 'accepted'
     processed = 'processed'
     deferred = 'deferred'
@@ -258,6 +299,7 @@ class Status(str, Enum):
     bounced = 'bounced'
     complained = 'complained'
     rejected = 'rejected'
+    canceled = 'canceled'
 
 
 class EmailMessage(BaseModel):
@@ -309,7 +351,7 @@ class EmailMessage(BaseModel):
     status: Annotated[
         Status,
         Field(
-            description="Aggregate delivery status derived from recipient states. `accepted` means Bird has the send and is preparing to deliver. `processed` means Bird has processed the message and queued it for delivery to the recipient's mail server.\n"
+            description="Aggregate delivery status derived from recipient states. `scheduled` means the message is queued to send at a future time and has not been dispatched yet. `accepted` means Bird has the send and is preparing to deliver. `processed` means Bird has processed the message and queued it for delivery to the recipient's mail server. `canceled` means a scheduled message was canceled before it was sent.\n"
         ),
     ]
     accepted_count: Annotated[
@@ -421,6 +463,12 @@ class EmailMessage(BaseModel):
             description='When all recipients reached a terminal delivered state, or null if not yet fully delivered.'
         ),
     ] = None
+    scheduled_at: Annotated[
+        str | None,
+        Field(
+            description='When this message is scheduled to send, for a send created with a future send time. Null for an immediate send. Stays set after the scheduled send fires.'
+        ),
+    ] = None
 
 
 class EmailMessageList(FieldListEnvelope):
@@ -959,6 +1007,72 @@ class EventEmailBounced(BaseModel):
     data: EventEmailBouncedData
 
 
+class EventEmailMessageBase(BaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    email_id: Annotated[
+        str,
+        Field(
+            description='ID of the email send.',
+            examples=['em_01krdgeqcxet5s7t44vh8rt9mg'],
+            min_length=1,
+            pattern='^em_[0-9a-hjkmnp-tv-z]{26}$',
+        ),
+    ]
+    workspace_id: Annotated[
+        str,
+        Field(
+            description='ID of the workspace.',
+            examples=['ws_01krdgeqcxet5s7t44vh8rt9mg'],
+            min_length=1,
+            pattern='^ws_[0-9a-hjkmnp-tv-z]{26}$',
+        ),
+    ]
+    tags: Annotated[
+        list[EmailTag] | None,
+        Field(
+            description='Tags provided on the send request, echoed on the event so you can route and correlate without an extra lookup. Null when the send carried no tags.\n'
+        ),
+    ]
+    metadata: Annotated[
+        dict[str, Any] | None,
+        Field(
+            description='The metadata object provided on the send request, echoed on the event so you can correlate events with your own records. Null when the send carried no metadata.\n',
+            examples=[{'order_id': 'ord_123'}],
+        ),
+    ]
+
+
+class EventEmailCanceledData(EventEmailMessageBase):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+
+
+class Type5(str, Enum):
+    email_canceled = 'email.canceled'
+
+
+class EventEmailCanceled(BaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    type: Annotated[
+        Literal['email.canceled'],
+        Field(description='Event type.', examples=['email.canceled']),
+    ]
+    timestamp: Annotated[
+        str,
+        Field(
+            description='Time the scheduled send was canceled.',
+            examples=['2026-05-21 12:00:00+00:00'],
+            min_length=1,
+        ),
+    ]
+    data: EventEmailCanceledData
+
+
 class EventEmailClickedData(EventEmailBase):
     model_config = ConfigDict(
         extra='allow',
@@ -987,7 +1101,7 @@ class EventEmailClickedData(EventEmailBase):
     ]
 
 
-class Type5(str, Enum):
+class Type6(str, Enum):
     email_clicked = 'email.clicked'
 
 
@@ -1023,7 +1137,7 @@ class EventEmailComplainedData(EventEmailBase):
     ]
 
 
-class Type6(str, Enum):
+class Type7(str, Enum):
     email_complained = 'email.complained'
 
 
@@ -1076,7 +1190,7 @@ class EventEmailDeferredData(EventEmailBase):
     ]
 
 
-class Type7(str, Enum):
+class Type8(str, Enum):
     email_deferred = 'email.deferred'
 
 
@@ -1105,7 +1219,7 @@ class EventEmailDeliveredData(EventEmailBase):
     )
 
 
-class Type8(str, Enum):
+class Type9(str, Enum):
     email_delivered = 'email.delivered'
 
 
@@ -1134,7 +1248,7 @@ class EventEmailListUnsubscribedData(EventEmailBase):
     )
 
 
-class Type9(str, Enum):
+class Type10(str, Enum):
     email_list_unsubscribed = 'email.list_unsubscribed'
 
 
@@ -1177,7 +1291,7 @@ class EventEmailOpenedData(EventEmailBase):
     ]
 
 
-class Type10(str, Enum):
+class Type11(str, Enum):
     email_opened = 'email.opened'
 
 
@@ -1237,7 +1351,7 @@ class EventEmailOutOfBandBounceData(EventEmailBase):
     ]
 
 
-class Type11(str, Enum):
+class Type12(str, Enum):
     email_out_of_band_bounce = 'email.out_of_band_bounce'
 
 
@@ -1266,7 +1380,7 @@ class EventEmailProcessedData(EventEmailBase):
     )
 
 
-class Type12(str, Enum):
+class Type13(str, Enum):
     email_processed = 'email.processed'
 
 
@@ -1374,7 +1488,7 @@ class EventEmailReceivedData(BaseModel):
     ] = None
 
 
-class Type13(str, Enum):
+class Type14(str, Enum):
     email_received = 'email.received'
 
 
@@ -1402,6 +1516,9 @@ class EmailRejectionReason(str, Enum):
     transmission_failed = 'transmission_failed'
     generation_failure = 'generation_failure'
     policy_rejection = 'policy_rejection'
+    domain_unverified = 'domain_unverified'
+    quota_exceeded = 'quota_exceeded'
+    recipient_not_allowed = 'recipient_not_allowed'
 
 
 class EventEmailRejectedData(EventEmailBase):
@@ -1411,7 +1528,7 @@ class EventEmailRejectedData(EventEmailBase):
     rejection_reason: EmailRejectionReason
 
 
-class Type14(str, Enum):
+class Type15(str, Enum):
     email_rejected = 'email.rejected'
 
 
@@ -1434,13 +1551,50 @@ class EventEmailRejected(BaseModel):
     data: EventEmailRejectedData
 
 
+class EventEmailScheduledData(EventEmailMessageBase):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    scheduled_at: Annotated[
+        str,
+        Field(
+            description='When the message is scheduled to send.',
+            examples=['2026-05-22 09:00:00+00:00'],
+            min_length=1,
+        ),
+    ]
+
+
+class Type16(str, Enum):
+    email_scheduled = 'email.scheduled'
+
+
+class EventEmailScheduled(BaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    type: Annotated[
+        Literal['email.scheduled'],
+        Field(description='Event type.', examples=['email.scheduled']),
+    ]
+    timestamp: Annotated[
+        str,
+        Field(
+            description='Time the send was scheduled.',
+            examples=['2026-05-21 12:00:00+00:00'],
+            min_length=1,
+        ),
+    ]
+    data: EventEmailScheduledData
+
+
 class EventEmailUnsubscribedData(EventEmailBase):
     model_config = ConfigDict(
         extra='allow',
     )
 
 
-class Type15(str, Enum):
+class Type17(str, Enum):
     email_unsubscribed = 'email.unsubscribed'
 
 
@@ -1463,7 +1617,7 @@ class EventEmailUnsubscribed(BaseModel):
     data: EventEmailUnsubscribedData
 
 
-class Type16(str, Enum):
+class Type18(str, Enum):
     email_suppression_created = 'email_suppression.created'
 
 
@@ -1552,7 +1706,7 @@ class EventSMSAcceptedData(EventSMSBase):
     )
 
 
-class Type17(str, Enum):
+class Type19(str, Enum):
     sms_accepted = 'sms.accepted'
 
 
@@ -1595,7 +1749,7 @@ class EventSMSDeliveredData(EventSMSBase):
     ]
 
 
-class Type18(str, Enum):
+class Type20(str, Enum):
     sms_delivered = 'sms.delivered'
 
 
@@ -1624,7 +1778,7 @@ class EventSMSExpiredData(EventSMSBase):
     )
 
 
-class Type19(str, Enum):
+class Type21(str, Enum):
     sms_expired = 'sms.expired'
 
 
@@ -1656,7 +1810,7 @@ class EventSMSFailedData(EventSMSBase):
     ]
 
 
-class Type20(str, Enum):
+class Type22(str, Enum):
     sms_failed = 'sms.failed'
 
 
@@ -1688,7 +1842,7 @@ class EventSMSRejectedData(EventSMSBase):
     ]
 
 
-class Type21(str, Enum):
+class Type23(str, Enum):
     sms_rejected = 'sms.rejected'
 
 
@@ -1731,7 +1885,7 @@ class EventSMSSentData(EventSMSBase):
     ]
 
 
-class Type22(str, Enum):
+class Type24(str, Enum):
     sms_sent = 'sms.sent'
 
 
@@ -1762,7 +1916,7 @@ class EventSMSUndeliveredData(EventSMSBase):
     ]
 
 
-class Type23(str, Enum):
+class Type25(str, Enum):
     sms_undelivered = 'sms.undelivered'
 
 
@@ -1791,6 +1945,7 @@ class WebhookEvent(
         | EventDomainVerified
         | EventEmailAccepted
         | EventEmailBounced
+        | EventEmailCanceled
         | EventEmailClicked
         | EventEmailComplained
         | EventEmailDeferred
@@ -1801,6 +1956,7 @@ class WebhookEvent(
         | EventEmailProcessed
         | EventEmailReceived
         | EventEmailRejected
+        | EventEmailScheduled
         | EventEmailUnsubscribed
         | EventEmailSuppressionCreated
         | EventSMSAccepted
@@ -1817,6 +1973,7 @@ class WebhookEvent(
         | EventDomainVerified
         | EventEmailAccepted
         | EventEmailBounced
+        | EventEmailCanceled
         | EventEmailClicked
         | EventEmailComplained
         | EventEmailDeferred
@@ -1827,6 +1984,7 @@ class WebhookEvent(
         | EventEmailProcessed
         | EventEmailReceived
         | EventEmailRejected
+        | EventEmailScheduled
         | EventEmailUnsubscribed
         | EventEmailSuppressionCreated
         | EventSMSAccepted

messagebird_sdk-0.2.2/src/bird/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

{messagebird_sdk-0.2.0 → messagebird_sdk-0.2.2}/src/bird/resources/email.py

@@ -182,7 +182,6 @@ class Email:
         the server accepts both plain addresses and RFC 5322 mailbox form and normalises them.
 
         ```python
-        # bird:snippet:start email.send
         msg = client.email.send(
             from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
             to=["delivered@messagebird.dev"],
@@ -190,13 +189,11 @@ class Email:
             html="<p>My first Bird email.</p>",
         )
         print(msg.id, msg.status)
-        # bird:snippet:end email.send
         ```
 
         Pass ``options`` for per-call overrides (``timeout``, ``idempotency_key``, …):
 
         ```python
-        # bird:snippet:start email.options
         client.email.send(
             from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
             to=["delivered@messagebird.dev"],
@@ -204,13 +201,11 @@ class Email:
             text="My first Bird email.",
             options={"timeout": 10, "max_retries": 0},
         )
-        # bird:snippet:end email.options
         ```
 
         A failure raises a typed ``APIError``; catch the subclasses you act on:
 
         ```python
-        # bird:snippet:start email.errors
         from bird import APIStatusError, RateLimitError, ValidationError
 
         try:
@@ -226,7 +221,6 @@ class Email:
             print(err.status_code, err.details)
         except APIStatusError as err:
             print(err.status_code, err.code, err.request_id)
-        # bird:snippet:end email.errors
         ```
         """
         body = _send_body(
@@ -254,7 +248,6 @@ class Email:
         value always wins — the same merge :meth:`send` applies.
 
         ```python
-        # bird:snippet:start email.sendBatch
         batch = client.email.send_batch(
             messages=[
                 {
@@ -273,7 +266,6 @@ class Email:
         )
         for item in batch.data:
             print(item.id, item.status)
-        # bird:snippet:end email.sendBatch
         ```
         """
         body = _batch_body(messages, self._defaults)
@@ -303,14 +295,10 @@ class Email:
         """List messages, newest first; iterate the page to auto-paginate.
 
         ```python
-        # bird:snippet:start email.list.paginate
-        # bird:snippet:start email.list.iterate
         for message in client.email.list(status="delivered"):
             print(message.id)
-        # bird:snippet:end email.list.iterate
         page = client.email.list(status="delivered")  # page.data, page.next_cursor
         print(len(page.data), page.next_cursor)
-        # bird:snippet:end email.list.paginate
         ```
         """
         query = _list_query({
@@ -325,13 +313,11 @@ class AsyncEmail:
     """Async mirror of `Email`: ``await`` each call, ``async for`` over a list.
 
     ```python
-    # bird:snippet:start email.list.async
     from bird import AsyncBird
 
     async with AsyncBird() as client:
         async for message in client.email.list(status="delivered"):
             print(message.id)
-    # bird:snippet:end email.list.async
     ```
     """
 

{messagebird_sdk-0.2.0 → messagebird_sdk-0.2.2}/src/bird/resources/webhooks.py

@@ -119,12 +119,10 @@ class Webhooks:
         missing headers.
 
         ```python
-        # bird:snippet:start webhook.unwrap
         # Pass the RAW request body (bytes) and the request headers.
         event = client.webhooks.unwrap(request.body, request.headers)
         if event.root.type == "email.delivered":
             print(event.root.data.email_id)
-        # bird:snippet:end webhook.unwrap
         ```
         """
         return _verify_and_parse(payload, headers, secret or self._secret, tolerance)

messagebird_sdk-0.2.0/src/bird/_version.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"