feat: init async support with httpx

Author: drish

examples/simple_email_async.py

@@ -0,0 +1,54 @@
+import asyncio
+import os
+
+import resend
+from resend import HTTPXClient
+
+if not os.environ["RESEND_API_KEY"]:
+    raise EnvironmentError("RESEND_API_KEY is missing")
+
+# Set up async HTTP client
+resend.default_http_client = HTTPXClient()
+
+params: resend.Emails.SendParams = {
+    "from": "onboarding@resend.dev",
+    "to": ["delivered@resend.dev"],
+    "subject": "hi",
+    "html": "<strong>hello, world!</strong>",
+    "reply_to": "to@gmail.com",
+    "bcc": "delivered@resend.dev",
+    "cc": ["delivered@resend.dev"],
+    "tags": [
+        {"name": "tag1", "value": "tagvalue1"},
+        {"name": "tag2", "value": "tagvalue2"},
+    ],
+}
+
+
+async def main():
+    # Without Idempotency Key
+    email_non_idempotent: resend.Email = await resend.Emails.send_async(params)
+    print(f"Sent email without idempotency key: {email_non_idempotent['id']}")
+
+    # With Idempotency Key
+    options: resend.Emails.SendOptions = {
+        "idempotency_key": "44",
+    }
+    email_idempotent: resend.Email = await resend.Emails.send_async(params, options)
+    print(f"Sent email with idempotency key: {email_idempotent['id']}")
+
+    email_resp: resend.Email = await resend.Emails.get_async(email_id=email_non_idempotent["id"])
+    print(f"Retrieved email: {email_resp['id']}")
+    print("Email ID: ", email_resp["id"])
+    print("Email from: ", email_resp["from"])
+    print("Email to: ", email_resp["to"])
+    print("Email subject: ", email_resp["subject"])
+    print("Email html: ", email_resp["html"])
+    print("Email created_at: ", email_resp["created_at"])
+    print("Email reply_to: ", email_resp["reply_to"])
+    print("Email bcc: ", email_resp["bcc"])
+    print("Email cc: ", email_resp["cc"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

requirements-dev.txt

@@ -0,0 +1 @@
+httpx>=0.24.0

resend/__init__.py

@@ -18,6 +18,15 @@
 from .http_client import HTTPClient
 from .http_client_requests import RequestsClient
 from .request import Request
+
+# Async imports (optional - only available with pip install resend[async])
+try:
+    from .http_client_async import AsyncHTTPClient
+    from .http_client_httpx import HTTPXClient
+    from .async_request import AsyncRequest
+except ImportError:
+    # Async classes not available without httpx dependency
+    pass
 from .version import __version__, get_version
 
 # Config vars
@@ -50,6 +59,18 @@
     "Attachment",
     "Tag",
     "Broadcast",
-    # Default HTTP Client
+    # HTTP Clients
+    "HTTPClient",
     "RequestsClient",
 ]
+
+# Add async exports if available
+try:
+    from .http_client_httpx import HTTPXClient
+    __all__.extend([
+        "AsyncHTTPClient", 
+        "HTTPXClient",
+        "AsyncRequest"
+    ])
+except ImportError:
+    pass

resend/async_request.py

@@ -0,0 +1,108 @@
+import json
+from typing import Any, Dict, Generic, List, Optional, Union, cast
+
+from typing_extensions import Literal, TypeVar
+
+import resend
+from resend.exceptions import (NoContentError, ResendError,
+                               raise_for_code_and_type)
+from resend.version import get_version
+
+RequestVerb = Literal["get", "post", "put", "patch", "delete"]
+T = TypeVar("T")
+
+ParamsType = Union[Dict[str, Any], List[Dict[str, Any]]]
+HeadersType = Dict[str, str]
+
+
+class AsyncRequest(Generic[T]):
+    def __init__(
+        self,
+        path: str,
+        params: ParamsType,
+        verb: RequestVerb,
+        options: Optional[Dict[str, Any]] = None,
+    ):
+        self.path = path
+        self.params = params
+        self.verb = verb
+        self.options = options
+
+    async def perform(self) -> Union[T, None]:
+        data = await self.make_request(url=f"{resend.api_url}{self.path}")
+
+        if isinstance(data, dict) and data.get("statusCode") not in (None, 200):
+            raise_for_code_and_type(
+                code=data.get("statusCode") or 500,
+                message=data.get("message", "Unknown error"),
+                error_type=data.get("name", "InternalServerError"),
+            )
+
+        return cast(T, data)
+
+    async def perform_with_content(self) -> T:
+        resp = await self.perform()
+        if resp is None:
+            raise NoContentError()
+        return resp
+
+    def __get_headers(self) -> HeadersType:
+        headers: HeadersType = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {resend.api_key}",
+            "User-Agent": f"resend-python:{get_version()}",
+        }
+
+        if self.verb == "post" and self.options and "idempotency_key" in self.options:
+            headers["Idempotency-Key"] = str(self.options["idempotency_key"])
+
+        return headers
+
+    async def make_request(self, url: str) -> Union[Dict[str, Any], List[Any]]:
+        headers = self.__get_headers()
+
+        if isinstance(self.params, dict):
+            json_params: Optional[Union[Dict[str, Any], List[Any]]] = {
+                str(k): v for k, v in self.params.items()
+            }
+        elif isinstance(self.params, list):
+            json_params = [dict(item) for item in self.params]
+        else:
+            json_params = None
+
+        try:
+            content, _status_code, resp_headers = await resend.default_http_client.request(
+                method=self.verb,
+                url=url,
+                headers=headers,
+                json=json_params,
+            )
+
+        # Safety net around the HTTP Client
+        except Exception as e:
+            raise ResendError(
+                code=500,
+                message=str(e),
+                error_type="HttpClientError",
+                suggested_action="Request failed, please try again.",
+            )
+
+        content_type = {k.lower(): v for k, v in resp_headers.items()}.get(
+            "content-type", ""
+        )
+
+        if "application/json" not in content_type:
+            raise_for_code_and_type(
+                code=500,
+                message=f"Expected JSON response but got: {content_type}",
+                error_type="InternalServerError",
+            )
+
+        try:
+            return cast(Union[Dict[str, Any], List[Any]], json.loads(content))
+        except json.JSONDecodeError:
+            raise_for_code_and_type(
+                code=500,
+                message="Failed to decode JSON response",
+                error_type="InternalServerError",
+            )

