Como enviar e-mails com PHP

Enviar e-mails com PHP sempre significou brigar com a mail(), configurar servidores SMTP ou incluir dependências pesadas. O SDK PHP do Emailit oferece uma alternativa limpa e moderna. Você pode enviar e-mails transacionais, gerenciar domínios, verificar endereços e tratar webhooks, tudo por meio de um cliente de API simples.

O PHP continua sendo uma das linguagens mais utilizadas para desenvolvimento web, e o envio de e-mails é um requisito essencial para praticamente todas as aplicações PHP. Seja um produto SaaS, uma loja virtual ou um sistema de gerenciamento de conteúdo, a entrega confiável de e-mails é 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 de e-mail dedicada garante que as suas mensagens realmente cheguem à caixa de entrada.

Neste guia, vamos instalar o SDK e usá-lo para enviar e-mails a partir de qualquer aplicação PHP.

Requisitos

• PHP 8.1 ou superior
• Uma conta no 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 sem esforço a qualquer projeto PHP que use o Composer para gerenciar dependências. Não é preciso incluir arquivos à mão nem criar autoloaders.

Inicializar o cliente

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

require 'vendor/autoload.php';

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

A sua chave de API fica no painel do Emailit, em API Keys.

Enviar um e-mail básico

Enviar um e-mail exige uma única 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.

Em comparação com a função nativa mail() do PHP, enviar e-mails por 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 tem uma entrega confiável em todos os principais provedores de e-mail, como Gmail, Outlook e Yahoo.

Enviar com um 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',
    ],
]);

Os templates mantêm o conteúdo dos seus e-mails fora do código e permitem que pessoas que não programam atualizem os textos sem precisar de deploy. Isso é especialmente útil para e-mails transacionais como mensagens de boas-vindas, links de redefinição de senha, recibos de faturas e notificações de envio, em que o design e o texto mudam com mais frequência do 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 é muito usado para enviar faturas, relatórios ou documentos gerados direto da sua aplicação PHP, sem precisar de um link de download separado.

Agendar um e-mail 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

E-mails agendados podem ser cancelados antes de serem enviados:

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

O agendamento é útil para comunicações com hora marcada, como lembretes de consultas, avisos de renovação de assinatura e campanhas de nutrição, em que o horário de envio importa tanto quanto o conteúdo.

Listar e gerenciar e-mails enviados

Obtenha uma lista paginada dos seus e-mails:

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

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

Tente de novo o envio de um e-mail que falhou:

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

Ter visibilidade total dos e-mails enviados e do status de entrega de cada um, além de poder tentar de novo os que falharam, dá a você um nível de controle que a função mail() do PHP simplesmente não oferece. Isso é fundamental para aplicações em que cada e-mail importa, como recibos transacionais, links de verificação de conta e códigos de autenticação de dois fatores.

Verificar endereços de e-mail antes de enviar

Reduza os bounces verificando os endereços antes:

$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 e-mail é 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.

Tratar 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}"),
};

Os webhooks permitem que a sua aplicação PHP reaja na hora quando um e-mail é entregue, aberto ou clicado, ou quando dá bounce. 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 e-mail.

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();
}

Um bom tratamento de erros garante que a sua aplicação falhe de forma controlada quando algo dá errado. As exceções de limite de taxa, por exemplo, podem ser tratadas com uma estratégia de novas tentativas, enquanto os erros de autenticação devem disparar um alerta para você trocar a chave de API.

Além do envio

O SDK oferece acesso à API completa do Emailit, não apenas envio. Você pode gerenciar domínios, chaves de API, listas de contatos, inscritos, templates, supressões, contatos e eventos, tudo pelo 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 e-mail. Em vez de usar bibliotecas ou serviços separados para a gestão de domínios, as listas de contatos e o envio de e-mails, você resolve tudo com um único cliente PHP consistente.

Comece agora

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

composer require emailit/emailit-php

Confira a documentação completa do SDK no GitHub ou consulte a referência da API para ver os detalhes de cada endpoint.