Download the PHP package samuelterra22/volpa-mail-laravel without Composer

Volpa Mail for Laravel

Official Volpa Mail SDK and Mail Transport for Laravel. Send transactional emails through the Volpa Mail API using Laravel's native Mail facade or the SDK directly — with typed DTOs, retries, and rich error handling.

What this package is: the client SDK that your Laravel apps install to send mail through Volpa Mail. It does not contain the Volpa Mail backend (the multi-tenant sending platform).

Table of contents

• Requirements
• Feature scope
• Installation
• Configuration
• Quick start
• Using as a Laravel Mailer
• Using as a direct SDK
• Idempotency-Key on send
• Suppressions
• Contacts & contact lists
• Broadcasts
• Webhook verification
• Email payload reference
• Attachments
• Checking delivery status
• Error handling
• Troubleshooting
• Testing & quality
• Contributing — Conventional Commits & releases
• License

Requirements

Feature scope

Installation

The service provider and the VolpaMail facade are auto-discovered — no manual registration needed.

Publish the config (optional, only if you want to tweak defaults):

This creates config/volpa-mail.php.

Configuration

Add your credentials to .env:

All available environment variables:

The API key is mandatory. If it is missing, the SDK throws VolpaMailException::missingApiKey() on the first call — fail fast instead of silently dropping mail.

Quick start

Using as a Laravel Mailer

Register the mailer in config/mail.php:

Make it the default mailer:

…or use it on demand for a single message:

All standard Mailable features work as usual — Markdown mailables, attachments, cc/bcc, replyTo, custom headers. The transport converts the Symfony message into a Volpa Mail API call and records the returned email ID as the message ID (setMessageId($sent->id)) so you can correlate it with webhook events on the backend.

Using as a direct SDK

For fine-grained control, templates, and variables, call the SDK directly.

With a friendly array

With a typed DTO

Idempotency-Key on send

Pass a unique key as the second argument to send() to enable idempotent delivery. The backend replays the same response for a repeated key (24-hour TTL) instead of sending a duplicate email. On a body mismatch for the same key, the API returns 409 Conflict.

The recommended key format is UUID v7 (time-ordered):

Store the key with the job so retries reuse it safely.

Suppressions

Manage the suppression list (hard bounces, complaints, unsubscribes, etc.):

SuppressionReason cases: HardBounce, SoftBounceRepeated, Complaint, Unsubscribe, Manual, InvalidAddress.

Contacts & contact lists

ContactStatus cases: Active, Unsubscribed, Bounced, Complained.

Broadcasts

BroadcastStatus cases: Draft, Scheduled, Sending, Sent, Canceled, Failed. Use $status->isFinal() to check if the broadcast has reached a terminal state.

Webhook verification

The Volpa Mail backend sends events to your endpoint (e.g. delivered, bounced) signed with a custom HMAC-SHA256 scheme.

Signature format — the delivery header is X-VolpaMail-Signature:

The signed string is <unix_timestamp>.<raw_json_body>. The tolerance window defaults to 300 seconds.

Verifying in a controller

Or verify raw payload + header string manually:

The event type is also available in the X-VolpaMail-Event header if you need it before parsing the body.

Email payload reference

Fields accepted by send() (array keys / DTO constructor args). Empty optional fields are omitted from the request body.

Attachments

Build an attachment from a file on disk (it is read and base64-encoded for you):

Or construct it explicitly with already-encoded content:

Checking delivery status

EmailStatus cases:

Error handling

Any non-2xx response (or a missing API key) raises a SamuelTerra\VolpaMail\Exceptions\VolpaMailException:

The exception parses both error envelopes returned by the backend: {"error":{"code","message"}} and {"message","errors"}. On HTTP 429, check $e->retryAfter before scheduling a retry.

Troubleshooting

Testing & quality

The test suite uses Pest and Orchestra Testbench with Http::fake() — no real network calls are made.

Run all three before pushing:

Contributing — Conventional Commits & releases

This package is versioned automatically. When you push to main, the CI workflow runs the tests; if they pass, the Release workflow reads the commit messages, computes the next version (SemVer), and publishes the tag + GitHub Release — which syncs Packagist. You never create a tag by hand.

For this to work, commits must follow the Conventional Commits standard:

Types and version impact

Since the workflow uses default_bump: false, a push that contains only no-effect commits (e.g. just docs:) does not generate a release — correct SemVer behavior.

Breaking change (major)

Use ! after the type or a BREAKING CHANGE: footer:

Examples

Before pushing, make sure the gate is green locally:

License

MIT. See LICENSE.md.