Enviar e-mail no WordPress com wp_mail() (e SMTP)

Atualizado em 19/06/2026

Todo e-mail que o WordPress dispara passa por uma única função: wp_mail(). Ela é uma fina camada sobre a biblioteca PHPMailer, incluída no núcleo. Entender essa pilha — função, filtros e o action de configuração — é o que permite enviar HTML corretamente, definir um remetente confiável e, principalmente, garantir entregabilidade. Este último ponto é onde a maioria dos sites tropeça, e é também onde mora a maior parte do trabalho de especialista. Se você ainda está se ambientando com pontos de extensão, vale revisar antes os hooks (actions e filters), já que tudo aqui é construído sobre eles.

A assinatura de wp_mail()

A função aceita cinco parâmetros, dos quais só os três primeiros são obrigatórios na prática:

<?php
// wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ): bool
$enviado = wp_mail(
    '[email protected]',          // string ou array de destinatários
    'Seu pedido foi confirmado',    // assunto
    'Obrigado pela compra!'         // corpo (texto puro por padrão)
);

if ( ! $enviado ) {
    // Algo falhou no transporte — veja a seção sobre wp_mail_failed.
}

O retorno é um booleano que indica apenas se a mensagem foi aceita pelo transporte. Ele não garante que o e-mail chegou à caixa do destinatário — essa é uma distinção crucial que discutiremos em entregabilidade. O parâmetro $to aceita uma string ou um array; $headers aceita uma string com quebras de linha ou um array de linhas; e $attachments espera caminhos absolutos de arquivos no servidor.

Enviando HTML: o Content-Type

Por padrão, wp_mail() envia em text/plain. Se você colocar tags HTML no corpo sem mudar o Content-Type, o cliente de e-mail mostrará o markup cru (<p>, <a>…) como texto. Há duas formas de declarar HTML. A primeira, e mais segura, é passar o header diretamente na chamada — assim o tipo vale só para aquele e-mail:

<?php
$to      = '[email protected]';
$subject = 'Bem-vindo à loja';
$message = '<h1>Olá!</h1>'
         . '<p>Seu cadastro foi criado. '
         . '<a href="https://exemplo.com/conta">Acessar minha conta</a>.</p>';

$headers = array(
    'Content-Type: text/html; charset=UTF-8',
    'From: Loja Exemplo <[email protected]>',
);

wp_mail( $to, $subject, $message, $headers );

A segunda forma é o filtro wp_mail_content_type. Ele é global: muda o tipo de todos os e-mails enquanto estiver ativo. Por isso, o padrão correto é adicioná-lo, enviar e removê-lo na sequência:

<?php
add_filter( 'wp_mail_content_type', 'meu_content_type_html' );

function meu_content_type_html() {
    return 'text/html';
}

wp_mail( $to, $subject, $message );

// Reverte para não afetar e-mails do núcleo e de outros plugins.
remove_filter( 'wp_mail_content_type', 'meu_content_type_html' );

Definindo o remetente: wp_mail_from e wp_mail_from_name

Sem configuração, o WordPress envia de [email protected] com o nome "WordPress". Esse remetente genérico prejudica tanto a marca quanto a entregabilidade. Ajuste-o com dois filtros:

<?php
add_filter( 'wp_mail_from',      'meu_email_remetente' );
add_filter( 'wp_mail_from_name', 'meu_nome_remetente' );

function meu_email_remetente( $original ) {
    // Use SEMPRE um endereço do seu próprio domínio.
    return '[email protected]';
}

function meu_nome_remetente( $original ) {
    return 'Loja Exemplo';
}

Os callbacks recebem o valor original e devem retorná-lo (são filters, não actions). O endereço escolhido precisa pertencer ao domínio que assina os e-mails via SPF/DKIM; um From divergente do domínio de envio é um dos sinais mais fortes para um filtro de spam descartar a mensagem.

SMTP sem plugin: o action phpmailer_init

O wp_mail() instancia internamente um objeto PHPMailer. O action phpmailer_init entrega esse objeto por referência, e é o ponto oficial para configurar SMTP autenticado direto no código, sem instalar um plugin:

<?php
add_action( 'phpmailer_init', 'meu_smtp' );

function meu_smtp( $phpmailer ) {
    $phpmailer->isSMTP();
    $phpmailer->Host       = 'smtp.seuprovedor.com';
    $phpmailer->Port       = 587;                 // 587 = STARTTLS; 465 = SMTPS
    $phpmailer->SMTPAuth   = true;
    $phpmailer->SMTPSecure = 'tls';               // 'tls' p/ 587, 'ssl' p/ 465
    // Credenciais via constantes do wp-config.php — nunca no banco/repositório.
    $phpmailer->Username   = defined( 'MEU_SMTP_USER' ) ? MEU_SMTP_USER : '';
    $phpmailer->Password   = defined( 'MEU_SMTP_PASS' ) ? MEU_SMTP_PASS : '';
}

