Como verificar e-mails em formulários do WordPress

Todo plugin de formulário do WordPress vai alegremente coletar asdf@asdf e uma centena de endereços do Gmail digitados errado, e entregá-los direto para sua lista de e-mails. Para verificar e-mails em formulários do WordPress você não precisa de um plugin novo — você precisa chamar uma API de verificação no momento em que alguém faz o envio, ou exportar os registros e limpá-los em massa. Este guia mostra os dois caminhos para os três grandes plugins de formulário (Contact Form 7, WPForms, Gravity Forms) usando padrões que funcionam independentemente de qual deles você usa.

A resposta curta#

Dois padrões suportados, e qual você escolhe depende do seu plugin e do plano dele:

1. Tempo real — conecte-se ao evento de envio ou validação do plugin e chame a API da Qualisend antes de o registro ser confirmado. Na maioria dos plugins isso é um pequeno trecho de PHP em um filtro de validação (o único lugar onde você consegue rejeitar um endereço na hora), ou uma etapa de webhook nos planos Pro para marcação assíncrona.
2. Em massa — exporte os registros armazenados pelo plugin para CSV e passe todos pelo verificador em massa da Qualisend de tempos em tempos. Sem código, funciona em qualquer plano que armazene registros.

Verificar e-mails em formulários do WordPress no envio#

Praticamente todo plugin de formulário dispara um evento no lado do servidor quando chega um envio, e esse evento é o seu ponto de integração. A distinção importante é quando o hook dispara, porque isso decide se você consegue bloquear um endereço ruim ou apenas reagir a ele:

Se você quer que o visitante veja "esse endereço não parece entregável" e o corrija, você precisa do filtro de validação, o que significa um pouco de PHP. Se você só quer manter endereços mortos fora da sua ferramenta seguinte, um webhook basta e não precisa de código.

Aqui está a abordagem com filtro de validação no filtro de validação de e-mail do Contact Form 7. O mesmo formato se aplica ao Gravity Forms e ao WPForms — só mudam o nome do hook (gform_field_validation no Gravity Forms, wpforms_process no WPForms) e a forma como você anexa o erro. Se o Gravity Forms é o seu plugin, o guia de verificação de e-mails no Gravity Forms percorre o hook gform_field_validation de ponta a ponta com a fiação específica do GF. A chave de API fica em uma constante no wp-config.php, nunca em um shortcode, arquivo de tema ou JavaScript de front-end:

// In a snippet plugin, or your theme's functions.php.
// In wp-config.php:  define( 'QUALISEND_API_KEY', 'YOUR_API_KEY' );

add_filter( 'wpcf7_validate_email*', 'qs_verify_email', 20, 2 );
add_filter( 'wpcf7_validate_email',  'qs_verify_email', 20, 2 );

function qs_verify_email( $result, $tag ) {
    $field = $tag->name;
    $email = isset( $_POST[ $field ] ) ? trim( wp_unslash( $_POST[ $field ] ) ) : '';
    if ( $email === '' ) {
        return $result; // let the plugin's own required-field check handle it
    }

    // Check /developers for the exact endpoint and request body.
    $response = wp_remote_post( 'https://api.qualisend.com/v1/verify', array(
        'timeout' => 4, // don't let a slow probe stall the form
        'headers' => array(
            'Authorization' => 'Bearer ' . QUALISEND_API_KEY,
            'Content-Type'  => 'application/json',
        ),
        'body' => wp_json_encode( array( 'email' => $email ) ),
    ) );

    // Fail open: never block a real visitor because our API had a bad moment.
    if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) !== 200 ) {
        return $result;
    }

    $data    = json_decode( wp_remote_retrieve_body( $response ), true );
    $verdict = $data['result'] ?? array();

    if ( ( $verdict['status'] ?? '' ) === 'undeliverable' ) {
        $result->invalidate( $tag, "That address doesn't look deliverable — please check it." );
    } elseif ( ! empty( $verdict['sub_flags']['disposable'] ) ) {
        $result->invalidate( $tag, 'Please use a permanent email address.' );
    }

    return $result;
}

Três coisas sustentam esse trecho, e são as mesmas três em qualquer linguagem: mantenha a chave no lado do servidor, limite a requisição com um timeout curto e falhe aberto — se a chamada der erro, estourar o tempo ou retornar um código diferente de 200, deixe o envio passar. Uma API de verificação é um filtro de qualidade, não um porteiro, e perder um lead real por causa de uma falha passageira é o pior desfecho. Para a mecânica da própria chamada de API — cabeçalhos, tratamento de erros, formato da resposta — o guia de validação de e-mail em PHP percorre a mesma requisição de ponta a ponta.

Se PHP personalizado não é uma opção, a alternativa sem código é um webhook. Se o seu plugin oferece webhooks — o Gravity Forms pelo seu Webhooks Add-On, o WPForms pelo addon Webhooks, ambos em licenças de nível mais alto — aponte o webhook para uma pequena função serverless que guarda sua chave e chama a API. O detalhe, conforme a tabela acima: esses webhooks disparam depois que o registro é salvo, então não conseguem mostrar um erro na hora. O que eles conseguem fazer é verificar de forma assíncrona e agir sobre o veredicto — adicionar uma tag, pular a resposta automática ou descartar endereços não entregáveis antes que cheguem à sua ferramenta de e-mail. Uma etapa de webhook sem código (do tipo que o Zapier ou o Make expõem) funciona da mesma forma: envio do formulário na entrada, chamada de API, veredicto na saída.

