feat: Add emails list method with pagination (#162)

Author: drish

examples/simple_email.py

@@ -42,3 +42,23 @@
 print("Email reply_to: ", email_resp["reply_to"])
 print("Email bcc: ", email_resp["bcc"])
 print("Email cc: ", email_resp["cc"])
+
+print("\n--- Listing Emails ---")
+
+# List all emails
+all_emails = resend.Emails.list()
+print(f"Total emails in this batch: {len(all_emails['data'])}")
+print(f"Has more emails: {all_emails['has_more']}")
+
+# List with pagination
+list_params: resend.Emails.ListParams = {
+    "limit": 5,
+}
+paginated_emails = resend.Emails.list(params=list_params)
+print(f"Retrieved {len(paginated_emails['data'])} emails (limited to 5)")
+
+# Example with cursor-based pagination
+if paginated_emails["data"]:
+    last_email_id = paginated_emails["data"][-1]["id"]
+    next_page = resend.Emails.list(params={"limit": 5, "after": last_email_id})
+    print(f"Next page has {len(next_page['data'])} emails")

resend/emails/_emails.py

@@ -6,6 +6,7 @@
 from resend.emails._attachment import Attachment, RemoteAttachment
 from resend.emails._email import Email
 from resend.emails._tag import Tag
+from resend.pagination_helper import PaginationHelper
 
 
 class _UpdateParams(TypedDict):
@@ -178,6 +179,52 @@ class SendResponse(TypedDict):
         The sent Email ID.
         """
 
+    class ListParams(TypedDict):
+        """
+        ListParams is the class that wraps the parameters for the list method.
+
+        Attributes:
+            limit (NotRequired[int]): The maximum number of emails to return. Defaults to 10, maximum 100.
+            after (NotRequired[str]): Return emails after this cursor for pagination.
+            before (NotRequired[str]): Return emails before this cursor for pagination.
+        """
+
+        limit: NotRequired[int]
+        """
+        The maximum number of emails to return. Defaults to 10, maximum 100.
+        """
+        after: NotRequired[str]
+        """
+        Return emails after this cursor for pagination.
+        """
+        before: NotRequired[str]
+        """
+        Return emails before this cursor for pagination.
+        """
+
+    class ListResponse(TypedDict):
+        """
+        ListResponse is the type that wraps the response for listing emails.
+
+        Attributes:
+            object (str): The object type: "list"
+            data (List[Email]): The list of email objects.
+            has_more (bool): Whether there are more emails available for pagination.
+        """
+
+        object: str
+        """
+        The object type: "list"
+        """
+        data: List[Email]
+        """
+        The list of email objects.
+        """
+        has_more: bool
+        """
+        Whether there are more emails available for pagination.
+        """
+
     @classmethod
     def send(
         cls, params: SendParams, options: Optional[SendOptions] = None
@@ -261,3 +308,25 @@ def update(cls, params: UpdateParams) -> UpdateEmailResponse:
             verb="patch",
         ).perform_with_content()
         return resp
+
+    @classmethod
+    def list(cls, params: Optional[ListParams] = None) -> ListResponse:
+        """
+        Retrieve a list of emails.
+        see more: https://resend.com/docs/api-reference/emails/list-emails
+
+        Args:
+            params (Optional[ListParams]): The list parameters for pagination
+
+        Returns:
+            ListResponse: A paginated list of email objects
+        """
+        base_path = "/emails"
+        query_params = cast(Dict[Any, Any], params) if params else None
+        path = PaginationHelper.build_paginated_path(base_path, query_params)
+        resp = request.Request[Emails.ListResponse](
+            path=path,
+            params={},
+            verb="get",
+        ).perform_with_content()
+        return resp

tests/emails_test.py

@@ -156,3 +156,101 @@ def test_email_send_with_inline_attachment(self) -> None:
         }
         email: resend.Emails.SendResponse = resend.Emails.send(params)
         assert email["id"] == "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
+
+    def test_email_list(self) -> None:
+        self.set_mock_json(
+            {
+                "object": "list",
+                "data": [
+                    {
+                        "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
+                        "to": ["james@bond.com"],
+                        "from": "onboarding@resend.dev",
+                        "created_at": "2023-04-03T22:13:42.674981+00:00",
+                        "subject": "Hello World",
+                        "html": "Congrats on sending your <strong>first email</strong>!",
+                        "text": None,
+                        "bcc": [None],
+                        "cc": [None],
+                        "reply_to": [None],
+                        "last_event": "delivered",
+                    },
+                    {
+                        "id": "5ef9a417-02e9-4d39-ad75-9611e0fcc33d",
+                        "to": ["test@example.com"],
+                        "from": "hello@resend.dev",
+                        "created_at": "2023-04-04T10:15:42.674981+00:00",
+                        "subject": "Test Email",
+                        "html": "This is a test email",
+                        "text": "This is a test email",
+                        "bcc": [None],
+                        "cc": [None],
+                        "reply_to": [None],
+                        "last_event": "sent",
+                    },
+                ],
+                "has_more": True,
+            }
+        )
+
+        emails: resend.Emails.ListResponse = resend.Emails.list()
+        assert emails["object"] == "list"
+        assert len(emails["data"]) == 2
+        assert emails["has_more"] == True
+        assert emails["data"][0]["id"] == "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
+        assert emails["data"][1]["id"] == "5ef9a417-02e9-4d39-ad75-9611e0fcc33d"
+
+    def test_email_list_with_params(self) -> None:
+        self.set_mock_json(
+            {
+                "object": "list",
+                "data": [
+                    {
+                        "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
+                        "to": ["james@bond.com"],
+                        "from": "onboarding@resend.dev",
+                        "created_at": "2023-04-03T22:13:42.674981+00:00",
+                        "subject": "Hello World",
+                        "html": "Congrats on sending your <strong>first email</strong>!",
+                        "text": None,
+                        "bcc": [None],
+                        "cc": [None],
+                        "reply_to": [None],
+                        "last_event": "delivered",
+                    },
+                ],
+                "has_more": False,
+            }
+        )
+
+        list_params: resend.Emails.ListParams = {
+            "limit": 10,
+            "after": "cursor123",
+        }
+        emails: resend.Emails.ListResponse = resend.Emails.list(params=list_params)
+        assert emails["object"] == "list"
+        assert len(emails["data"]) == 1
+        assert emails["has_more"] == False
+
+    def test_email_list_with_before_param(self) -> None:
+        self.set_mock_json(
+            {
+                "object": "list",
+                "data": [],
+                "has_more": False,
+            }
+        )
+
+        list_params: resend.Emails.ListParams = {
+            "limit": 5,
+            "before": "cursor456",
+        }
+        emails: resend.Emails.ListResponse = resend.Emails.list(params=list_params)
+        assert emails["object"] == "list"
+        assert len(emails["data"]) == 0
+        assert emails["has_more"] == False
+
+    def test_should_list_email_raise_exception_when_no_content(self) -> None:
+        self.set_mock_json(None)
+        with self.assertRaises(NoContentError):
+            _ = resend.Emails.list()