Download the PHP package vercy/sendbyte-laravel without Composer

SendByte Laravel by Vercy

Laravel integration for the SendByte Africa transactional email API. Gives you three things:

1. A Mail driver — keep using Mail::to(...)->send(...) and Mailables, backed by SendByte.
2. An API client / Facade — call SendByte directly for anything the Mail layer doesn't cover.
3. Webhook handling — a route, signature verification, and Laravel events for SendByte's delivery lifecycle.

This package talks to SendByte's REST API directly over Laravel's HTTP client — it doesn't depend on the official sendbyte/sendbyte-php SDK, so there's nothing extra to configure beyond your API key.

Requirements

• PHP ^8.1
• Laravel 10.x, 11.x, 12.x, or 13.x

Contents

• Installation
• Sending mail via the Mail driver
• Sending without a Mailable
• Using the API client directly
• Webhooks
• Verifying your setup
• Common errors
• Testing
• License

Installation

The service provider and Sendbyte facade are auto-discovered. Publish the config if you want to tweak it:

Add your key (from app.sendbyte.africa) to .env:

Use an sk_test_... key while you're getting set up — it doesn't require a verified sending domain. Switch to an sk_live_... key once your domain is verified and you're sending real traffic.

Sending mail via the Mail driver

Add a mailer in config/mail.php:

Point default mail at it (or use ->mailer('sendbyte') per-send):

Then send like normal, using a Mailable:

Attachments, CC/BCC, reply-to, and HTML/text bodies are all translated to SendByte's payload shape automatically.

Sending without a Mailable

For quick or one-off sends, Mail::raw() and Mail::html() work too:

If MAIL_MAILER=sendbyte is already set in .env, you can drop mailer('sendbyte') and just call Mail::raw(...) / Mail::html(...) directly.

Using the API client directly

For anything outside the Mail layer — checking delivery status, idempotent retries, listing sends:

Failures throw Sendbyte\Laravel\Exceptions\SendbyteException:

You can also resolve Sendbyte\Laravel\Sendbyte from the container instead of using the facade, e.g. for constructor injection.

Webhooks

The package registers POST /webhooks/sendbyte automatically, guarded by HMAC signature verification. Set your signing secret (shown when you create the webhook endpoint in the SendByte dashboard):

Then listen for whichever lifecycle stages you care about in EventServiceProvider:

Every lifecycle event (EmailQueued, EmailSent, EmailDelivered, EmailDeliveryDelayed, EmailBounced, EmailComplained, EmailOpened, EmailClicked, EmailFailed) exposes $event->data (the event's data object), $event->payload (the full raw payload), $event->emailId(), and $event->to().

Webhook header names

Signature verification uses HMAC-SHA256 over the raw request body, matching how SendByte describes its webhooks (signed, replayable, 9 lifecycle events). Header names are configurable in config/sendbyte.php rather than hardcoded, since providers vary here — confirm the exact names against a real test event before relying on this in production:

1. Create a webhook endpoint in the SendByte dashboard and trigger a test event.
2. Check the actual header name(s) on the incoming request.
3. Update signature_header / timestamp_header in config/sendbyte.php (or the matching .env vars) to match — no code changes needed.

If SendByte signs a timestamp.body string rather than just the raw body, that's already handled as long as timestamp_header is set correctly. If they don't send a timestamp at all, set SENDBYTE_WEBHOOK_TIMESTAMP_HEADER=null to skip that check.

Customizing the route

Set enabled to false if you'd rather register the route and controller yourself.

Verifying your setup

Quick smoke test after install — run php artisan tinker:

A successful call returns an array containing an id. Anything else — an exception, a validation error — means something in your key, domain verification, or config needs attention before you wire it into real code.

Common errors

"Domain not verified" / send rejected — the address in from must be on a domain you've verified in your SendByte dashboard. sk_test_... keys are more permissive; sk_live_... keys enforce this strictly.

Composer can't resolve a version — if you're installing straight off a dev-main branch with no tagged release, either require it explicitly (composer require vercy/sendbyte-laravel:dev-main) or, better, use a tagged version (^1.0) once one's published — dev branches can introduce breaking changes without a version bump.

SendbyteException with no useful message — call $e->errorPayload() to see SendByte's full raw error response; the top-level message is a summary and may omit field-level detail.

Testing

The test suite uses Orchestra Testbench and fakes HTTP calls, so no live API key is needed.

License

MIT.