Enviando E-mails com PHP

O envio de emails em PHP tradicionalmente significava lutar com mail(), configurar servidores SMTP ou incluir dependências pesadas. O SDK PHP do Emailit oferece uma alternativa limpa e moderna. Você pode enviar emails transacionais, gerenciar domínios, verificar endereços e lidar com webhooks, tudo através de um cliente de API simples.

O PHP continua sendo uma das linguagens mais utilizadas para desenvolvimento web, e o envio de emails é um requisito essencial para praticamente todas as aplicações PHP. Seja construindo um produto SaaS, uma loja virtual ou um sistema de gerenciamento de conteúdo, a entrega confiável de emails é fundamental para onboarding de usuários, redefinição de senhas, confirmações de pedidos e campanhas de marketing. Em vez de depender da função nativa mail() do PHP, que oferece controle limitado e nenhuma garantia de entrega, usar uma API dedicada de email garante que suas mensagens realmente cheguem à caixa de entrada.

Neste guia, vamos percorrer a instalação do SDK e seu uso para enviar emails de qualquer aplicação PHP.

Requisitos

• PHP 8.1 ou superior
• Uma conta Emailit com uma chave de API
• Composer

Instalação

Instale o SDK via Composer:

composer require emailit/emailit-php

O SDK PHP do Emailit está disponível como um pacote Composer, então se integra perfeitamente a qualquer projeto PHP que use Composer para gerenciamento de dependências. Não há necessidade de includes manuais de arquivos ou autoloaders personalizados.

Inicializar o cliente

Crie uma instância do cliente com sua chave de API:

require 'vendor/autoload.php';

$emailit = Emailit::client('sua_chave_api');

Você pode encontrar sua chave de API no painel do Emailit em Chaves de API.

Enviar um email básico

Enviar um email requer apenas uma chamada de método:

$email = $emailit->emails()->send([
    'from'    => 'ola@seudominio.com',
    'to'      => ['usuario@exemplo.com'],
    'subject' => 'Olá do Emailit',
    'html'    => '<h1>Bem-vindo!</h1><p>Obrigado por se cadastrar.</p>',
]);

echo $email->id;     // em_abc123...
echo $email->status; // pending

Todos os métodos de serviço retornam objetos de recurso tipados com acesso direto às propriedades, então você sempre sabe exatamente com o que está trabalhando.

Comparado ao uso da função nativa mail() do PHP, enviar emails através de uma API oferece rastreamento de entrega, tratamento de bounces e informações detalhadas de status para cada mensagem. Você não precisa se preocupar em configurar Sendmail ou Postfix no seu servidor, e obtém entrega confiável em todos os principais provedores de email como Gmail, Outlook e Yahoo.

Enviar com template

Se você criou um template no painel do Emailit, pode referenciá-lo pelo slug e passar variáveis:

$email = $emailit->emails()->send([
    'from'      => 'ola@seudominio.com',
    'to'        => 'usuario@exemplo.com',
    'template'  => 'email_boas_vindas',
    'variables' => [
        'nome'    => 'João Silva',
        'empresa' => 'Acme Ltda',
    ],
]);

Templates mantêm o conteúdo dos seus emails fora do código e permitem que não-desenvolvedores atualizem textos sem precisar fazer deploy. Isso é especialmente útil para emails transacionais como mensagens de boas-vindas, links de redefinição de senha, recibos de faturas e notificações de envio, onde o design e a redação mudam mais frequentemente que o código que os dispara.

Enviar com anexos

Anexe arquivos passando conteúdo codificado em base64:

$email = $emailit->emails()->send([
    'from'        => 'faturas@seudominio.com',
    'to'          => 'cliente@exemplo.com',
    'subject'     => 'Sua Fatura #12345',
    'html'        => '<p>Segue em anexo sua fatura.</p>',
    'attachments' => [
        [
            'filename'     => 'fatura.pdf',
            'content'      => base64_encode(file_get_contents('fatura.pdf')),
            'content_type' => 'application/pdf',
        ],
    ],
]);

Você pode anexar PDFs, imagens, planilhas ou qualquer outro tipo de arquivo. Isso é comumente usado para enviar faturas, relatórios ou documentos gerados diretamente da sua aplicação PHP sem precisar de um link de download separado.

Agendar um email para mais tarde

Passe um timestamp scheduled_at para enviar em uma data futura:

$email = $emailit->emails()->send([
    'from'         => 'lembretes@seudominio.com',
    'to'           => 'usuario@exemplo.com',
    'subject'      => 'Lembrete de Consulta',
    'html'         => '<p>Sua consulta é amanhã às 14h.</p>',
    'scheduled_at' => '2026-04-10T09:00:00Z',
]);

