SDK Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Resend PHP SDK provides a structured interface for interacting with the Resend API. It utilizes a service-based architecture to organize different API domains (emails, domains, API keys, etc.) and employs a transporter layer to handle HTTP communications.
Sources: src/Resend.php, README.md:27-35
Core Components
The architecture consists of four primary layers: the Entry Point, the Client, Services, and Transporters.
Entry Point (Resend Class)
The Resend class provides a static factory method to initialize the SDK. It configures the underlying HTTP client and transporter with a provided API key.
Sources: src/Resend.php, README.md:27
Client and Service Discovery
The Client class acts as a central hub. It uses a ServiceFactory to dynamically provide access to specific API services.
Sources: src/Client.php, src/Service/ServiceFactory.php
Service Layer
Services represent specific API resources like Emails, Domains, or ApiKeys. Each service extends the base Service class and uses a Transporter to send requests.
Sources: src/Service/Service.php, tests/Service/Service.php:6-14
Transporter Layer
The HttpTransporter handles the execution of PSR-7 compliant requests. It manages API headers, base URIs, and transforms API responses into raw data or throws structured exceptions.
Sources: tests/Transporters/HttpTransporter.php:21-30, tests/ValueObjects/Transporter/Payload.php:10-18
Request Lifecycle
The following diagram illustrates how a request flows from the user code through the SDK to the API.
The SDK converts user-provided arrays into Payload value objects, which the HttpTransporter then transforms into standard HTTP requests.
Sources: tests/Transporters/HttpTransporter.php:32-53, tests/ValueObjects/Transporter/Payload.php:10-25
Data Structures
Resources and Collections
The SDK maps API responses to PHP objects.
- Resource: A base class for individual API objects (e.g., a single Email or Domain).
- Collection: A wrapper for list responses containing an array of Resources and metadata like pagination.
Sources: src/Resource.php, src/Collection.php, tests/Service/Service.php:16-23
Payload Management
The Payload value object encapsulates the HTTP method, endpoint, and data required for an API call. It supports different content types, including JSON and multipart/form-data for file uploads.
| Method | Usage | Content Type |
|---|---|---|
create | POST requests | application/json |
list | GET requests | N/A (Query Params) |
upload | File uploads | multipart/form-data |
delete | DELETE requests | N/A |
Sources: tests/ValueObjects/Transporter/Payload.php:10-155
Webhook Security
The SDK includes a WebhookSignature utility to verify incoming webhook requests. It validates the svix-signature header against a shared secret and a timestamp to prevent replay attacks.
Error Handling
The SDK uses structured exceptions to handle failures:
ErrorException: Thrown when the API returns a structured error (e.g., 422 Validation Error).TransporterException: Thrown for networking or connection issues.UnserializableResponse: Thrown when the API returns a response that cannot be parsed as JSON.
Sources: tests/Transporters/HttpTransporter.php:100-165
Summary
The Resend PHP SDK architecture prioritizes modularity by separating API resource logic from the underlying HTTP transport mechanism. This design allows for consistent error handling, clear resource mapping, and secure webhook verification across the library.