README

Official PHP SDK for Huefy — transactional email delivery made simple.

Installation

composer require teracrafts/huefy-sdk

To use a custom PSR-18 HTTP client instead of the bundled Guzzle adapter:

composer require teracrafts/huefy-sdk psr/http-client your-psr18-client

Requirements

• PHP 8.1+
• guzzlehttp/guzzle (installed automatically, or bring your own PSR-18 client)

Quick Start

use Teracrafts\Huefy\HuefyEmailClient;
use Teracrafts\Huefy\Models\SendEmailRequest;
use Teracrafts\Huefy\Models\SendEmailRecipient;

$client = new HuefyEmailClient([
    'apiKey' => 'sdk_your_api_key',
]);

$response = $client->sendEmail(new SendEmailRequest(
    templateKey: 'welcome-email',
    data: ['firstName' => 'Alice', 'trialDays' => 14],
    recipient: new SendEmailRecipient(
        email: 'alice@example.com',
        type: 'cc',
        data: ['locale' => 'en'],
    ),
));

echo 'Email ID: ' . $response->data->emailId . PHP_EOL;

Key Features

• PSR-18 compatible — swap in any PSR-18 HTTP client
• PSR-3 logger — plug in any PSR-3 logger (Monolog, etc.)
• PHP 8.1 enums — EmailProvider is a native enum
• Named arguments — all constructors support PHP 8 named argument syntax
• Retry with exponential backoff — configurable attempts, base delay, ceiling, and jitter
• Circuit breaker — opens after 5 consecutive failures, probes after 30 s
• HMAC-SHA256 signing — optional request signing for additional integrity verification
• Key rotation — primary + secondary API key with seamless failover
• Rate limit callbacks — onRateLimitUpdate fires whenever rate-limit headers change
• PII detection — warns when template variables contain sensitive field patterns

Configuration Reference

Bulk Email

use Teracrafts\Huefy\Models\BulkRecipient;
use Teracrafts\Huefy\Models\SendBulkEmailsRequest;

$bulk = $client->sendBulkEmails(new SendBulkEmailsRequest(
    templateKey: 'promo',
    recipients: [
        new BulkRecipient(email: 'bob@example.com'),
        new BulkRecipient(email: 'carol@example.com'),
    ]
));

echo "Sent: {$bulk->data->successCount}, Failed: {$bulk->data->failureCount}" . PHP_EOL;

Error Handling

use Teracrafts\Huefy\Errors\ErrorCode;
use Teracrafts\Huefy\Errors\HuefyException;

try {
    $response = $client->sendEmail($request);
    echo 'Delivered: ' . $response->data->emailId . PHP_EOL;
} catch (HuefyException $e) {
    if ($e->getErrorCode() === ErrorCode::AUTHENTICATION_ERROR) {
        echo 'Invalid API key' . PHP_EOL;
    } elseif ($e->getErrorCode() === ErrorCode::RATE_LIMIT_ERROR) {
        echo 'Rate limited' . PHP_EOL;
    } elseif ($e->getErrorCode() === ErrorCode::CIRCUIT_BREAKER_OPEN) {
        echo 'Circuit open — service unavailable, backing off' . PHP_EOL;
    } else {
        echo "Huefy error [{$e->getErrorCode()}]: {$e->getMessage()}" . PHP_EOL;
    }
}

Error Code Reference

Health Check

$health = $client->healthCheck();
if (($health['data']['status'] ?? null) !== 'healthy') {
    error_log('Huefy degraded: ' . ($health['data']['status'] ?? 'unknown'));
}

Local Development

The PHP SDK does not resolve HUEFY_MODE automatically. To match the local Caddy setup, set baseUrl to https://api.huefy.on/api/v1/sdk. To bypass Caddy and hit the raw app port directly, use http://localhost:8080/api/v1/sdk instead:

$client = new HuefyEmailClient([
    'apiKey' => 'sdk_local_key',
    'baseUrl' => 'https://api.huefy.on/api/v1/sdk',
]);

Namespace Compatibility

The canonical PHP namespace is Teracrafts\Huefy\.... Existing Huefy\... references remain supported through the bundled compatibility aliases.

Developer Guide

Full documentation, advanced patterns, and provider configuration are in the PHP Developer Guide.

License

MIT