Documentation

Conector Laravel

Packagist: coffeemail/coffeemail-laravel v0.1.0

Driver oficial do CoffeeMail para Laravel Mailer, notificações e webhooks, com integração Symfony Mailer e suporte nativo a filas assíncronas.

Prefere usar o cliente PHP sem framework ou em outro ecossistema? Consulte a documentação do SDK PHP oficial.

SDK PHP

Instalação

packagist.org/packages/coffeemail/coffeemail-laravel ↗

terminal

composer require coffeemail/coffeemail-laravel

Configuração do Ambiente

Adicione as credenciais ao seu arquivo .env e defina o CoffeeMail como o mailer padrão da aplicação.

.env

# .envMAIL_MAILER=coffeemailMAIL_FROM_ADDRESS="contato@seudominio.com.br"MAIL_FROM_NAME="Minha Empresa" COFFEEMAIL_API_KEY=cm_live_sua_chave_aquiCOFFEEMAIL_WEBHOOK_SECRET=whsec_seu_secret_aqui

config/mail.php

// config/mail.php (opcional - configurado automaticamente pelo package)'mailers' => [    'coffeemail' => [        'transport' => 'coffeemail',        'key' => env('COFFEEMAIL_API_KEY'),    ],],

Envio com Laravel Mailer (Mailables e Queues)

Envie e-mails usando a sintaxe nativa do Laravel Mail, com suporte completo a filas assíncronas do queue worker.

app/Mail/PedidoConfirmadoMail.php

namespace App\Mail; use Illuminate\Bus\Queueable;use Illuminate\Mail\Mailable;use Illuminate\Queue\SerializesModels; class PedidoConfirmadoMail extends Mailable{    use Queueable, SerializesModels;     public function __construct(public array $pedido) {}     public function build()    {        return $this->subject('Seu pedido foi confirmado!')            ->html('<h1>Obrigado pela compra!</h1><p>Pedido #' . $this->pedido['id'] . '</p>');    }} // Disparo síncrono ou enfileirado no background worker:use Illuminate\Support\Facades\Mail;use App\Mail\PedidoConfirmadoMail; // Envio imediatoMail::to('cliente@gmail.com')->send(new PedidoConfirmadoMail($pedido)); // Enfileiramento assíncrono (Queue)Mail::to('cliente@gmail.com')->queue(new PedidoConfirmadoMail($pedido));

Acesso Direto à API via Facade

A Facade CoffeeMail permite acessar diretamente qualquer recurso da API CoffeeMail com desestruturação de tupla [$data, $error].

ExemploFacade.php

use CoffeeMail\Laravel\Facades\CoffeeMail; // 1. Envio direto via Facade com tipagem estrita[$data, $error] = CoffeeMail::emails()->send([    'from' => 'noreply@seudominio.com.br',    'to' => 'cliente@gmail.com',    'subject' => 'Notificação Crítica',    'html' => '<p>Conteúdo da mensagem</p>',]); if ($error) {    throw $error->toException();} // 2. Consulta de domínios cadastrados[$domains, $error] = CoffeeMail::domains()->list(); // 3. Consulta de estatísticas[$stats, $error] = CoffeeMail::stats()->get();

Proteção de Webhooks com Middleware

O middleware verify.coffeemail.signature valida a assinatura criptográfica HMAC SHA-256 e protege suas rotas contra adulteração.

routes/api.php

use Illuminate\Http\Request;use Illuminate\Support\Facades\Route; // routes/api.phpRoute::post('/webhooks/coffeemail', function (Request $request) {    $event = $request->input('event');    $payload = $request->input('data');     match ($event) {        'email.delivered' => Log::info("Email entregue: {$payload['id']}"),        'email.bounced' => Log::warning("Bounce detectado: {$payload['id']}"),        default => null,    };     return response()->json(['status' => 'ok']);})->middleware('verify.coffeemail.signature');