Laravel SDK

The jetemail/jetemail-laravel package is the official Laravel SDK for JetEmail transactional email (MIT license, PHP 8.1+, Laravel 10, 11 or 12, Guzzle 7). Create a transactional API key in the dashboard: Outbound → Keys → Add API key. Use that key with the SDK.

Not using Laravel? Use the framework-agnostic PHP SDK instead.

Installation

composer require jetemail/jetemail-laravel

Package on Packagist: jetemail/jetemail-laravel. Source on GitHub: jetemail/jetemail-laravel. The service provider (JetEmail\Laravel\JetEmailServiceProvider) and the JetEmail facade alias are auto-discovered by Laravel.

Configuration

Add your transactional API key to your .env file:

JETEMAIL_API_KEY=your-api-key

Optionally publish the config file to config/jetemail.php:

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

All settings and their environment variables:

Config key	Env var	Default
`api_key`	`JETEMAIL_API_KEY`	—
`base_url`	`JETEMAIL_BASE_URL`	`https://api.jetemail.com`
`webhook.secret`	`JETEMAIL_WEBHOOK_SECRET`	—
`webhook.tolerance`	`JETEMAIL_WEBHOOK_TOLERANCE`	`300`
`path`	`JETEMAIL_PATH`	`jetemail`
`domain`	`JETEMAIL_DOMAIN`	—

If jetemail.api_key is empty the SDK falls back to services.jetemail.key in config/services.php. If neither is set, resolving the client throws JetEmail\Laravel\Exceptions\ApiKeyIsMissing.

Laravel Mail Integration

Use JetEmail as a Laravel mail driver. Add the mailer to your config/mail.php:

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

Set it as your default mailer in .env:

MAIL_MAILER=jetemail

Then use Laravel’s standard Mail API:

use Illuminate\Support\Facades\Mail;

Mail::to('recipient@example.com')->send(new WelcomeEmail());

This works with all Laravel Mailables and Notifications out of the box. The transport maps from/to/cc/bcc/reply-to, the HTML and text bodies, custom headers and attachments onto a JetEmail send, and adds the returned message ID to the sent message as an X-JetEmail-Id header. API failures surface as a Symfony TransportException.

Direct API Usage

Resolving the client

The JetEmail\Laravel\JetEmail client is bound in the container as a singleton (also aliased as jetemail) and exposes two services:

Service	Property	Description
Email	`$jetemail->email`	Send a single email
Batch	`$jetemail->batch`	Send up to 100 emails in one request

use JetEmail\Laravel\JetEmail;

$jetemail = app(JetEmail::class);   // or app('jetemail')

email and batch are instance properties, not methods, so they cannot be reached through the facade’s static syntax (JetEmail::email is parsed by PHP as a class constant and throws Undefined constant). If you prefer the facade, unwrap it first: \JetEmail\Laravel\Facades\JetEmail::getFacadeRoot()->email->send(...).

Send a single email

use JetEmail\Laravel\Data\SendEmailOptions;

$result = $jetemail->email->send(new SendEmailOptions(
    from: 'you@example.com',
    to: 'recipient@example.com',
    subject: 'Hello!',
    html: '<h1>Welcome</h1><p>Thanks for signing up.</p>',
));

// $result['id']       - the message ID
// $result['response'] - queue confirmation message

Use a from address on a verified domain (see Getting started). SendEmailOptions accepts the following named constructor arguments:

Argument	Required	Description
`from`	✓	Sender, e.g. `"Name <email@domain.com>"`
`to`	✓	Recipient(s), string or array (max 50)
`subject`	✓	Subject line
`html`	*	HTML body (need `html` and/or `text`)
`text`	*	Plain text (need `html` and/or `text`)
`cc`, `bcc`, `replyTo`		Recipients, string or array (max 50 each)
`headers`		Custom headers as `['X-Header' => 'value']`
`attachments`		Array of `Attachment` objects (max 40MB total)

Responses are plain PHP arrays decoded from the API response; a single send returns ['id' => string, 'response' => string].

Send with plain text

$result = $jetemail->email->send(new SendEmailOptions(
    from: 'you@example.com',
    to: 'recipient@example.com',
    subject: 'Hello!',
    text: 'Thanks for signing up.',
));

Multiple recipients, CC, BCC, Reply-To

$result = $jetemail->email->send(new SendEmailOptions(
    from: 'you@example.com',
    to: ['alice@example.com', 'bob@example.com'],
    subject: 'Team Update',
    html: '<p>Here is the latest update.</p>',
    cc: 'manager@example.com',
    bcc: ['logs@example.com'],
    replyTo: 'support@example.com',
));

Attachments

Build attachments with JetEmail\Laravel\Data\Attachment. The helpers base64-encode the content for you; fromPath() takes an optional second argument to override the filename (defaults to the file’s basename).

use JetEmail\Laravel\Data\Attachment;

$result = $jetemail->email->send(new SendEmailOptions(
    from: 'you@example.com',
    to: 'recipient@example.com',
    subject: 'Invoice',
    html: '<p>Please find your invoice attached.</p>',
    attachments: [
        Attachment::fromPath('/path/to/invoice.pdf'),
        Attachment::fromPath('/tmp/abc123.pdf', 'receipt.pdf'),
        Attachment::fromContent('Hello World', 'hello.txt'),
        new Attachment(filename: 'raw.txt', data: base64_encode('already encoded by you')),
    ],
));

Custom headers

$result = $jetemail->email->send(new SendEmailOptions(
    from: 'you@example.com',
    to: 'recipient@example.com',
    subject: 'Tracked Email',
    html: '<p>Hello</p>',
    headers: [
        'X-Campaign-Id' => 'welcome-2024',
    ],
));

Batch send (up to 100 emails)

