relaywarden/php-sdk

Official PHP SDK for RelayWarden API

v1.0.0 2026-01-19 15:02 UTC

Requires

• php: ^8.3
• guzzlehttp/guzzle: ^7.10

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.0

MIT

README

Official PHP SDK for the RelayWarden API v1.

Installation

composer require relaywarden/php-sdk

Quick Start

<?php

use RelayWarden\Client;

// Initialize the client
$client = new Client(
    'https://api.relaywarden.eu/api/v1',
    'your-api-token'
);

// Set project ID for project-scoped operations
$client->setProjectId('your-project-id');

// Send a message
$message = $client->messages()->send([
    'from' => [
        'email' => '[e-mail]',
        'name' => 'Acme Corp'
    ],
    'to' => [
        ['email' => '[e-mail]']
    ],
    'subject' => 'Welcome!',
    'html' => '<h1>Welcome!</h1>',
    'text' => 'Welcome!'
]);

echo "Message ID: " . $message['data']['message_id'];

Authentication

The SDK uses Bearer token authentication. Pass your API token when creating the client:

$client = new Client(
    'https://api.relaywarden.eu/api/v1',
    'your-api-token'
);

Resources

Identity

// Get current user/service account info
$me = $client->identity()->me();

// List teams
$teams = $client->identity()->teams();

Projects

// List projects
$projects = $client->projects()->list(['environment' => 'production']);

// Create project
$project = $client->projects()->create([
    'name' => 'Production',
    'environment' => 'production'
]);

// Get project
$project = $client->projects()->get('project-id');

// Update project
$project = $client->projects()->update('project-id', [
    'name' => 'Updated Name'
]);

// Delete project
$client->projects()->delete('project-id');

Messages

// Send message with idempotency key
$message = $client->messages()->send([
    'from' => ['email' => '[e-mail]'],
    'to' => [['email' => '[e-mail]']],
    'subject' => 'Hello',
    'html' => '<h1>Hello</h1>'
], 'unique-idempotency-key');

// List messages
$messages = $client->messages()->list([
    'status' => 'delivered',
    'per_page' => 25
]);

// Get message
$message = $client->messages()->get('message-id');

// Get message timeline
$timeline = $client->messages()->getTimeline('message-id');

// Cancel message
$client->messages()->cancel('message-id');

// Resend message
$client->messages()->resend('message-id');

Templates

// Create template
$template = $client->templates()->create([
    'name' => 'Welcome Email',
    'subject' => 'Welcome {{ $name }}!',
    'html_body' => '<h1>Welcome {{ $name }}!</h1>',
    'text_body' => 'Welcome {{ $name }}!'
]);

// Render template
$rendered = $client->templates()->render('template-id', [
    'data' => ['name' => 'John']
]);

// Test send
$client->templates()->testSend('template-id', [
    'to' => '[e-mail]',
    'data' => ['name' => 'John']
]);

Domains

// Create domain
$domain = $client->domains()->create([
    'domain' => 'mail.example.com'
]);

// Verify domain
$result = $client->domains()->verify('domain-id');

// Get DNS records
$records = $client->domains()->getDnsRecords('domain-id');

// Rotate DKIM keys
$client->domains()->rotateDkim('domain-id');

Error Handling

The SDK throws specific exception types for different error scenarios:

use RelayWarden\Exceptions\AuthenticationException;
use RelayWarden\Exceptions\RateLimitException;
use RelayWarden\Exceptions\ValidationException;
use RelayWarden\Exceptions\ApiException;

try {
    $message = $client->messages()->send([...]);
} catch (AuthenticationException $e) {
    // 401 - Invalid or missing token
    echo "Authentication failed: " . $e->getMessage();
} catch (ValidationException $e) {
    // 422 - Validation errors
    echo "Validation failed: " . $e->getMessage();
    foreach ($e->getErrorDetails() as $detail) {
        echo $detail['field'] . ": " . $detail['message'];
    }
} catch (RateLimitException $e) {
    // 429 - Rate limit exceeded
    echo "Rate limit exceeded. Retry after: " . $e->getRetryAfter() . " seconds";
} catch (ApiException $e) {
    // Other API errors
    echo "API Error: " . $e->getMessage();
    echo "Request ID: " . $e->getRequestId();
}

Pagination

List endpoints return paginated responses:

$response = $client->messages()->list();

// Access pagination metadata
$currentPage = $response['meta']['current_page'];
$total = $response['meta']['total'];
$lastPage = $response['meta']['last_page'];

// Access data
$messages = $response['data'];

Rate Limiting

The SDK automatically handles rate limits with exponential backoff. Rate limit information is available in the exception:

try {
    $client->messages()->send([...]);
} catch (RateLimitException $e) {
    $retryAfter = $e->getRetryAfter(); // Seconds to wait
    // SDK will automatically retry, but you can also handle manually
}

Configuration

$client = new Client(
    'https://api.relaywarden.eu/api/v1',
    'your-token',
    [
        'max_retries' => 3,
        'timeout' => 30
    ]
);

Testing

composer test
composer test-coverage

License

MIT