echo $email->status;       // scheduled
echo $email->scheduled_at; // 2026-04-10T09:00:00Z

Emails agendados podem ser cancelados antes de serem enviados:

$emailit->emails()->cancel('em_abc123');

O agendamento é útil para comunicações sensíveis ao tempo como lembretes de consultas, avisos de renovação de assinatura e campanhas de nutrição onde o horário de envio importa tanto quanto o conteúdo.

Listar e gerenciar emails enviados

Recupere uma lista paginada dos seus emails:

$emails = $emailit->emails()->list(['page' => 1, 'limit' => 10]);

foreach ($emails as $email) {
    echo $email->id . ' - ' . $email->status . "\n";
}

Tente novamente um email que falhou:

$emailit->emails()->retry('em_abc123');

Ter visibilidade completa dos seus emails enviados, seu status de entrega e a capacidade de tentar novamente falhas oferece um nível de controle que a função mail() do PHP simplesmente não consegue fornecer. Isso é crítico para aplicações onde cada email importa, como recibos transacionais, links de verificação de conta e códigos de autenticação de dois fatores.

Verificar endereços de email antes de enviar

Reduza bounces verificando endereços antecipadamente:

$result = $emailit->emailVerifications()->verify([
    'email' => 'teste@exemplo.com',
]);

echo $result->status; // valid
echo $result->score;  // 0.95
echo $result->risk;   // low

A verificação de email é uma boa prática para proteger sua reputação de remetente. Enviar para endereços inválidos ou descartáveis aumenta sua taxa de bounce, o que pode acionar filtros de spam e prejudicar a entregabilidade em todo o seu domínio. Ao verificar endereços antes de enviar, você mantém suas taxas de bounce baixas e sua reputação intacta.

Lidar com eventos de webhook

O SDK inclui classes de evento tipadas e verificação de assinatura para webhooks. Isso permite reagir a eventos de entrega em tempo real:

use Emailit\WebhookSignature;
use Emailit\Events\EmailDelivered;
use Emailit\Events\EmailBounced;

$event = WebhookSignature::verify(
    file_get_contents('php://input'),
    $_SERVER['HTTP_X_EMAILIT_SIGNATURE'],
    $_SERVER['HTTP_X_EMAILIT_TIMESTAMP'],
    'seu_segredo_assinatura_webhook'
);

match (true) {
    $event instanceof EmailDelivered => handleDelivered($event),
    $event instanceof EmailBounced   => handleBounce($event),
    default                          => log("Não tratado: {$event->type}"),
};

Webhooks permitem que sua aplicação PHP responda instantaneamente quando um email é entregue, retornado, aberto ou clicado. Isso é essencial para construir fluxos orientados a eventos como atualizar um CRM quando uma mensagem é entregue, alertar sua equipe de suporte sobre bounces ou rastrear métricas de engajamento para suas campanhas de email.

Tratamento de erros

O SDK lança exceções tipadas para que você possa tratar cada caso de erro com precisão:

use Emailit\Exceptions\AuthenticationException;
use Emailit\Exceptions\RateLimitException;
use Emailit\Exceptions\UnprocessableEntityException;
use Emailit\Exceptions\ApiErrorException;

try {
    $emailit->emails()->send([...]);
} catch (AuthenticationException $e) {
    // Chave de API inválida (401)
} catch (RateLimitException $e) {
    // Muitas requisições (429)
} catch (UnprocessableEntityException $e) {
    // Validação falhou (422)
} catch (ApiErrorException $e) {
    // Qualquer outro erro de API
    echo $e->getHttpStatus();
}

O tratamento adequado de erros garante que sua aplicação degrade graciosamente quando algo dá errado. Exceções de limite de taxa, por exemplo, podem ser tratadas com uma estratégia de retry, enquanto erros de autenticação devem disparar um alerta para que você possa rotacionar sua chave de API.

Além de emails

O SDK oferece acesso à API completa do Emailit, não apenas envio. Você pode gerenciar domínios, chaves de API, audiências, assinantes, templates, supressões, contatos e eventos, tudo do PHP:

$domain = $emailit->domains()->create(['name' => 'exemplo.com']);
$contact = $emailit->contacts()->create(['email' => 'usuario@exemplo.com']);
$templates = $emailit->templates()->list();

Isso torna o SDK PHP do Emailit um kit completo de infraestrutura de email. Em vez de usar bibliotecas ou serviços separados para gerenciamento de domínios, listas de contatos e envio de emails, você pode lidar com tudo através de um único cliente PHP consistente.

Comece agora

Instale o SDK e envie seu primeiro email em menos de um minuto:

composer require emailit/emailit-php

Confira a documentação completa do SDK no GitHub, ou vá para a Referência da API para detalhes sobre todos os endpoints.