feat: Optional pagination list methods (#165)

Author: drish

examples/api_keys.py

@@ -22,5 +22,19 @@
     print(key["name"])
     print(key["created_at"])
 
+print("\n--- Using pagination parameters ---")
+if keys["data"]:
+    paginated_params: resend.ApiKeys.ListParams = {
+        "limit": 8,
+        "after": keys["data"][0]["id"],
+    }
+    paginated_keys: resend.ApiKeys.ListResponse = resend.ApiKeys.list(
+        params=paginated_params
+    )
+    print(f"Retrieved {len(paginated_keys['data'])} keys with pagination")
+    print(f"Has more keys: {paginated_keys['has_more']}")
+else:
+    print("No keys available for pagination example")
+
 if len(keys["data"]) > 0:
     resend.ApiKeys.remove(api_key_id=keys["data"][0]["id"])

examples/audiences.py

@@ -21,6 +21,21 @@
 
 audiences: resend.Audiences.ListResponse = resend.Audiences.list()
 print("List of audiences:", [a["id"] for a in audiences["data"]])
+print(f"Has more audiences: {audiences['has_more']}")
+
+print("\n--- Using pagination parameters ---")
+if audiences["data"]:
+    paginated_params: resend.Audiences.ListParams = {
+        "limit": 5,
+        "after": audiences["data"][0]["id"],
+    }
+    paginated_audiences: resend.Audiences.ListResponse = resend.Audiences.list(
+        params=paginated_params
+    )
+    print(f"Retrieved {len(paginated_audiences['data'])} audiences with pagination")
+    print(f"Has more audiences: {paginated_audiences['has_more']}")
+else:
+    print("No audiences available for pagination example")
 
 rmed: resend.Audiences.RemoveAudienceResponse = resend.Audiences.remove(
     id=audience["id"]

examples/broadcasts.py

@@ -58,4 +58,19 @@
 
 list_response: resend.Broadcasts.ListResponse = resend.Broadcasts.list()
 print("List of broadcasts !\n")
-print(list_response)
+print(f"Found {len(list_response['data'])} broadcasts")
+print(f"Has more broadcasts: {list_response['has_more']}")
+
+print("\n--- Using pagination parameters ---")
+if list_response["data"]:
+    paginated_params: resend.Broadcasts.ListParams = {
+        "limit": 3,
+        "after": list_response["data"][0]["id"],
+    }
+    paginated_broadcasts: resend.Broadcasts.ListResponse = resend.Broadcasts.list(
+        params=paginated_params
+    )
+    print(f"Retrieved {len(paginated_broadcasts['data'])} broadcasts with pagination")
+    print(f"Has more broadcasts: {paginated_broadcasts['has_more']}")
+else:
+    print("No broadcasts available for pagination example")

examples/contacts.py

@@ -46,9 +46,25 @@
 
 contacts: resend.Contacts.ListResponse = resend.Contacts.list(audience_id=audience_id)
 print("List of contacts")
+print(f"Found {len(contacts['data'])} contacts")
+print(f"Has more contacts: {contacts['has_more']}")
 for c in contacts["data"]:
     print(c)
 
+print("\n--- Using pagination parameters ---")
+if contacts["data"]:
+    paginated_params: resend.Contacts.ListParams = {
+        "limit": 2,
+        "after": contacts["data"][0]["id"],
+    }
+    paginated_contacts: resend.Contacts.ListResponse = resend.Contacts.list(
+        audience_id=audience_id, params=paginated_params
+    )
+    print(f"Retrieved {len(paginated_contacts['data'])} contacts with pagination")
+    print(f"Has more contacts: {paginated_contacts['has_more']}")
+else:
+    print("No contacts available for pagination example")
+
 # remove by email
 rmed: resend.Contacts.RemoveContactResponse = resend.Contacts.remove(
     audience_id=audience_id, email=cont_by_email["email"]

examples/domains.py

@@ -33,11 +33,27 @@
 print(f"Updated domain: {updated_domain['id']}")
 
 domains: resend.Domains.ListResponse = resend.Domains.list()
-if not domains:
+print(f"Found {len(domains['data'])} domains")
+print(f"Has more domains: {domains['has_more']}")
+if not domains["data"]:
     print("No domains found")
 for domain in domains["data"]:
     print(domain)
 
+print("\n--- Using pagination parameters ---")
+if domains["data"]:
+    paginated_params: resend.Domains.ListParams = {
+        "limit": 2,
+        "after": domains["data"][0]["id"],
+    }
+    paginated_domains: resend.Domains.ListResponse = resend.Domains.list(
+        params=paginated_params
+    )
+    print(f"Retrieved {len(paginated_domains['data'])} domains with pagination")
+    print(f"Has more domains: {paginated_domains['has_more']}")
+else:
+    print("No domains available for pagination example")
+
 verified_domain: resend.Domain = resend.Domains.verify(domain_id=domain["id"])
 print(f"Verified")
 print(verified_domain)

resend/api_keys/_api_keys.py

@@ -1,25 +1,36 @@
-from typing import Any, Dict, List, cast
+from typing import Any, Dict, List, Optional, cast
 
 from typing_extensions import NotRequired, TypedDict
 
 from resend import request
 from resend.api_keys._api_key import ApiKey
+from resend.pagination_helper import PaginationHelper
 
 
 class ApiKeys:
 
     class ListResponse(TypedDict):
         """
-        ListResponse type that wraps a list of API key objects
+        ListResponse type that wraps a list of API key objects with pagination metadata
 
         Attributes:
+            object (str): The object type, always "list"
             data (List[ApiKey]): A list of API key objects
+            has_more (bool): Whether there are more results available
         """
 
+        object: str
+        """
+        The object type, always "list"
+        """
         data: List[ApiKey]
         """
         A list of API key objects
         """
+        has_more: bool
+        """
+        Whether there are more results available for pagination
+        """
 
     class CreateApiKeyResponse(TypedDict):
         """
@@ -39,6 +50,24 @@ class CreateApiKeyResponse(TypedDict):
         The token of the created API key
         """
 
+    class ListParams(TypedDict):
+        limit: NotRequired[int]
+        """
+        Number of API keys to retrieve. Maximum is 100, and minimum is 1.
+        """
+        after: NotRequired[str]
+        """
+        The ID after which we'll retrieve more API keys (for pagination).
+        This ID will not be included in the returned list.
+        Cannot be used with the before parameter.
+        """
+        before: NotRequired[str]
+        """
+        The ID before which we'll retrieve more API keys (for pagination).
+        This ID will not be included in the returned list.
+        Cannot be used with the after parameter.
+        """
+
     class CreateParams(TypedDict):
         name: str
         """
@@ -75,15 +104,23 @@ def create(cls, params: CreateParams) -> CreateApiKeyResponse:
         return resp
 
     @classmethod
-    def list(cls) -> ListResponse:
+    def list(cls, params: Optional[ListParams] = None) -> ListResponse:
         """
         Retrieve a list of API keys for the authenticated user.
         see more: https://resend.com/docs/api-reference/api-keys/list-api-keys
 
+        Args:
+            params (Optional[ListParams]): Optional pagination parameters
+                - limit: Number of API keys to retrieve (max 100, min 1)
+                - after: ID after which to retrieve more API keys
+                - before: ID before which to retrieve more API keys
+
         Returns:
             ListResponse: A list of API key objects
         """
-        path = "/api-keys"
+        base_path = "/api-keys"
+        query_params = cast(Dict[Any, Any], params) if params else None
+        path = PaginationHelper.build_paginated_path(base_path, query_params)
         resp = request.Request[ApiKeys.ListResponse](
             path=path, params={}, verb="get"
         ).perform_with_content()

resend/audiences/_audiences.py

@@ -1,8 +1,9 @@
-from typing import Any, Dict, List, cast
+from typing import Any, Dict, List, Optional, cast
 
-from typing_extensions import TypedDict
+from typing_extensions import NotRequired, TypedDict
 
 from resend import request
+from resend.pagination_helper import PaginationHelper
 
 from ._audience import Audience
 
@@ -32,23 +33,46 @@ class RemoveAudienceResponse(TypedDict):
         Whether the audience was deleted
         """
 
+    class ListParams(TypedDict):
+        limit: NotRequired[int]
+        """
+        Number of audiences to retrieve. Maximum is 100, and minimum is 1.
+        """
+        after: NotRequired[str]
+        """
+        The ID after which we'll retrieve more audiences (for pagination).
+        This ID will not be included in the returned list.
+        Cannot be used with the before parameter.
+        """
+        before: NotRequired[str]
+        """
+        The ID before which we'll retrieve more audiences (for pagination).
+        This ID will not be included in the returned list.
+        Cannot be used with the after parameter.
+        """
+
     class ListResponse(TypedDict):
         """
-        ListResponse type that wraps a list of audience objects
+        ListResponse type that wraps a list of audience objects with pagination metadata
 
         Attributes:
-            object (str): The object type, "list"
+            object (str): The object type, always "list"
             data (List[Audience]): A list of audience objects
+            has_more (bool): Whether there are more results available
         """
 
         object: str
         """
-        The object type, "list"
+        The object type, always "list"
         """
         data: List[Audience]
         """
         A list of audience objects
         """
+        has_more: bool
+        """
+        Whether there are more results available for pagination
+        """
 
     class CreateAudienceResponse(TypedDict):
         """
@@ -99,15 +123,24 @@ def create(cls, params: CreateParams) -> CreateAudienceResponse:
         return resp
 
     @classmethod
-    def list(cls) -> ListResponse:
+    def list(cls, params: Optional[ListParams] = None) -> ListResponse:
         """
         Retrieve a list of audiences.
         see more: https://resend.com/docs/api-reference/audiences/list-audiences
 
+        Args:
+            params (Optional[ListParams]): Optional pagination parameters
+                - limit: Number of audiences to retrieve (max 100, min 1).
+                  If not provided, all audiences will be returned without pagination.
+                - after: ID after which to retrieve more audiences
+                - before: ID before which to retrieve more audiences
+
         Returns:
             ListResponse: A list of audience objects
         """
-        path = "/audiences/"
+        base_path = "/audiences"
+        query_params = cast(Dict[Any, Any], params) if params else None
+        path = PaginationHelper.build_paginated_path(base_path, query_params)
         resp = request.Request[Audiences.ListResponse](
             path=path, params={}, verb="get"
         ).perform_with_content()

resend/broadcasts/_broadcasts.py

@@ -1,8 +1,9 @@
-from typing import Any, Dict, List, Union, cast
+from typing import Any, Dict, List, Optional, Union, cast
 
 from typing_extensions import NotRequired, TypedDict
 
 from resend import request
+from resend.pagination_helper import PaginationHelper
 
 from ._broadcast import Broadcast
 
@@ -160,23 +161,46 @@ class SendResponse(CreateResponse):
             id (str): id of the created broadcast
         """
 
+    class ListParams(TypedDict):
+        limit: NotRequired[int]
+        """
+        Number of broadcasts to retrieve. Maximum is 100, and minimum is 1.
+        """
+        after: NotRequired[str]
+        """
+        The ID after which we'll retrieve more broadcasts (for pagination).
+        This ID will not be included in the returned list.
+        Cannot be used with the before parameter.
+        """
+        before: NotRequired[str]
+        """
+        The ID before which we'll retrieve more broadcasts (for pagination).
+        This ID will not be included in the returned list.
+        Cannot be used with the after parameter.
+        """
+
     class ListResponse(TypedDict):
         """
-        ListResponse is the class that wraps the response of the list method.
+        ListResponse is the class that wraps the response of the list method with pagination metadata.
 
         Attributes:
-            object (str): object type: "list"
+            object (str): object type, always "list"
             data (List[Broadcast]): A list of broadcast objects
+            has_more (bool): Whether there are more results available
         """
 
         object: str
         """
-        object type: "list"
+        object type, always "list"
         """
         data: List[Broadcast]
         """
         A list of broadcast objects
         """
+        has_more: bool
+        """
+        Whether there are more results available for pagination
+        """
 
     class RemoveResponse(TypedDict):
         """
@@ -259,15 +283,24 @@ def send(cls, params: SendParams) -> SendResponse:
         return resp
 
     @classmethod
-    def list(cls) -> ListResponse:
+    def list(cls, params: Optional[ListParams] = None) -> ListResponse:
         """
         Retrieve a list of broadcasts.
         see more: https://resend.com/docs/api-reference/broadcasts/list-broadcasts
 
+        Args:
+            params (Optional[ListParams]): Optional pagination parameters
+                - limit: Number of broadcasts to retrieve (max 100, min 1).
+                  If not provided, all broadcasts will be returned without pagination.
+                - after: ID after which to retrieve more broadcasts
+                - before: ID before which to retrieve more broadcasts
+
         Returns:
             ListResponse: A list of broadcast objects
         """
-        path = "/broadcasts/"
+        base_path = "/broadcasts"
+        query_params = cast(Dict[Any, Any], params) if params else None
+        path = PaginationHelper.build_paginated_path(base_path, query_params)
         resp = request.Request[Broadcasts.ListResponse](
             path=path, params={}, verb="get"
         ).perform_with_content()