feat: add suppressions endpoints

examples/async/suppressions_async.py

@@ -0,0 +1,48 @@
+import asyncio
+import os
+
+import resend
+
+if not os.environ["RESEND_API_KEY"]:
+    raise EnvironmentError("RESEND_API_KEY is missing")
+
+
+async def main() -> None:
+    add_params: resend.Suppressions.AddParams = {
+        "email": "blocked@example.com",
+    }
+    added = await resend.Suppressions.add_async(add_params)
+    print(f"Added suppression: {added['id']}")
+
+    list_params: resend.Suppressions.ListParams = {
+        "origin": "bounce",
+        "limit": 10,
+    }
+    suppressions = await resend.Suppressions.list_async(list_params)
+    print(f"Has more: {suppressions['has_more']}")
+    for suppression in suppressions["data"]:
+        print(f"{suppression['email']} ({suppression['origin']})")
+
+    found: resend.Suppression = await resend.Suppressions.get_async(
+        "blocked@example.com"
+    )
+    print(f"Suppressed at: {found['created_at']}")
+
+    batch_add_params: resend.Suppressions.Batch.AddParams = {
+        "emails": ["one@example.com", "two@example.com"],
+    }
+    batch_added = await resend.Suppressions.Batch.add_async(batch_add_params)
+    print(f"Batch added {len(batch_added['data'])} suppressions")
+
+    batch_remove_params: resend.Suppressions.Batch.RemoveParams = {
+        "ids": [entry["id"] for entry in batch_added["data"]],
+    }
+    batch_removed = await resend.Suppressions.Batch.remove_async(batch_remove_params)
+    print(f"Batch removed {len(batch_removed['data'])} suppressions")
+
+    removed = await resend.Suppressions.remove_async("blocked@example.com")
+    print(f"Removed suppression {removed['id']}: deleted={removed['deleted']}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/suppressions.py

@@ -0,0 +1,49 @@
+import os
+
+import resend
+
+if not os.environ["RESEND_API_KEY"]:
+    raise EnvironmentError("RESEND_API_KEY is missing")
+
+
+# Add: stop delivering to an address.
+add_params: resend.Suppressions.AddParams = {
+    "email": "blocked@example.com",
+}
+added = resend.Suppressions.add(add_params)
+print(f"Added suppression: {added['id']}")
+
+# List: page through suppressions, optionally filtered by origin.
+list_params: resend.Suppressions.ListParams = {
+    "origin": "bounce",
+    "limit": 10,
+}
+suppressions = resend.Suppressions.list(list_params)
+print(f"Has more: {suppressions['has_more']}")
+for suppression in suppressions["data"]:
+    print(
+        f"{suppression['email']} ({suppression['origin']}) "
+        f"source_id={suppression['source_id']}"
+    )
+
+# Get: look up a suppression by ID or by email address.
+found: resend.Suppression = resend.Suppressions.get("blocked@example.com")
+print(f"Suppressed at: {found['created_at']}")
+
+# Batch add: suppress up to 100 addresses in a single call.
+batch_add_params: resend.Suppressions.Batch.AddParams = {
+    "emails": ["one@example.com", "two@example.com"],
+}
+batch_added = resend.Suppressions.Batch.add(batch_add_params)
+print(f"Batch added {len(batch_added['data'])} suppressions")
+
+# Batch remove: pass either emails or ids, never both.
+batch_remove_params: resend.Suppressions.Batch.RemoveParams = {
+    "ids": [entry["id"] for entry in batch_added["data"]],
+}
+batch_removed = resend.Suppressions.Batch.remove(batch_remove_params)
+print(f"Batch removed {len(batch_removed['data'])} suppressions")
+
+# Remove: resume delivering to an address.
+removed = resend.Suppressions.remove("blocked@example.com")
+print(f"Removed suppression {removed['id']}: deleted={removed['deleted']}")

resend/__init__.py

@@ -55,6 +55,12 @@
 from .request import Request
 from .segments._segment import Segment
 from .segments._segments import Segments
+from .suppressions._suppression import (Suppression, SuppressionListItem,
+                                        SuppressionOrigin)
+from .suppressions._suppressions import Suppressions
+from .suppressions.batch._suppressions_batch import (BatchRemovedSuppression,
+                                                     BatchSuppression,
+                                                     SuppressionsBatch)
 from .templates._template import Template, TemplateListItem, Variable
 from .templates._templates import Templates
 from .topics._topic import Topic
@@ -114,6 +120,8 @@
     "Topics",
     "Logs",
     "OAuthGrants",
+    "Suppressions",
+    "SuppressionsBatch",
     # Types
     "Audience",
     "Automation",
@@ -152,6 +160,11 @@
     "Tag",
     "Broadcast",
     "Segment",
+    "Suppression",
+    "SuppressionListItem",
+    "SuppressionOrigin",
+    "BatchSuppression",
+    "BatchRemovedSuppression",
     "Template",
     "TemplateListItem",
     "Variable",

resend/suppressions/__init__.py

@@ -0,0 +1,14 @@
+from ._suppression import Suppression, SuppressionListItem, SuppressionOrigin
+from ._suppressions import Suppressions
+from .batch._suppressions_batch import (BatchRemovedSuppression,
+                                        BatchSuppression, SuppressionsBatch)
+
+__all__ = [
+    "Suppressions",
+    "Suppression",
+    "SuppressionListItem",
+    "SuppressionOrigin",
+    "SuppressionsBatch",
+    "BatchSuppression",
+    "BatchRemovedSuppression",
+]

resend/suppressions/_suppression.py

@@ -0,0 +1,55 @@
+from typing import Optional
+
+from typing_extensions import Literal, TypedDict
+
+from resend._base_response import BaseResponse
+
+SuppressionOrigin = Literal[
+    "bounce",
+    "complaint",
+    "manual",
+]
+
+
+class SuppressionListItem(TypedDict):
+    """
+    SuppressionListItem represents a suppression in list responses.
+
+    List entries do not carry the 'object' field that the get response includes.
+
+    Attributes:
+        id (str): The ID of the suppression.
+        email (str): The suppressed email address.
+        origin (SuppressionOrigin): What caused the address to be suppressed.
+        source_id (Optional[str]): The ID of the event that caused the suppression,
+            such as the email that bounced or complained. None for manual suppressions.
+        created_at (str): The date and time the suppression was created.
+    """
+
+    id: str
+    email: str
+    origin: SuppressionOrigin
+    source_id: Optional[str]
+    created_at: str
+
+
+class Suppression(BaseResponse):
+    """
+    Suppression represents an email address that Resend will not deliver to.
+
+    Attributes:
+        object (str): Always 'suppression'.
+        id (str): The ID of the suppression.
+        email (str): The suppressed email address.
+        origin (SuppressionOrigin): What caused the address to be suppressed.
+        source_id (Optional[str]): The ID of the event that caused the suppression,
+            such as the email that bounced or complained. None for manual suppressions.
+        created_at (str): The date and time the suppression was created.
+    """
+
+    object: str
+    id: str
+    email: str
+    origin: SuppressionOrigin
+    source_id: Optional[str]
+    created_at: str