README

A lightweight Symfony Mailer transport for Laravel that delivers mail via ZeptoMail’s HTTP API (no SMTP). It plugs into Laravel’s mailers and supports CC/BCC/Reply-To, attachments & inline (CID) images, single & batch sending, template sending (single & batch), custom MIME headers, open/click tracking flags, and a client reference. Under the hood it uses Laravel’s Http client, so you can Http::fake() in tests.

Requirements

• PHP 8.1+
• Laravel 9.x / 10.x / 11.x (Symfony Mailer)
• Outbound HTTPS and TLS 1.2 available
• A ZeptoMail account & API key (use the correct region endpoint, e.g. .com or .eu)

Installation

Install via Composer:

composer require brunocfalcao/laravel-zeptomail-driver

If you don’t use package discovery, register the provider manually:

// config/app.php
'providers' => [
    // ...
    Brunocfalcao\ZeptoMailApiDriver\ZeptoMailApiDriverServiceProvider::class,
],

Configuration

1) Environment

# .env
MAIL_MAILER=zeptomail
MAIL_FROM_ADDRESS=hello@yourdomain.com
MAIL_FROM_NAME="Your App"

# Driver secret
ZEPTOMAIL_MAIL_KEY=your-zeptomail-api-key

# Region endpoint (pick the one for your account):
ZEPTO_MAIL_ENDPOINT=https://api.zeptomail.com
# ZEPTO_MAIL_ENDPOINT=https://api.zeptomail.eu

# Optional tuning
ZEPTO_MAIL_TIMEOUT=30
ZEPTO_MAIL_RETRIES=2
ZEPTO_MAIL_RETRY_MS=200

# Optional defaults
ZEPTO_MAIL_TEMPLATE_KEY=           # or ZEPTO_MAIL_TEMPLATE_ALIAS=
ZEPTO_MAIL_BOUNCE_ADDRESS=         # templates API only
ZEPTO_MAIL_TRACK_OPENS=false
ZEPTO_MAIL_TRACK_CLICKS=false
ZEPTO_MAIL_CLIENT_REFERENCE=
ZEPTO_MAIL_FORCE_BATCH=false

The service provider reads config('services.zeptomail.mail_key') and falls back to env('ZEPTOMAIL_MAIL_KEY').

2) config/services.php

// config/services.php (excerpt)
return [
    // ...
    'zeptomail' => [
        // Primary: configure here. Fallback: env('ZEPTOMAIL_MAIL_KEY')
        'mail_key'        => env('ZEPTOMAIL_MAIL_KEY'),

        // Use .eu if your account lives in the EU region
        'endpoint'        => env('ZEPTO_MAIL_ENDPOINT', 'https://api.zeptomail.com'),

        // HTTP client tuning
        'timeout'         => env('ZEPTO_MAIL_TIMEOUT', 30),
        'retries'         => env('ZEPTO_MAIL_RETRIES', 2),
        'retry_sleep_ms'  => env('ZEPTO_MAIL_RETRY_MS', 200),

        // Optional defaults for convenience
        'template_key'    => env('ZEPTO_MAIL_TEMPLATE_KEY'),
        'template_alias'  => env('ZEPTO_MAIL_TEMPLATE_ALIAS'),
        'bounce_address'  => env('ZEPTO_MAIL_BOUNCE_ADDRESS'),
        'track_opens'     => env('ZEPTO_MAIL_TRACK_OPENS', false),
        'track_clicks'    => env('ZEPTO_MAIL_TRACK_CLICKS', false),
        'client_reference'=> env('ZEPTO_MAIL_CLIENT_REFERENCE'),
        'force_batch'     => env('ZEPTO_MAIL_FORCE_BATCH', false),
    ],
];

3) config/mail.php

// config/mail.php (excerpt)
return [
    'default' => env('MAIL_MAILER', 'smtp'),

    'mailers' => [
        'smtp' => [
            'transport' => 'smtp',
            // ...
        ],

        'zeptomail' => [
            'transport' => 'zeptomail', // registered by the ServiceProvider
        ],
    ],

    'from' => [
        'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'),
        'name'    => env('MAIL_FROM_NAME', 'Example'),
    ],
];

Usage

You can use this transport like any other Laravel mailer.

Single email (default)

use Illuminate\Support\Facades\Mail;
use App\Mail\InvoiceReady;

Mail::to('a@example.com')->send(new InvoiceReady());
// -> POST /v1.1/email

Select the mailer per send

Mail::mailer('zeptomail')->to('a@example.com')->send(new InvoiceReady());

CC / BCC / Reply-To

Mail::mailer('zeptomail')->send(
    (new App\Mail\SimpleMessage)
        ->to('to@example.com')
        ->cc(['cc1@example.com', 'cc2@example.com'])
        ->bcc('audit@example.com')
        ->replyTo('reply@example.com')
);

Attachments & Inline (CID) images

// App\Mail\ReportMail
public function build()
{
    $cid = $this->embed(public_path('img/logo.png')); // <img src="cid:{{ $cid }}">
    return $this->subject('Monthly Report')
        ->view('emails.report', compact('cid'))
        ->attach(storage_path('app/reports/monthly.pdf')); // regular attachment
}

The driver maps attachments to attachments[] and CID images to inline_images[] with cid set accordingly.

Custom MIME headers, tracking, and client reference

public function build()
{
    return $this->subject('Security Alert')
        ->view('emails.security')
        ->withSymfonyMessage(function (Symfony\Component\Mime\Email $email) {
            // Custom headers → go under Zepto's mime_headers
            $email->getHeaders()->addTextHeader('X-Custom-Header', 'abc-123');

            // Tracking flags
            $email->getHeaders()->addTextHeader('X-Zepto-Track-Opens', 'true');
            $email->getHeaders()->addTextHeader('X-Zepto-Track-Clicks', 'false');

            // Optional client reference
            $email->getHeaders()->addTextHeader('X-Zepto-Client-Reference', 'user#42-event#login');
        });
}

