PHPackages                             teracrafts/huefy-sdk-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Templating & Views](/categories/templating)
4. /
5. teracrafts/huefy-sdk-php

ActiveLibrary[Templating & Views](/categories/templating)

teracrafts/huefy-sdk-php
========================

Huefy - PHP SDK

v1.0.1(1y ago)00MITPHPPHP >=8.0

Since Jul 2Pushed 1mo agoCompare

[ Source](https://github.com/teracrafts/huefy-sdk-php)[ Packagist](https://packagist.org/packages/teracrafts/huefy-sdk-php)[ Docs](https://github.com/teracrafts/huefy-sdk)[ RSS](/packages/teracrafts-huefy-sdk-php/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (9)Versions (4)Used By (0)

teracrafts/huefy-sdk
====================

[](#teracraftshuefy-sdk)

Official PHP SDK for [Huefy](https://huefy.dev) — transactional email delivery made simple.

Installation
------------

[](#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
------------

[](#requirements)

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

Quick Start
-----------

[](#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
------------

[](#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
-----------------------

[](#configuration-reference)

ParameterDefaultDescription`apiKey`—**Required.** Must have prefix `sdk_`, `srv_`, or `cli_``baseUrl``https://api.huefy.dev/api/v1/sdk`Override the API base URL`timeout``30.0`Request timeout in seconds`retryConfig->maxAttempts``3`Total attempts including the first`retryConfig->baseDelay``0.5`Exponential backoff base delay (seconds)`retryConfig->maxDelay``10.0`Maximum backoff delay (seconds)`retryConfig->jitter``0.2`Random jitter factor (0–1)`circuitBreakerConfig->failureThreshold``5`Consecutive failures before circuit opens`circuitBreakerConfig->resetTimeout``30.0`Seconds before half-open probe`logger``null`PSR-3 logger instance`secondaryApiKey``null`Backup key used during key rotation`enableRequestSigning``false`Enable HMAC-SHA256 request signing`onRateLimitUpdate``null`Callable fired on rate-limit header changesBulk Email
----------

[](#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
--------------

[](#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

[](#error-code-reference)

ExceptionCodeMeaning`HuefyInitException`1001Client failed to initialise`HuefyAuthException`1102API key rejected`HuefyNetworkException`1201Upstream request failed`HuefyCircuitOpenException`1301Circuit breaker tripped`HuefyRateLimitException`2003Rate limit exceeded`HuefyTemplateMissingException`2005Template key not foundHealth Check
------------

[](#health-check)

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

Local Development
-----------------

[](#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
-----------------------

[](#namespace-compatibility)

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

Developer Guide
---------------

[](#developer-guide)

Full documentation, advanced patterns, and provider configuration are in the [PHP Developer Guide](../../docs/spec/guides/php.guide.md).

License
-------

[](#license)

MIT

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance72

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

3

Last Release

365d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/177446929?v=4)[TeraCrafts](/maintainers/teracrafts)[@teracrafts](https://github.com/teracrafts)

---

Top Contributors

[![kynx-iv](https://avatars.githubusercontent.com/u/20340730?v=4)](https://github.com/kynx-iv "kynx-iv (41 commits)")

---

Tags

apisdkemailtemplatetransactionalhuefy

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/teracrafts-huefy-sdk-php/health.svg)

```
[![Health](https://phpackages.com/badges/teracrafts-huefy-sdk-php/health.svg)](https://phpackages.com/packages/teracrafts-huefy-sdk-php)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.3k543.5M2.6k](/packages/aws-aws-sdk-php)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[nutgram/nutgram

The Telegram bot library that doesn't drive you nuts

737290.3k8](/packages/nutgram-nutgram)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

273.0k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)