PHPackages                             teracrafts/huefy-laravel - 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. [Mail & Notifications](/categories/mail)
4. /
5. teracrafts/huefy-laravel

ActiveLibrary[Mail & Notifications](/categories/mail)

teracrafts/huefy-laravel
========================

Laravel package for Huefy - App Mail Templates with seamless integration, service providers, and artisan commands

v2.1.1(5mo ago)00MITPHPPHP ^8.1

Since Jul 3Pushed 5mo agoCompare

[ Source](https://github.com/teracrafts/huefy-sdk-laravel)[ Packagist](https://packagist.org/packages/teracrafts/huefy-laravel)[ Docs](https://www.huefy.dev)[ RSS](/packages/teracrafts-huefy-laravel/feed)WikiDiscussions main Synced 1mo ago

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

Huefy Laravel Package
=====================

[](#huefy-laravel-package)

The official Laravel package for Huefy - App Mail Templates. Provides seamless integration with Laravel's mail and notification systems, along with artisan commands and service providers for easy template-based email management.

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

[](#installation)

Install the package via Composer:

```
composer require teracrafts/huefy-sdk-laravel
```

### Laravel Auto-Discovery

[](#laravel-auto-discovery)

The package uses Laravel's auto-discovery feature, so the service provider and facade are registered automatically.

### Manual Registration (if needed)

[](#manual-registration-if-needed)

If auto-discovery is disabled, add the service provider to your `config/app.php`:

```
'providers' => [
    // ...
    TeraCrafts\HuefyLaravel\HuefyServiceProvider::class,
],

'aliases' => [
    // ...
    'Huefy' => TeraCrafts\HuefyLaravel\Facades\Huefy::class,
],
```

### Publish Configuration

[](#publish-configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag=huefy-config
```

Configuration
-------------

[](#configuration)

Add your Huefy API key to your `.env` file:

```
HUEFY_API_KEY=your-huefy-api-key
HUEFY_DEFAULT_PROVIDER=ses
HUEFY_TIMEOUT=30
HUEFY_RETRY_ATTEMPTS=3
```

Basic Usage
-----------

[](#basic-usage)

### Using the Facade

[](#using-the-facade)

```
use TeraCrafts\HuefyLaravel\Facades\Huefy;

// Send a single email
$response = Huefy::sendEmail('welcome-email', [
    'name' => 'John Doe',
    'company' => 'Acme Corp'
], 'john@example.com');

// Send with specific provider
$response = Huefy::sendEmail('newsletter', [
    'name' => 'Jane Smith',
    'unsubscribe_url' => 'https://example.com/unsubscribe'
], 'jane@example.com', 'sendgrid');

// Send bulk emails
$emails = [
    [
        'template_key' => 'welcome-email',
        'data' => ['name' => 'John'],
        'recipient' => 'john@example.com'
    ],
    [
        'template_key' => 'welcome-email',
        'data' => ['name' => 'Jane'],
        'recipient' => 'jane@example.com',
        'provider' => 'mailgun'
    ]
];

$results = Huefy::sendBulkEmails($emails);
```

### Using Dependency Injection

[](#using-dependency-injection)

```
use TeraCrafts\HuefyLaravel\HuefyClient;

class EmailService
{
    public function __construct(private HuefyClient $huefy)
    {
    }

    public function sendWelcomeEmail(User $user): void
    {
        $this->huefy->sendEmail('welcome-email', [
            'name' => $user->name,
            'email' => $user->email,
            'login_url' => route('login')
        ], $user->email);
    }
}
```

Laravel Mail Integration
------------------------

[](#laravel-mail-integration)

Configure Huefy as a mail driver in `config/mail.php`:

```
'mailers' => [
    'huefy' => [
        'transport' => 'huefy',
        'template_key' => env('HUEFY_DEFAULT_TEMPLATE_KEY'),
        'provider' => env('HUEFY_DEFAULT_PROVIDER', 'ses'),
    ],
],
```

### Using with Mailables

[](#using-with-mailables)

```
use Illuminate\Mail\Mailable;
use Illuminate\Support\Facades\Mail;

class WelcomeMail extends Mailable
{
    public function __construct(
        public User $user
    ) {}

    public function build()
    {
        return $this->view('emails.welcome')
                    ->with([
                        'name' => $this->user->name,
                        'login_url' => route('login')
                    ])
                    ->subject('Welcome to our platform!');
    }

    public function envelope()
    {
        return new Envelope(
            subject: 'Welcome!',
            using: [
                fn (Message $message) => $message
                    ->getHeaders()
                    ->addTextHeader('X-Template-Key', 'welcome-email')
                    ->addTextHeader('X-Template-Data', json_encode([
                        'name' => $this->user->name,
                        'login_url' => route('login')
                    ]))
                    ->addTextHeader('X-Email-Provider', 'sendgrid')
            ]
        );
    }
}

// Send the email
Mail::to('user@example.com')->send(new WelcomeMail($user));
```

Laravel Notification Integration
--------------------------------

[](#laravel-notification-integration)

### Creating a Huefy Notification

[](#creating-a-huefy-notification)

```
use Illuminate\Notifications\Notification;
use TeraCrafts\HuefyLaravel\Notifications\HuefyChannel;
use TeraCrafts\HuefyLaravel\Notifications\HuefyMessage;

class WelcomeNotification extends Notification
{
    public function __construct(
        private User $user
    ) {}

    public function via($notifiable): array
    {
        return [HuefyChannel::class];
    }

    public function toHuefy($notifiable): HuefyMessage
    {
        return HuefyMessage::create('welcome-email')
            ->data([
                'name' => $this->user->name,
                'email' => $this->user->email,
                'activation_url' => route('activation', $this->user->id)
            ])
            ->provider('sendgrid');
    }
}

// Send the notification
$user->notify(new WelcomeNotification($user));
```

### Using Route Notification

[](#using-route-notification)

```
// In your User model
public function routeNotificationForHuefy()
{
    return $this->email;
}

// Or return an array for more complex routing
public function routeNotificationForHuefy()
{
    return [
        'email' => $this->email,
        'name' => $this->name
    ];
}
```

Artisan Commands
----------------

[](#artisan-commands)

The package provides several artisan commands for managing emails:

### Health Check

[](#health-check)

Check the Huefy API health status:

```
php artisan huefy:health
```

### Send Email

[](#send-email)

Send an email using a template:

```
# Basic usage
php artisan huefy:send welcome-email user@example.com

# With inline data
php artisan huefy:send welcome-email user@example.com --data='{"name":"John","company":"Acme"}'

# With data from file
php artisan huefy:send welcome-email user@example.com --file=data.json

# With specific provider
php artisan huefy:send newsletter user@example.com --provider=sendgrid --data='{"name":"Jane"}'
```

### Validate Template

[](#validate-template)

Validate a template with test data:

```
# Interactive validation
php artisan huefy:validate welcome-email

# With inline data
php artisan huefy:validate welcome-email --data='{"name":"Test User"}'

# With data from file
php artisan huefy:validate welcome-email --file=test-data.json
```

### List Providers

[](#list-providers)

List available email providers:

```
php artisan huefy:providers
```

Advanced Usage
--------------

[](#advanced-usage)

### Custom Mail Transport

[](#custom-mail-transport)

Create a custom mailable that uses Huefy transport:

```
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Mail\Mailables\Headers;

class CustomHuefyMail extends Mailable
{
    public function __construct(
        private string $templateKey,
        private array $templateData,
        private ?string $provider = null
    ) {}

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Custom Huefy Email',
        );
    }

    public function content(): Content
    {
        return new Content(
            text: 'emails.empty', // Dummy view since we're using templates
        );
    }

    public function headers(): Headers
    {
        return new Headers(
            text: [
                'X-Template-Key' => $this->templateKey,
                'X-Template-Data' => json_encode($this->templateData),
                'X-Email-Provider' => $this->provider ?: config('huefy.default_provider'),
            ],
        );
    }
}
```

### Bulk Email Processing

[](#bulk-email-processing)

```
use TeraCrafts\HuefyLaravel\Facades\Huefy;

class NewsletterService
{
    public function sendNewsletter(Collection $subscribers, string $templateKey): array
    {
        $emails = $subscribers->map(function ($subscriber) use ($templateKey) {
            return [
                'template_key' => $templateKey,
                'data' => [
                    'name' => $subscriber->name,
                    'preferences_url' => route('preferences', $subscriber->id),
                    'unsubscribe_url' => route('unsubscribe', $subscriber->token),
                ],
                'recipient' => $subscriber->email,
                'provider' => $subscriber->preferred_provider ?? 'ses',
            ];
        })->toArray();

        return Huefy::sendBulkEmails($emails);
    }
}
```

### Error Handling

[](#error-handling)

```
use TeraCrafts\HuefyLaravel\Exceptions\HuefyException;
use TeraCrafts\HuefyLaravel\Exceptions\TemplateNotFoundException;
use TeraCrafts\HuefyLaravel\Exceptions\ValidationException;
use TeraCrafts\HuefyLaravel\Facades\Huefy;

try {
    Huefy::sendEmail('welcome-email', $data, $email);
} catch (TemplateNotFoundException $e) {
    Log::error('Template not found', [
        'template' => $e->getTemplateKey(),
        'message' => $e->getMessage()
    ]);
} catch (ValidationException $e) {
    Log::error('Validation failed', [
        'errors' => $e->getErrors(),
        'message' => $e->getMessage()
    ]);
} catch (HuefyException $e) {
    Log::error('Huefy API error', [
        'code' => $e->getCode(),
        'message' => $e->getMessage(),
        'context' => $e->getContext()
    ]);
}
```

### Queue Integration

[](#queue-integration)

```
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use TeraCrafts\HuefyLaravel\Facades\Huefy;

class SendHuefyEmailJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(
        private string $templateKey,
        private array $data,
        private string $recipient,
        private ?string $provider = null
    ) {}

    public function handle(): void
    {
        Huefy::sendEmail(
            $this->templateKey,
            $this->data,
            $this->recipient,
            $this->provider
        );
    }
}

// Dispatch the job
SendHuefyEmailJob::dispatch('welcome-email', $data, $email)->onQueue('emails');
```

Configuration Reference
-----------------------

[](#configuration-reference)

The `config/huefy.php` file contains all configuration options:

```
return [
    // API Configuration
    'api_key' => env('HUEFY_API_KEY'),
    'timeout' => env('HUEFY_TIMEOUT', 30),
    'retry_attempts' => env('HUEFY_RETRY_ATTEMPTS', 3),
    'default_provider' => env('HUEFY_DEFAULT_PROVIDER', 'ses'),

    // Mail Integration
    'mail' => [
        'default_template_key' => env('HUEFY_DEFAULT_TEMPLATE_KEY'),
        'auto_extract_data' => env('HUEFY_AUTO_EXTRACT_DATA', true),
    ],

    // Notification Integration
    'notifications' => [
        'default_template_key' => env('HUEFY_NOTIFICATION_TEMPLATE_KEY'),
        'include_notification_data' => env('HUEFY_INCLUDE_NOTIFICATION_DATA', true),
    ],

    // Logging
    'logging' => [
        'log_successful_sends' => env('HUEFY_LOG_SUCCESS', false),
        'log_failed_sends' => env('HUEFY_LOG_FAILURES', true),
        'channel' => env('HUEFY_LOG_CHANNEL', 'default'),
    ],

    // Rate Limiting
    'rate_limiting' => [
        'enabled' => env('HUEFY_RATE_LIMITING_ENABLED', true),
        'requests_per_minute' => env('HUEFY_REQUESTS_PER_MINUTE', 60),
    ],
];
```

Testing
-------

[](#testing)

```
use TeraCrafts\HuefyLaravel\Facades\Huefy;

// Mock the Huefy facade for testing
public function test_sends_welcome_email()
{
    Huefy::shouldReceive('sendEmail')
        ->once()
        ->with('welcome-email', ['name' => 'John'], 'john@example.com', null)
        ->andReturn(['message_id' => 'test-123', 'status' => 'sent']);

    $result = $this->emailService->sendWelcome('john@example.com', 'John');

    $this->assertTrue($result);
}
```

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 9.0, 10.0, or 11.0
- Guzzle HTTP client 7.0+

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

Support
-------

[](#support)

- **Documentation**:
- **Issues**: [GitHub Issues](https://github.com/teracrafts/huefy-sdk-laravel/issues)
- **Email**:

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance70

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity47

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 ~70 days

Total

3

Last Release

174d ago

Major Versions

v1.0.1 → v2.1.12025-11-20

### Community

Maintainers

![](https://www.gravatar.com/avatar/0d882655d13f2fd63d90d3a65b410ce2e940581d70ceccedb683fa03df5646b2?d=identicon)[teracrafts](/maintainers/teracrafts)

---

Top Contributors

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

---

Tags

apilaravelmailemailnotificationssendgridtemplatesmailgunmailchimpseshuefy

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[s-ichikawa/laravel-sendgrid-driver

This library adds a 'sendgrid' mail driver to Laravel.

4139.3M1](/packages/s-ichikawa-laravel-sendgrid-driver)[propaganistas/laravel-disposable-email

Disposable email validator

5762.6M6](/packages/propaganistas-laravel-disposable-email)[laravel-notification-channels/discord

Laravel notification driver for Discord.

2371.3M11](/packages/laravel-notification-channels-discord)[coconutcraig/laravel-postmark

Laravel package for sending mail via the Postmark API

2152.9M1](/packages/coconutcraig-laravel-postmark)[erag/laravel-disposable-email

A Laravel package to detect and block disposable email addresses.

226102.4k](/packages/erag-laravel-disposable-email)[sunaoka/laravel-ses-template-driver

Amazon SES template mail driver for Laravel.

1088.0k](/packages/sunaoka-laravel-ses-template-driver)

PHPackages © 2026

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