Batch sending (per-recipient personalization & hidden recipients)

Use batch when sending to a collection of recipients. Recipients are not visible to each other. You can also provide per-recipient merge_info.

Batch (non-template)

use Illuminate\Support\Facades\Mail;

$recipients = ['alice@example.com', 'bob@example.com', 'carol@example.com'];

$perRecipient = [
    'alice@example.com' => ['name' => 'Alice', 'tier' => 'gold'],
    'bob@example.com'   => ['name' => 'Bob',   'tier' => 'silver'],
    // carol has no specific merge vars
];

Mail::to($recipients)->send(
    (new App\Mail\PromoMail)
        ->withSymfonyMessage(function (Symfony\Component\Mime\Email $email) use ($perRecipient) {
            // Force Zepto batch endpoint
            $email->getHeaders()->addTextHeader('X-Zepto-Batch', 'true');
            // Provide per-recipient merge vars
            $email->getHeaders()->addTextHeader('X-Zepto-PerRecipient-MergeInfo', json_encode($perRecipient));
        })
);
// -> POST /v1.1/email/batch

You can globally enforce batch via services.zeptomail.force_batch=true if you prefer.

Template sending

Send using a template key or alias (single or batch). Provide global merge_info, plus per-recipient merge_info in batch.

Single template email

use Illuminate\Support\Facades\Mail;

Mail::to('jane@example.com')->send(
    (new App\Mail\Templated)
        ->withSymfonyMessage(function (Symfony\Component\Mime\Email $email) {
            // Key or alias (the driver handles either)
            $email->getHeaders()->addTextHeader('X-Zepto-Template', 'my-template-alias'); // or 'ea36f19a...'

            // Global merge vars for this email
            $email->getHeaders()->addTextHeader('X-Zepto-MergeInfo', json_encode([
                'name'       => 'Jane',
                'reset_link' => 'https://example.com/reset/xyz',
            ]));

            // Optional bounce address (templates API)
            $email->getHeaders()->addTextHeader('X-Zepto-Bounce-Address', 'bounce@bounce.example.com');
        })
);
// -> POST /v1.1/email/template

Batch template email

use Illuminate\Support\Facades\Mail;

$recipients = ['a@example.com', 'b@example.com'];

$perRecipient = [
    'a@example.com' => ['name' => 'Alice', 'coupon' => 'ALC-10'],
    'b@example.com' => ['name' => 'Bob',   'coupon' => 'BOB-15'],
];

Mail::to($recipients)->send(
    (new App\Mail\Templated)
        ->withSymfonyMessage(function (Symfony\Component\Mime\Email $email) use ($perRecipient) {
            $email->getHeaders()->addTextHeader('X-Zepto-Template', 'my-template-alias');
            $email->getHeaders()->addTextHeader('X-Zepto-Batch', 'true');
            $email->getHeaders()->addTextHeader('X-Zepto-PerRecipient-MergeInfo', json_encode($perRecipient));

            // Optional global merge vars across all recipients
            $email->getHeaders()->addTextHeader('X-Zepto-MergeInfo', json_encode([
                'product' => 'Pro Plan',
            ]));
        })
);
// -> POST /v1.1/email/template/batch

Testing with Http::fake()

Because this driver uses Laravel’s HTTP client, you can fake the API easily:

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Mail;
use App\Mail\InvoiceReady;

test('sends via zeptomail', function () {
    Http::fake([
        'https://api.zeptomail.com/*' => Http::response(['data' => [['message' => 'Email request received']]], 200),
        // or match your EU endpoint:
        // 'https://api.zeptomail.eu/*' => Http::response([...], 200),
    ]);

    Mail::to('test@example.com')->send(new InvoiceReady());

    Http::assertSent(function ($request) {
        return str_ends_with($request->url(), '/v1.1/email')
            && $request->method() === 'POST'
            && $request->json('subject') === 'Your invoice';
    });
});

Queues

Mailables work seamlessly on queues. Ensure your workers have the same .env values and outbound HTTPS access. If using Horizon, watch memory/timeouts on bursts of batch sends.

Troubleshooting

• 401 / auth errors → Verify the key and that you’re using the correct regional endpoint (.com vs .eu).
• “error” in response JSON → The driver throws if the Zepto response includes an error object; check domain/sender verification and payload shape.
• Inline images not showing → Ensure you embed and reference the returned cid (<img src="cid:{{ $cid }}">).
• Recipients visibility → Use batch endpoints to hide recipients; single-email endpoint can expose them.
• Rate limits / large sends → Batch endpoints support a large number of recipients per request (subject to your Zepto plan). Split very large lists and back off with retries if needed.

How it works

• ZeptoMailApiDriverServiceProvider registers the zeptomail transport.
• ZeptoMailTransport converts the Symfony Email into Zepto payloads and calls the correct endpoint based on headers/config:
  • POST /v1.1/email (single)
  • POST /v1.1/email/batch (batch)
  • POST /v1.1/email/template (template single)
  • POST /v1.1/email/template/batch (template batch)

It also maps: from/to/cc/bcc/reply-to, subject, html/text, attachments, inline images, mime_headers, tracking flags, client_reference, and (for templates) merge_info & optional bounce_address.

Changelog

See CHANGELOG.

Contributing

PRs are welcome. If you add fields, please link the specific Zepto docs section in your PR description and include tests with Http::fake().

Security

Keep secrets in .env. Rotate API keys periodically. Consider setting a dedicated bounce address when using template APIs.

License

The MIT License (MIT). See LICENSE for details.