Documentation

SDK PHP

Packagist: coffeemail/coffeemail-php v0.1.0

Referência completa do pacote oficial coffeemail/coffeemail-php para PHP moderno (8.2+). Tipagem estrita, retorno seguro data, error, suporte a tuplas e validação criptográfica de webhooks.

Buscando a documentação para Node.js ou TypeScript? Acesse a referência oficial do pacote @coffeemail/node.

SDK Node.js

Instalação

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

terminal

composer require coffeemail/coffeemail-php

Inicialização do Cliente

Laravel • Symfony • WordPress • Vanilla PHP

A chave de API é resolvida automaticamente da variável de ambiente COFFEEMAIL_API_KEY se omitida no construtor.

$client = new CoffeeMail(?string $apiKey = null, string $locale = 'pt-BR', int $timeoutSeconds = 10);

send_email.php

use CoffeeMail\CoffeeMail; // Carrega automaticamente COFFEEMAIL_API_KEY do ambiente ou do construtor:$client = new CoffeeMail(); [$data, $error] = $client->emails->send([    'from' => 'contato@seudominio.com.br',    'to' => 'cliente@gmail.com',    'subject' => 'Bem-vindo ao CoffeeMail!',    'html' => '<h1>Olá!</h1><p>Sua conta está ativa.</p>',]); if ($error !== null) {    echo "Erro ao enviar [{$error->code}]: {$error->message}\n";    exit(1);} echo "E-mail enfileirado com sucesso: {$data['id']}\n";

Desestruturação de Tuplas e Retorno Seguro

Padrão Seguro { data, error }

As operações retornam uma instância de CoffeeMailResponse permitindo desestruturar [$data, $error] diretamente ou chamar ->unwrap() para lançar exceções tipadas.

error_handling.php

use CoffeeMail\CoffeeMail;use CoffeeMail\Exceptions\RateLimitError; $client = new CoffeeMail(); [$data, $error] = $client->emails->send([    'from' => 'contato@seudominio.com.br',    'to' => 'cliente@gmail.com',    'subject' => 'Aviso',    'html' => '<p>Mensagem</p>',]); if ($error instanceof RateLimitError) {    echo "Aguarde {$error->retryAfterSeconds} segundos antes de tentar novamente.\n";    exit(1);} if ($error !== null) {    echo "Falha de envio: {$error->message}\n";    exit(1);} echo "ID: {$data['id']}\n";

Validação Criptográfica de Webhooks

HMAC SHA-256 (hash_equals)

O método Webhooks::verifySignature valida a assinatura HMAC SHA-256 no header x-coffeemail-signature usando comparação em tempo constante contra timing attacks.

webhook_controller.php

use CoffeeMail\Resources\Webhooks; // No endpoint de webhook do seu app PHP:$payload = file_get_contents('php://input');$signature = $_SERVER['HTTP_X_COFFEEMAIL_SIGNATURE'] ?? '';$secret = getenv('COFFEEMAIL_WEBHOOK_SECRET'); if (! Webhooks::verifySignature($payload, $signature, $secret)) {    http_response_code(401);    echo "Assinatura inválida";    exit;} $event = json_decode($payload, true);echo "Evento processado com segurança: " . $event['event'];

Catálogo de Métodos

Referência de operações disponíveis no cliente oficial para PHP.

Emails

.send()— Enviar e-mail transacional

$client->emails->send(array $payload): CoffeeMailResponse

send.php

use CoffeeMail\CoffeeMail; $client = new CoffeeMail(); [$data, $error] = $client->emails->send([    'from' => 'noreply@seudominio.com.br',    'to' => 'cliente@example.com',    'subject' => 'Confirmação do pedido #123',    'html' => '<h1>Obrigado!</h1><p>Seu pedido está em processamento.</p>',]); if ($error !== null) {    echo "Erro ao enviar [{$error->code}]: {$error->message}\n";    exit(1);} echo "E-mail enfileirado com sucesso: {$data['id']}\n";

.sendBatch()— Enviar e-mails em lote

$client->emails->sendBatch(array $items): CoffeeMailResponse

sendBatch.php

use CoffeeMail\CoffeeMail; $client = new CoffeeMail(); [$data, $error] = $client->emails->sendBatch([    [        'from' => 'noreply@seudominio.com.br',        'to' => 'cliente1@example.com',        'subject' => 'Notificação 1',        'html' => '<p>Mensagem 1</p>',    ],    [        'from' => 'noreply@seudominio.com.br',        'to' => 'cliente2@example.com',        'subject' => 'Notificação 2',        'html' => '<p>Mensagem 2</p>',    ],]); if ($error !== null) {    throw $error;}

.get()— Consultar status do e-mail

$client->emails->get(string $id): CoffeeMailResponse

get.php

use CoffeeMail\CoffeeMail; $client = new CoffeeMail(); [$data, $error] = $client->emails->get('eml_8f92b7c4'); if ($data !== null) {    echo "Status: {$data['status']}\n";}

.list()— Listar histórico de envios

$client->emails->list(array $query = []): CoffeeMailResponse

list.php

use CoffeeMail\CoffeeMail; $client = new CoffeeMail(); [$data, $error] = $client->emails->list([    'limit' => 20,    'status' => 'delivered',]);

Domínios

.create()— Cadastrar domínio

$client->domains->create(array $payload): CoffeeMailResponse

create.php

use CoffeeMail\CoffeeMail; $client = new CoffeeMail(); [$data, $error] = $client->domains->create([    'name' => 'meudominio.com.br',]);

.verify()— Verificar registros DNS do domínio

$client->domains->verify(string $id): CoffeeMailResponse

verify.php

use CoffeeMail\CoffeeMail; $client = new CoffeeMail(); [$data, $error] = $client->domains->verify('dom_123');

Templates

.preview()— Pré-visualizar template com variáveis

$client->templates->preview(string $id, array $variables = []): CoffeeMailResponse

preview.php

use CoffeeMail\CoffeeMail; $client = new CoffeeMail(); [$data, $error] = $client->templates->preview('tpl_123', [    'nome' => 'João',    'codigo' => '9842',]);

Webhooks

.verifySignature()— Validar assinatura HMAC de Webhook

Webhooks::verifySignature(string $payload, string $signature, string $secret): bool

verifySignature.php

use CoffeeMail\Resources\Webhooks; // No controller do seu framework (Laravel, Symfony, etc.):$payload = file_get_contents('php://input');$signature = $_SERVER['HTTP_X_COFFEEMAIL_SIGNATURE'] ?? '';$secret = getenv('COFFEEMAIL_WEBHOOK_SECRET'); $isValid = Webhooks::verifySignature($payload, $signature, $secret); if (! $isValid) {    http_response_code(401);    echo "Assinatura inválida";    exit;}

Métricas

.get()— Consultar métricas de entregabilidade

$client->stats->get(array $query = []): CoffeeMailResponse

get.php

use CoffeeMail\CoffeeMail; $client = new CoffeeMail(); [$data, $error] = $client->stats->get([    'from' => '2026-01-01',    'to' => '2026-01-31',]);