Se um determinado plugin expõe webhooks ou permite rodar PHP personalizado depende inteiramente do plugin e do seu plano — o Contact Form 7 gratuito lhe dá o filtro de validação, mas nenhuma interface de webhook; o Gravity Forms e o WPForms deixam os webhooks atrás de complementos pagos. Confira o que o seu nível inclui antes de se comprometer com um caminho.

Agir sobre o veredicto#

A API retorna um objeto result que contém um status de deliverable, risky, undeliverable ou unknown, além de um score de 0 a 100, um código de reason e sub-flags para disposable, role, free e catch_all — o mesmo $data['result'] que o trecho acima lê. Mapeie esses valores para uma ação do formulário:

O veredicto local imediato — sintaxe, domínio, descartável, função — é o que você quer em um formulário ao vivo: ele retorna rápido e captura a maior parte dos envios ruins. A sondagem SMTP da caixa de correio, mais pesada, é mais adequada ao caminho em massa abaixo, onde alguns segundos de latência não importam. Se você está avaliando por que cada checagem fica onde fica, como funciona a verificação de e-mail detalha o pipeline.

Ou verifique os registros em massa a partir de uma exportação em CSV#

Nem todo formulário precisa de um portão em tempo real, e alguns plugins tornam o código personalizado incômodo. A alternativa sem código é deixar os envios se acumularem e limpá-los de tempos em tempos.

1. Exporte os registros para CSV. O Gravity Forms tem Import/Export → Export Entries; o WPForms tem uma exportação de registros no plano Pro; o Contact Form 7 não armazena nada por padrão, então combine-o com o plugin gratuito Flamingo para capturar os envios primeiro.
2. Verifique o CSV em massa. Envie-o para o verificador em massa da Qualisend, que roda o pipeline completo — incluindo a sondagem SMTP — em cada linha e devolve um arquivo com pontuação.
3. Filtre e sincronize. Mantenha os deliverable, revise os risky e descarte os undeliverable antes de importar os sobreviventes para a sua plataforma de e-mail.

Esse é o mesmo fluxo de qualquer limpeza de lista, só que originado da tabela de registros do seu formulário — o guia de como limpar uma lista de e-mails cobre o ciclo de exportar-verificar-reimportar por completo. A verificação em massa também é a ferramenta certa para os endereços que você já coletou antes de adicionar uma checagem em tempo real: passe o acervo antigo uma vez e, daí em diante, deixe o hook no momento do envio manter a lista limpa.

Tempo real, em massa ou os dois#

Eles resolvem problemas diferentes, então a maioria dos sites acaba querendo os dois:

• Tempo real é prevenção. Um erro de digitação capturado no envio é um lead salvo com uma correção de uma linha; um domínio morto rejeitado ali nunca vira um hard bounce que abala sua taxa de rejeição.
• Em massa é faxina. Os endereços se deterioram — as pessoas mudam de emprego, domínios expiram — então até uma lista perfeitamente filtrada precisa de reverificação periódica.

Combinar um hook no momento do envio com uma passagem mensal em massa segue a mesma lógica de unir a verificação a um fluxo de double opt-in: barre o lixo óbvio na porta e varra o resto de tempos em tempos.

Perguntas frequentes#

Consigo verificar e-mails no Contact Form 7 sem um complemento pago?#

Sim. O Contact Form 7 expõe o filtro wpcf7_validate_email na sua versão gratuita, então um pequeno trecho de PHP como o acima pode chamar a API e rejeitar endereços não entregáveis ou descartáveis na hora — sem precisar de complemento. Você só precisa conseguir adicionar código (pelo functions.php do seu tema ou por um plugin de trechos de código) e armazenar sua chave de API no wp-config.php.

Um webhook do Gravity Forms ou do WPForms consegue rejeitar um endereço ruim na hora?#

Geralmente não. Esses webhooks disparam depois que o registro é salvo, então rodam de forma assíncrona e não conseguem mostrar ao visitante um erro de validação. Eles são ideais para marcar, rotear ou suprimir endereços não entregáveis antes que cheguem à sua ferramenta de e-mail. Para uma rejeição na hora que o visitante veja, use o filtro de validação do plugin com PHP personalizado.

Existe um plugin nativo da Qualisend para o WordPress?#

No momento não — nossas integrações nativas de plataforma estão sendo reconstruídas, e um conector para o WordPress está no roteiro. Até ele chegar, as abordagens suportadas são as duas deste guia: chamar a API REST a partir de um hook de formulário, webhook ou função serverless, ou exportar os registros para CSV e verificar em massa. Ambas usam a API documentada diretamente.

Devo verificar no envio ou limpar os registros em massa?#

Os dois, por motivos diferentes. Verificar no envio impede que erros de digitação e endereços descartáveis entrem na sua lista, com retorno imediato para o visitante. A verificação em massa captura endereços que se deterioraram depois de coletados e limpa o acervo antigo que você reuniu antes de adicionar uma checagem em tempo real. Um hook no momento do envio somado a uma passagem periódica em massa cobre os dois.

Pronto para colocar isso no ar? O plano gratuito inclui créditos para testar os dois caminhos, a referência da API tem a requisição /verify exata para o seu hook ou função serverless, e o verificador de e-mail gratuito permite testar pontualmente um único endereço antes de você escrever uma linha de código.