Pass an array of SendEmailOptions. Returns summary (total, successful, failed) and results per message (success with id, or error with error).

$result = $jetemail->batch->send([
    new SendEmailOptions(
        from: 'you@example.com',
        to: 'alice@example.com',
        subject: 'Hello Alice',
        html: '<p>Hi Alice!</p>',
    ),
    new SendEmailOptions(
        from: 'you@example.com',
        to: 'bob@example.com',
        subject: 'Hello Bob',
        html: '<p>Hi Bob!</p>',
    ),
]);

// $result['summary']['successful'] - number of emails sent
// $result['results'] - per-email results

Without Laravel

The JetEmail client class only uses Guzzle at runtime, so it can be constructed directly without the container (the package still pulls in its illuminate/* dependencies when installed):

use JetEmail\Laravel\JetEmail;
use JetEmail\Laravel\Data\SendEmailOptions;

$jetemail = new JetEmail(
    apiKey: 'your-api-key',
    // baseUrl: 'https://api.jetemail.com', // optional
);

$jetemail->email->send(new SendEmailOptions(
    from: 'you@example.com',
    to: 'recipient@example.com',
    subject: 'Hello!',
    html: '<p>Hello World</p>',
));

Webhooks

JetEmail can send webhook events to your application for email delivery events.

Setup

Add your webhook secret to .env:

JETEMAIL_WEBHOOK_SECRET=your-webhook-secret

The webhook endpoint is automatically registered at POST /jetemail/webhook (route name jetemail.webhook). Point your JetEmail dashboard webhook URL to https://yourdomain.com/jetemail/webhook.

Configuration

You can customise the webhook route prefix and domain:

JETEMAIL_PATH=jetemail
JETEMAIL_DOMAIN=webhooks.yourdomain.com

Listening for events

Listen for webhook events in your EventServiceProvider or using Event::listen():

use JetEmail\Laravel\Events\Outbound\MessageDelivered;
use JetEmail\Laravel\Events\Outbound\MessageBounced;
use JetEmail\Laravel\Events\Outbound\MessageOpened;

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        MessageDelivered::class => [
            HandleDeliveredEmail::class,
        ],
        MessageBounced::class => [
            HandleBouncedEmail::class,
        ],
    ];
}

In your listener:

class HandleDeliveredEmail
{
    public function handle(MessageDelivered $event): void
    {
        $payload = $event->payload;

        // $payload['id']      - event ID
        // $payload['type']    - 'outbound.delivered'
        // $payload['from']    - sender
        // $payload['to']      - recipient
        // $payload['subject'] - subject line
        // $payload['mx']      - receiving mail server
    }
}

Every event class has a single public readonly array $payload property containing the decoded webhook body. Events with a type the SDK doesn’t recognise are acknowledged with 200 Webhook received and no event is dispatched.

Available events

All classes live under the JetEmail\Laravel\Events\Outbound namespace.

Event Class	Webhook Type
`Events\Outbound\MessageQueued`	`outbound.queued`
`Events\Outbound\MessageDelivered`	`outbound.delivered`
`Events\Outbound\MessageDeferred`	`outbound.deferred`
`Events\Outbound\MessageBounced`	`outbound.bounced`
`Events\Outbound\MessageRejected`	`outbound.rejected`
`Events\Outbound\MessageSpam`	`outbound.spam`
`Events\Outbound\MessageVirus`	`outbound.virus`
`Events\Outbound\MessageDropped`	`outbound.dropped`
`Events\Outbound\MessageOpened`	`outbound.opened`
`Events\Outbound\MessageClicked`	`outbound.clicked`
`Events\Outbound\MessageComplaint`	`outbound.complaint`

Signature verification

Webhook signatures are automatically verified when JETEMAIL_WEBHOOK_SECRET is set (the JetEmail\Laravel\Http\Middleware\VerifyWebhookSignature middleware is attached to the route). The middleware validates:

HMAC-SHA256 signature via the X-Webhook-Signature header (sha256=<hex digest> of the raw request body)
Timestamp freshness via X-Webhook-Timestamp (default: 5-minute tolerance)

Requests that fail either check are rejected with a 403 response. You can adjust the tolerance (in seconds; 0 disables the timestamp check):

JETEMAIL_WEBHOOK_TOLERANCE=300

Error Handling

API errors throw JetEmail\Laravel\Exceptions\JetEmailException. Requests that fail client-side validation (missing from, to or subject, neither html nor text, an empty batch or more than 100 emails in a batch) throw a standard InvalidArgumentException before any request is made.

use JetEmail\Laravel\Exceptions\JetEmailException;

try {
    $jetemail->email->send(new SendEmailOptions(...));
} catch (JetEmailException $e) {
    $e->getMessage();   // Error message
    $e->statusCode;     // HTTP status code (0 for network errors); also available via getCode()
    $e->response;       // Full API error response as an array, or null
} catch (InvalidArgumentException $e) {
    // Invalid options, nothing was sent
}

For the full source and additional examples, see the GitHub repository. REST details: API reference.

​Laravel SDK

​Installation

​Configuration

​Laravel Mail Integration

​Direct API Usage

​Resolving the client

​Send a single email

​Send with plain text

​Multiple recipients, CC, BCC, Reply-To

​Attachments

​Custom headers

​Batch send (up to 100 emails)

​Without Laravel

​Webhooks

​Setup

​Configuration

​Listening for events

​Available events

​Signature verification

​Error Handling

Laravel SDK

Installation

Configuration

Laravel Mail Integration

Direct API Usage

Resolving the client

Send a single email

Send with plain text

Multiple recipients, CC, BCC, Reply-To

Attachments

Custom headers

Batch send (up to 100 emails)

Without Laravel

Webhooks

Setup

Configuration

Listening for events

Available events

Signature verification

Error Handling