Download the PHP package bjthecod3r/laravel-zeptomail without Composer

Laravel ZeptoMail

A ZeptoMail mail driver for Laravel. Register zeptomail as a mailer and everything you already write — Mail::to()->send(), Mailables, notifications, queued mail — goes out over the Zoho ZeptoMail API.

Highlights

• A driver, not an API. Nothing in your application changes. Mailables, notifications, Mail::raw(), and queued mail all work as they do on SMTP.
• Templates supported. Point a Mailable at a ZeptoMail template with ->template($key) and pass merge_info; the package routes to the template endpoint and skips uploading a body the template would ignore.
• Inline images render. Anything embedded with $message->embed() is sent as an inline_images entry with its cid, instead of arriving as a file attachment.
• Testable with Http::fake(). Requests go through Laravel's HTTP client, so you assert on outgoing mail exactly like any other outbound call.
• Diagnostics you can act on. Failures throw a TransportExceptionInterface carrying ZeptoMail's status code, error code, request ID, and per-field errors — not a bare \RuntimeException.
• Every region. All eight ZeptoMail data centres, selected with one env var.

Requirements

• PHP ^8.2
• Laravel ^12.0 or ^13.0

Installation

The service provider is auto-discovered. Publishing the config is optional:

Add the mailer to config/mail.php:

Then set your credentials in .env:

ZEPTOMAIL_TOKEN is the Send Mail Token from your ZeptoMail Mail Agent (Mail Agents → your agent → Setup Info → API). Paste it with or without the leading Zoho-enczapikey — the transport normalises either form.

Make sure the from address in config/mail.php is on a domain you have verified in ZeptoMail, or the API will reject the send.

Regions

ZeptoMail runs separate data centres, and your token only works against the one your account lives in. Set ZEPTOMAIL_REGION to match:

The matching Zoho domains (zoho.eu, zohocloud.ca, …) are accepted as aliases.

Configuration

Everything in config/zeptomail.php:

Leave track_opens and track_clicks unset to send no flag at all and let your Mail Agent's own settings decide.

Retries cover connection failures only, and retry_times of 1 means a single attempt with no retry. ZeptoMail's send endpoint is not idempotent, so retrying a request the server may already have accepted would deliver the message twice — raise it deliberately.

Sending mail

There is no ZeptoMail-specific API to learn for ordinary mail:

Attachments and embedded images work as they do elsewhere in Laravel. Attachments become ZeptoMail attachments; anything embedded in a Blade view with $message->embed(...) becomes an inline_images entry, so it renders in the body instead of arriving as a download.

Per-message options

ZeptoMail-specific options are set on the Symfony message, so they work anywhere Laravel hands it to you. In a Mailable, that is the using argument of the envelope:

These are carried as X-ZeptoMail-* headers and stripped before the request is built, so they never reach the recipient. Any other custom header you set is forwarded to ZeptoMail as mime_headers.

Sending with a ZeptoMail template

Point a Mailable at a template and ZeptoMail supplies the subject and body:

The package posts to ZeptoMail's template endpoint and omits the body, which the template would discard anyway. Your Mailable still needs a content() method to satisfy Laravel, but its output is not sent. templateAlias() works the same way if you address templates by alias.

Several Mail Agents or regions

Any option can be set per mailer, falling back to config/zeptomail.php:

Handling failures

A rejected or unreachable send throws ZeptoMailTransportException, which extends Symfony's TransportException. Laravel treats it like any other mail failure — queued mail retries, and Mail::send() throws:

The message already folds in ZeptoMail's per-field errors, so a bad recipient reads as:

On success, ZeptoMail's request ID is recorded as the message ID, which is what you quote when tracing a send in the ZeptoMail dashboard:

Misconfiguration is caught when the mailer is built, not at send time: a missing token or an unrecognised region throws InvalidConfigurationException, naming the accepted values.

Testing

Mail::fake() works as always, intercepting before the transport runs:

To assert on what actually reaches ZeptoMail, fake the HTTP layer instead:

Contributing

See CONTRIBUTING.md.

Credits

This package began as a fork of zohomail/laravel-zeptomail by Zoho Corporation, and has since been rewritten in full.

ZeptoMail and Zoho are trademarks of Zoho Corporation. This package is not affiliated with, endorsed by, or sponsored by Zoho.

License

MIT. See LICENSE.