resend/emails/_emails.py

@@ -7,6 +7,12 @@
 from resend.emails._email import Email
 from resend.emails._tag import Tag
 
+# Async imports (optional - only available with pip install resend[async])
+try:
+    from resend.async_request import AsyncRequest
+except ImportError:
+    pass
+
 
 class _SendOptions(TypedDict):
     idempotency_key: NotRequired[str]
@@ -248,3 +254,85 @@ def update(cls, params: UpdateParams) -> UpdateEmailResponse:
             verb="patch",
         ).perform_with_content()
         return resp
+
+    @classmethod
+    async def send_async(cls, params: SendParams, options: Optional[SendOptions] = None) -> Email:
+        """
+        Send an email through the Resend Email API (async version).
+        see more: https://resend.com/docs/api-reference/emails/send-email
+
+        Args:
+            params (SendParams): The email parameters
+            options (SendOptions): The email options
+
+        Returns:
+            Email: The email object that was sent
+        """
+        path = "/emails"
+        resp = await AsyncRequest[Email](
+            path=path,
+            params=cast(Dict[Any, Any], params),
+            verb="post",
+            options=cast(Dict[Any, Any], options),
+        ).perform_with_content()
+        return resp
+
+    @classmethod
+    async def get_async(cls, email_id: str) -> Email:
+        """
+        Retrieve a single email (async version).
+        see more: https://resend.com/docs/api-reference/emails/retrieve-email
+
+        Args:
+            email_id (str): The ID of the email to retrieve
+
+        Returns:
+            Email: The email object that was retrieved
+        """
+        path = f"/emails/{email_id}"
+        resp = await AsyncRequest[Email](
+            path=path,
+            params={},
+            verb="get",
+        ).perform_with_content()
+        return resp
+
+    @classmethod
+    async def cancel_async(cls, email_id: str) -> CancelScheduledEmailResponse:
+        """
+        Cancel a scheduled email (async version).
+        see more: https://resend.com/docs/api-reference/emails/cancel-email
+
+        Args:
+            email_id (str): The ID of the scheduled email to cancel
+
+        Returns:
+            CancelScheduledEmailResponse: The response object that contains the ID of the scheduled email that was canceled
+        """
+        path = f"/emails/{email_id}/cancel"
+        resp = await AsyncRequest[_CancelScheduledEmailResponse](
+            path=path,
+            params={},
+            verb="post",
+        ).perform_with_content()
+        return resp
+
+    @classmethod
+    async def update_async(cls, params: UpdateParams) -> UpdateEmailResponse:
+        """
+        Update an email (async version).
+        see more: https://resend.com/docs/api-reference/emails/update-email
+
+        Args:
+            params (UpdateParams): The email parameters to update
+
+        Returns:
+            Email: The email object that was updated
+        """
+        path = f"/emails/{params['id']}"
+        resp = await AsyncRequest[_UpdateEmailResponse](
+            path=path,
+            params=cast(Dict[Any, Any], params),
+            verb="patch",
+        ).perform_with_content()
+        return resp

resend/http_client_async.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List, Mapping, Optional, Tuple, Union
+
+
+class AsyncHTTPClient(ABC):
+    """
+    Abstract base class for async HTTP clients.
+    This class defines the interface for making async HTTP requests.
+    Subclasses should implement the `request` method.
+    """
+
+    @abstractmethod
+    async def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        json: Optional[Union[Dict[str, object], List[object]]] = None,
+    ) -> Tuple[bytes, int, Mapping[str, str]]:
+        pass

resend/http_client_httpx.py

@@ -0,0 +1,40 @@
+from typing import Dict, List, Mapping, Optional, Tuple, Union
+
+from resend.http_client_async import AsyncHTTPClient
+
+try:
+    import httpx
+except ImportError:
+    raise ImportError(
+        "httpx is required for async support. Install it with: pip install resend[async]"
+    )
+
+
+class HTTPXClient(AsyncHTTPClient):
+    """
+    Async HTTP client implementation using the httpx library.
+    """
+
+    def __init__(self, timeout: int = 30):
+        self._timeout = timeout
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        json: Optional[Union[Dict[str, object], List[object]]] = None,
+    ) -> Tuple[bytes, int, Mapping[str, str]]:
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                resp = await client.request(
+                    method=method,
+                    url=url,
+                    headers=headers,
+                    json=json,
+                )
+                return resp.content, resp.status_code, resp.headers
+        except httpx.RequestError as e:
+            # This gets caught by the async request.perform() method
+            # and raises a ResendError with the error type "HttpClientError"
+            raise RuntimeError(f"Request failed: {e}") from e

setup.py

@@ -18,6 +18,9 @@
     packages=find_packages(exclude=["tests", "tests.*"]),
     package_data={"resend": ["py.typed"]},
     install_requires=install_requires,
+    extras_require={
+        "async": ["httpx>=0.24.0"],
+    },
     zip_safe=False,
     python_requires=">=3.7",
     keywords=["email", "email platform"],