Introduction
Relevant source files
The following files were used as context for generating this wiki page:
Resend PHP is a library that provides an interface for interacting with the Resend API. It allows developers to send emails, manage contacts, configure webhooks, and handle complex marketing automations through a structured PHP SDK. The library requires PHP 8.1 or higher and integrates with PSR-compliant HTTP clients.
Sources: README.md:1-26, composer.json:15-20
Core Architecture and Integration
The library uses a transporter-based architecture to manage communication between the PHP application and the Resend API. The HttpTransporter handles the underlying HTTP requests, managing authentication via API keys and ensuring proper content-type headers for both JSON and multipart data.
Request Flow
When a service method is called, the library constructs a Payload object containing the request method, path, and data. The transporter then converts this payload into a PSR-7 request and executes it using the configured HTTP client.
The diagram above illustrates how a call to a client service progresses from payload creation to the final API request and resource hydration.
Sources: tests/Transporters/HttpTransporter.php:26-55, tests/ValueObjects/Transporter/Payload.php:12-25
Dependency Management
The library relies on several key PSR standards and Guzzle components to ensure interoperability.
| Package | Purpose | Version |
|---|---|---|
php | Language runtime | ^8.1.0 |
guzzlehttp/guzzle | Default HTTP client | ^7.8.2 or ^8.0 |
psr/http-client | HTTP client abstraction | ^1.0 |
guzzlehttp/psr7 | PSR-7 implementations | ^2.6.3 or ^3.0 |
Sources: composer.json:15-20
Service Modules
The library organizes the Resend API into specific service modules, each handling a distinct resource type.
Email and Communication
The primary service allows sending emails with simple parameters like from, to, subject, and text. It also supports advanced features such as email templates and inbox drafts. Inboxes support both standalone drafts for new threads and reply drafts for existing conversations.
Sources: README.md:32-37, src/Inboxes/Draft.php:21-25
Automations and Workflows
The Automation module manages multi-step workflows. Automations consist of triggers (e.g., user.created), delays, and conditions.
The flow shows a typical automation sequence involving triggers, timed delays, and conditional branching based on contact properties.
Sources: tests/Fixtures/Automation.php:11-100
Webhook Security
The WebhookSignature class provides a static verify method to validate incoming webhooks. It checks headers provided by the sender (svix-id, svix-timestamp, svix-signature) and validates the SHA256 HMAC hash against a shared secret.
Sources: src/WebhookSignature.php:9-30
Data Handling
Transport Payloads
The library supports different content types depending on the endpoint requirements.
- JSON: Used for most API operations like creating contacts or sending emails.
- Multipart: Used specifically for file uploads, such as importing contact lists.
Sources: tests/ValueObjects/Transporter/Payload.php:40-45, tests/ValueObjects/Transporter/Payload.php:114-125
Error Handling
The HttpTransporter intercepts HTTP responses and maps error status codes to specific PHP exceptions. It handles:
UnserializableResponse: Thrown when the API returns a non-JSON body or unexpected content type.ErrorException: Thrown when the API returns a structured JSON error (e.g., 422 validation errors).TransporterException: Wraps network-level failures like connection timeouts.
Sources: tests/Transporters/HttpTransporter.php:68-165
Conclusion
Resend PHP provides a technical framework for integrating email and automation capabilities into PHP applications. By utilizing PSR standards and a modular service architecture, the library ensures that API interactions are consistent, secure through webhook verification, and capable of handling both simple data and complex file uploads.