README

Official Volpa Mail SDK and Mail Transport for Laravel. Send transactional emails through the Volpa Mail API using Laravel's native Mail or the SDK directly.

Installation

composer require samuelterra22/volpa-mail-laravel

Publish the config (optional):

php artisan vendor:publish --tag=volpa-mail-config

Configure your .env:

VOLPA_MAIL_API_KEY=vmk_xxxxxxxxxxxxxxxx
VOLPA_MAIL_BASE_URL=https://api.mail.volpa.com.br/v1

Using as a Laravel Mailer

Add the mailer in config/mail.php:

'mailers' => [
    'volpa-mail' => [
        'transport' => 'volpa-mail',
    ],
],

Set it as the default (MAIL_MAILER=volpa-mail) or use it on demand:

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

Mail::mailer('volpa-mail')->to($user->email)->send(new WelcomeMail($user));

All Mailable features (markdown, attachments, cc/bcc, reply-to) work as usual.

Using as a direct SDK

use SamuelTerra\VolpaMail\Facades\VolpaMail;

$sent = VolpaMail::emails()->send([
    'from' => ['email' => 'contato@athelier.com.br', 'name' => 'Athelier'],
    'to' => [['email' => 'cliente@gmail.com']],
    'subject' => 'Sua reserva foi confirmada!',
    'html' => '<h1>Obrigado!</h1>',
    'template_id' => 'reservation-confirmation',
    'variables' => ['name' => 'João'],
]);

echo $sent->id;      // eml_123
echo $sent->status->value; // queued

Or with a typed DTO:

use SamuelTerra\VolpaMail\Data\Address;
use SamuelTerra\VolpaMail\Data\SendEmailData;
use SamuelTerra\VolpaMail\Facades\VolpaMail;

VolpaMail::emails()->send(new SendEmailData(
    from: new Address('no-reply@volpa.com.br', 'Volpa'),
    to: [new Address('cliente@gmail.com')],
    subject: 'Olá',
    html: '<p>Conteúdo</p>',
));

Check status:

$email = VolpaMail::emails()->get('eml_123');

Tests

composer test
composer analyse   # PHPStan level 8
composer format    # Pint

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:

<type>[optional scope]: <description>

[optional body]

[optional footer]

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:

feat!: rename VolpaMail::emails()->find() to ->get()

BREAKING CHANGE: the find() method was removed; use get().

Examples

git commit -m "feat: support Idempotency-Key on send()"
git commit -m "fix(transport): propagate reply_to when converting Symfony Email"
git commit -m "docs: document status lookup"   # no release

Before pushing, make sure the gate is green locally:

composer test && composer analyse && composer format

License

MIT. See LICENSE.md.