webgrade-cloud/sendmetrics-laravel

A strict Laravel SDK for the SendMetrics transactional email API.

dev-main 2026-05-26 11:56 UTC

Requires

• php: ^8.2
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/mail: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0

Requires (Dev)

• laravel/pint: ^1.27
• orchestra/testbench: ^9.0|^10.0|^11.0
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11.5|^12.5

MIT

• Webgrade Cloud

• smtp
• laravel
• transactional-email
• email-api
• sendmetrics

README

SendMetrics Laravel SDK

SendMetrics is transactional email infrastructure for teams that need clean delivery primitives, strict API contracts, and operational visibility without owning SMTP complexity in every application.

This package is the official Laravel SDK for the SendMetrics Email API. It provides a first-class Laravel mail driver, a typed API client for advanced use cases, auto-discovery, publishable configuration, strict payload validation, and predictable exception handling.

Requirements

• PHP 8.2+
• Laravel 11, 12, or 13

Installation

composer require webgrade-cloud/sendmetrics-laravel

Laravel auto-discovers the service provider and facade.

Publish the configuration file:

php artisan vendor:publish --tag=sendmetrics-config

Add your credentials:

MAIL_MAILER=sendmetrics
SENDMETRICS_API_KEY=
SENDMETRICS_API_URL=https://sendmetrics.eu/api

Configuration

The package publishes config/sendmetrics.php:

return [
    'api_key' => env('SENDMETRICS_API_KEY'),
    'api_url' => env('SENDMETRICS_API_URL', 'https://sendmetrics.eu/api'),
    'timeout' => (int) env('SENDMETRICS_TIMEOUT', 10),
    'connect_timeout' => (int) env('SENDMETRICS_CONNECT_TIMEOUT', 5),
];

The package registers the sendmetrics mailer automatically. If you prefer to keep every mailer explicitly listed in config/mail.php, add:

'default' => env('MAIL_MAILER', 'sendmetrics'),

'mailers' => [
    'sendmetrics' => [
        'transport' => 'sendmetrics',
    ],
],

The SDK is intentionally strict. Payload keys must match the SendMetrics API contract exactly.

Laravel Mail

Set SendMetrics as your default mailer:

MAIL_MAILER=sendmetrics
SENDMETRICS_API_KEY=sm_xxx
SENDMETRICS_API_URL=https://sendmetrics.eu/api

Then use Laravel Mail normally:

use Illuminate\Support\Facades\Mail;

Mail::to('[e-mail]')->send(new WelcomeCustomer);

Mailables, Markdown mailables, Mail::send, Mail::raw, global mail.from, reply-to, CC, BCC, custom headers, tags, metadata, attachments, and queued mailables are sent through the SendMetrics API.

Tags and Metadata

Use Laravel's native mailable envelope API:

use Illuminate\Mail\Mailables\Envelope;

public function envelope(): Envelope
{
    return new Envelope(
        subject: 'Invoice paid',
        tags: ['billing'],
        metadata: [
            'account_id' => $this->accountId,
        ],
    );
}

Attachments

Laravel attachment APIs work as usual:

use Illuminate\Mail\Mailables\Attachment;

public function attachments(): array
{
    return [
        Attachment::fromPath(storage_path('invoices/invoice.pdf'))
            ->as('invoice.pdf')
            ->withMime('application/pdf'),
    ];
}

Raw data attachments are supported too:

Attachment::fromData(fn () => $this->pdf, 'invoice.pdf')
    ->withMime('application/pdf');

Notifications

Laravel's built-in mail notification channel uses the configured mailer, so no SendMetrics-specific notification code is required:

use Illuminate\Support\Facades\Notification;

Notification::send($users, new InvoicePaidNotification);

Inside the notification:

use Illuminate\Notifications\Messages\MailMessage;

public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->subject('Invoice paid')
        ->line('Your invoice has been paid.');
}

Queues

Queued mailables and queued notifications continue to use Laravel's queue system:

Mail::to('[e-mail]')->queue(new WelcomeCustomer);

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;

final class InvoicePaidNotification extends Notification implements ShouldQueue
{
    // ...
}

Retries, backoff, failed jobs, and queue workers stay in Laravel, while delivery goes through SendMetrics.

Advanced API Client

Most applications should use Laravel Mail. The direct client remains available for product-specific flows where you want to bypass Laravel's mail abstractions.

Use dependency injection when you want explicit, testable code:

use WebgradeCloud\SendMetrics\Data\EmailMessage;
use WebgradeCloud\SendMetrics\SendMetricsClient;

final class SendWelcomeEmail
{
    public function __construct(
        private readonly SendMetricsClient $sendMetrics,
    ) {}

    public function handle(string $email): void
    {
        $response = $this->sendMetrics->sendEmail(new EmailMessage(
            fromEmail: '[e-mail]',
            fromName: 'Example App',
            toEmail: $email,
            subject: 'Welcome to Example App',
            htmlBody: '<p>Your account is ready.</p>',
            textBody: 'Your account is ready.',
        ));

        $response->messageId;
    }
}

You may also send an exact API payload:

use WebgradeCloud\SendMetrics\Facades\SendMetrics;

$response = SendMetrics::sendEmail([
    'from' => [
        'email' => '[e-mail]',
        'name' => 'Billing',
    ],
    'to' => [
        [
            'email' => '[e-mail]',
            'name' => null,
        ],
    ],
    'subject' => 'Invoice paid',
    'html_body' => '<p>Your invoice was paid.</p>',
    'text_body' => 'Your invoice was paid.',
    'headers' => [
        'X-Billing-Event' => 'invoice-paid',
    ],
    'tags' => ['billing'],
    'metadata' => [
        'invoice_id' => 'inv_123',
    ],
    'attachments' => [],
]);

Accepted keys:

• from
• to — exactly one primary recipient
• cc
• bcc
• reply_to
• subject
• html_body
• text_body
• headers
• tags
• metadata
• attachments

Error Handling

When using Laravel Mail, SendMetrics API errors are surfaced as Symfony mail transport exceptions:

use Symfony\Component\Mailer\Exception\TransportExceptionInterface;

try {
    Mail::to('[e-mail]')->send(new WelcomeCustomer);
} catch (TransportExceptionInterface $exception) {
    report($exception);
}

The transport maps authentication errors, validation failures, rate limits, and server errors to clear mail transport exception messages. Debug details from the SendMetrics API response are attached to the Symfony exception when available.

When using the advanced API client, catch the SDK exceptions directly:

use WebgradeCloud\SendMetrics\Exceptions\ApiException;
use WebgradeCloud\SendMetrics\Exceptions\ConfigurationException;
use WebgradeCloud\SendMetrics\Exceptions\InvalidPayloadException;
use WebgradeCloud\SendMetrics\Exceptions\TransportException;

try {
    $sendMetrics->sendEmail($message);
} catch (InvalidPayloadException $exception) {
    report($exception);
} catch (ConfigurationException $exception) {
    report($exception);
} catch (ApiException $exception) {
    $exception->statusCode;
    $exception->responseBody;
} catch (TransportException $exception) {
    report($exception);
}

ApiException exposes the HTTP status code and decoded response body, including rate-limit and quota responses returned by the SendMetrics API.

Roadmap

• Template sending
• Batch sending
• Webhook helpers
• Inbound parsing
• Campaign APIs

The package intentionally does not include inbound parsing, a templates engine, batch campaigns, or a webhook server yet.

Security

Report security issues through GitHub Security Advisories or by contacting [e-mail].

Credits

SendMetrics is built by Webgrade Cloud.

License

The MIT License (MIT). See LICENSE for more information.