Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• composer.json
• src/WebhookSignature.php
• tests/Transporters/HttpTransporter.php
• tests/ValueObjects/Transporter/Payload.php
• tests/Service/Domain.php
• tests/Service/Contact.php
• tests/Service/Usage.php

Resend PHP provides a structured SDK to interact with the Resend API for email delivery and management. The library utilizes modern PHP 8.1+ features and adheres to PSR standards for HTTP communication.

You use the Resend client to manage various resources including emails, domains, contacts, and webhooks. The library handles authentication, payload serialization, and response parsing automatically.

Sources: README.md:1-35, composer.json:13-18

Installation and Requirements

To use the Resend PHP library, your environment must meet specific version requirements.

System Requirements

• PHP Version: 8.1.0 or higher.
• Dependencies: The library requires guzzlehttp/guzzle, guzzlehttp/psr7, and psr/http-client.

Sources: composer.json:14-17, README.md:21

Installation Steps

1. Open your terminal in the project root.
2. Run the Composer command: composer require resend/resend-php.

Sources: README.md:23-25

Client Initialization

The Resend::client() method creates a new API client instance. This instance acts as the gateway to all Resend services.

$resend = Resend::client('re_123456789');

Sources: README.md:29

Authentication Flow

The client uses an API Key for authorization. Every request sent by the transporter includes this key in the Authorization header.

The diagram shows how the API Key is processed from client initialization to the transport layer.
Sources: tests/Transporters/HttpTransporter.php:23-28, tests/ValueObjects/Transporter/Payload.php:14-16

Core Services

The library organizes functionality into specialized services accessible via the main client.

Service Name	Purpose	Primary Methods
emails	Send and track emails	send(), get()
domains	Manage sender domains	create(), verify(), list(), remove()
contacts	Manage audience data	create(), list(), update(), remove()
webhooks	Handle event notifications	create(), list(), verify()
usage	Monitor account limits	get()

Sources: tests/Service/Domain.php:7-71, tests/Service/Contact.php:8-98, tests/Service/Usage.php:7-40, README.md:31-36

Basic Usage Example: Sending an Email

The following code demonstrates a standard email request:

$resend->emails->send([
    'from' => 'onboarding@resend.dev',
    'to' => 'user@gmail.com',
    'subject' => 'hello world',
    'text' => 'it works!',
]);

Sources: README.md:31-36

Request and Response Architecture

The library uses a HttpTransporter to communicate with the Resend API at api.resend.com.

Payload Handling

The Payload value object determines the HTTP method and body format based on the action:

• POST/PATCH/PUT: Includes a JSON-encoded body.
• GET/DELETE: Typically contains no body, using URI parameters for filtering or pagination.
• Multipart: Used for file uploads, such as contact imports.

Sources: tests/ValueObjects/Transporter/Payload.php:12-42, tests/ValueObjects/Transporter/Payload.php:104-123

Communication Flow

The sequence diagram illustrates the internal delegation of a request from the user's application to the Resend API.
Sources: tests/Transporters/HttpTransporter.php:33-52, tests/Service/Domain.php:36-40

Webhook Security

Resend includes a WebhookSignature class to verify that incoming webhook requests originate from Resend.

Verification Process

1. Extract headers: svix-id, svix-timestamp, and svix-signature.
2. Provide the raw request body (payload).
3. Provide the Webhook Secret (prefixed with whsec_ or raw).
4. The system validates the timestamp against a tolerance (default 300 seconds) and verifies the HMAC SHA256 signature.

Sources: src/WebhookSignature.php:9-47, tests/WebhookSignature.php:14-20

Error Handling

The transporter identifies and throws specific exceptions when API requests fail.

• ErrorException: Thrown when the API returns a structured error (e.g., status 422 for missing required fields).
• TransporterException: Thrown for network or connection issues.
• UnserializableResponse: Thrown when the API response is not valid JSON or has an unexpected content type.

Sources: tests/Transporters/HttpTransporter.php:75-88, tests/Transporters/HttpTransporter.php:131-144, tests/Transporters/HttpTransporter.php:178-185

Conclusion

Getting started with Resend PHP requires minimal configuration: installing the package via Composer and initializing the client with an API key. The library's service-based architecture ensures that developers can easily manage emails, domains, and audience data through a consistent and type-safe interface. By utilizing the built-in transporter and signature verification tools, applications maintain secure and reliable communication with the Resend infrastructure.