Entregabilidade: o que realmente importa

Aqui está o conhecimento que separa quem "manda e-mail" de quem garante que o e-mail chega. Em hospedagem compartilhada, o mail() do PHP entrega através de um servidor local sem autenticação e com IP de reputação muitas vezes ruim — o resultado é spam ou descarte silencioso. A correção tem duas frentes que se complementam:

• Transporte autenticado (SMTP): envie por um serviço de e-mail transacional ou pelo SMTP do seu provedor, com usuário e senha — via plugin ou via phpmailer_init. Isso resolve a autenticação do envio.
• Autenticação de domínio no DNS: configure os três registros que provam ao destinatário que você está autorizado a enviar pelo seu domínio:

Sem esses registros, mesmo um SMTP perfeito pode cair em spam, porque o destinatário não consegue confirmar que o seu domínio autorizou o envio. E lembre-se: o endereço em From precisa ser do domínio coberto por esses registros — usar um @gmail.com como remetente em um envio que sai do seu servidor falha o alinhamento de DMARC e tende a ser rejeitado.

Depuração: capturando o erro com wp_mail_failed

Quando wp_mail() retorna false, o motivo real fica em um objeto WP_Error que o WordPress dispara pelo action wp_mail_failed. Registrá-lo é a forma correta de depurar — autenticação recusada, host errado, porta bloqueada, tudo aparece ali:

<?php
add_action( 'wp_mail_failed', 'meu_log_de_email' );

function meu_log_de_email( $wp_error ) {
    // $wp_error é um objeto WP_Error com o motivo da falha.
    if ( is_wp_error( $wp_error ) ) {
        error_log( '[wp_mail] Falha no envio: ' . $wp_error->get_error_message() );

        // Os dados do envio também vêm no objeto, úteis para diagnóstico:
        $data = $wp_error->get_error_data();
        if ( ! empty( $data['to'] ) ) {
            error_log( '[wp_mail] Destinatário(s): ' . implode( ', ', (array) $data['to'] ) );
        }
    }
}

Combine isso com o retorno booleano: trate o false no seu fluxo (não dê o cadastro como concluído, por exemplo) e use o wp_mail_failed para entender por quê. Em desenvolvimento, você também pode habilitar o debug do SMTP definindo $phpmailer->SMTPDebug = 2; dentro do phpmailer_init — apenas nunca deixe isso ligado em produção, pois despeja a conversa SMTP no output.

Onde o WooCommerce entra

As notificações transacionais do WooCommerce — "pedido recebido", "processando", "concluído", redefinição de senha do cliente — são, no fim, chamadas a wp_mail() com templates HTML por cima. Isso tem uma consequência prática importante: configurar SMTP e remetente conserta a entregabilidade da loja inteira de uma vez, sem precisar mexer e-mail por e-mail. O que muda no WooCommerce é a camada de gatilhos e templates (quais eventos disparam, qual layout usar), e isso é assunto do artigo sobre e-mails transacionais do WooCommerce.

Resumo: header, filtro ou hook?

Armadilhas comuns

• HTML sem Content-Type: o e-mail chega com as tags visíveis como texto. Declare o tipo por header ou filtro.
• Filtro de Content-Type não revertido: quebra a formatação de todos os e-mails em texto puro do site. Sempre remova o filtro após o envio pontual.
• From divergente do domínio: derruba o alinhamento de SPF/DKIM/DMARC e manda o e-mail para o spam. Use um endereço do próprio domínio.
• Anexos por caminho relativo: $attachments exige caminho absoluto no servidor; um caminho relativo simplesmente não anexa.
• Confiar no retorno true: ele só diz que o transporte aceitou a mensagem, não que ela chegou. Entregabilidade depende de SMTP + DNS, não do booleano.
• Credenciais SMTP no banco ou no repositório: guarde usuário e senha em constantes do wp-config.php ou variáveis de ambiente.

Boas práticas

• Prefira SMTP autenticado a mail() em qualquer site que dependa de e-mail (loja, formulário, login).
• Configure SPF, DKIM e DMARC no DNS antes de culpar o WordPress por e-mails no spam.
• Use um remetente do seu domínio, com nome reconhecível, alinhado à autenticação.
• Para HTML pontual, passe o Content-Type por header; para envios em lote, use o filtro e reverta-o.
• Sempre registre falhas com wp_mail_failed e trate o retorno booleano no fluxo da aplicação.
• Mantenha a configuração de envio em um plugin via hooks, não dentro do tema, para não perdê-la em uma troca de template.