Verifique e-mails do Gravity Forms

O Gravity Forms é o burro de carga dos sites WordPress sérios — aplicações de múltiplas páginas, fluxos de cadastro, pedidos de orçamento — e cada um deles tem um campo de e-mail que confere o formato e nada mais. Para verificar e-mails do Gravity Forms você não instala um plugin de marca; você se conecta ao envio, chama uma API de verificação e ou rejeita um endereço inválido na hora, ou o marca depois do fato. Este guia cobre os três caminhos suportados: um filtro de validação em PHP que bloqueia endereços não entregáveis e descartáveis antes de a entrada ser salva, o Webhooks Add-On para marcar-e-suprimir de forma assíncrona, e uma exportação por CSV para limpar sua tabela de entradas em massa.

A resposta curta#

O Gravity Forms oferece dois pontos de integração, e por qual deles você opta depende de você querer barrar um endereço inválido ou apenas reagir a ele:

1. Em tempo real, na hora — um pequeno trecho de PHP no filtro gform_field_validation chama a API da Qualisend enquanto o formulário está sendo validado e retorna um erro de campo que o visitante vê. Este é o único lugar em que você pode rejeitar um endereço antes que ele se torne uma entrada.
2. Em tempo real, assíncrono — o Webhooks Add-On envia um POST de cada entrada para uma URL que você controla depois que ela é salva. Ele não consegue mostrar um erro na hora, mas é perfeito para marcar, direcionar ou suprimir endereços não entregáveis antes que cheguem à sua ferramenta de e-mail.
3. Em massa — exporte as entradas armazenadas para CSV e passe-as pelo verificador em massa da Qualisend periodicamente. Sem código, funciona em qualquer licença que armazene entradas.

Este artigo é o complemento específico do Gravity Forms para o guia mais amplo de verificar e-mails em formulários WordPress, que cobre o Contact Form 7 e o WPForms com os mesmos padrões. Se você usa mais de um plugin de formulários, comece por lá; se você é 100% Gravity Forms, tudo o que você precisa está abaixo.

Por que o campo de e-mail do Gravity Forms não basta#

O tipo de campo email valida que o que alguém digitou parece um endereço — um @, um domínio, sem espaços perdidos. Isso é uma checagem de formato, e formato não é entregabilidade. jane@gmial.com passa. Assim como throwaway@mailinator.com, e assim como uma caixa de correio de aparência real em um domínio que expirou seis meses atrás. Nenhum deles é pego até você enviar, e a essa altura um endereço morto é um hard bounce corroendo sua taxa de rejeição e a reputação do remetente.

A verificação de verdade acrescenta as camadas que o Gravity Forms não tem: uma consulta de DNS/MX, uma sondagem SMTP da caixa de correio e sinalizadores para endereços descartáveis, de função (role), gratuitos e catch-all. Se o pipeline é novidade para você, como funciona a verificação de e-mail destrincha cada checagem e por que ela importa.

Verifique e-mails do Gravity Forms no envio#

O Gravity Forms expõe um filtro de validação no nível do campo que dispara durante a validação, antes de a entrada ser salva — o que significa que você pode invalidar o campo de e-mail e entregar ao visitante uma mensagem de erro para corrigir. Esse é o filtro gform_field_validation, e é o hook certo quando você quer uma barreira na hora, e não uma limpeza posterior.

O callback recebe o $result atual do campo (com um sinalizador is_valid e uma message), o $value enviado, o $form e o $field. Você chama a API e, se o veredito for ruim, vira is_valid para false e define a mensagem. Mantenha a chave da API em uma constante no wp-config.php — nunca em uma configuração de formulário, em um arquivo de tema ou em qualquer JavaScript de front-end:

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

add_filter( 'gform_field_validation', 'qs_gf_verify_email', 10, 4 );

function qs_gf_verify_email( $result, $value, $form, $field ) {
    // Only run on email fields that already passed Gravity Forms' own checks.
    if ( $field->type !== 'email' || ! $result['is_valid'] ) {
        return $result;
    }

    // An email field with "confirm" enabled hands back an array.
    $email = is_array( $value ) ? rgar( $value, 0 ) : $value;
    $email = trim( (string) $email );
    if ( $email === '' ) {
        return $result; // let the field's own required-field check handle empties
    }

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

    // Fail open: a transient error must never block a real applicant.
    if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) !== 200 ) {
        return $result;
    }

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

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

    return $result;
}

Três coisas sustentam este trecho, e são as mesmas três em qualquer linguagem: mantenha a chave no servidor, limite a requisição com um timeout curto e falhe de forma aberta — se a chamada der erro, estourar o tempo ou retornar algo diferente de 200, deixe o envio passar. Uma API de verificação é um filtro de qualidade, não uma barreira de autenticação, e perder um lead real por uma queda momentânea é o pior desfecho. Para a mecânica da requisição em si — cabeçalhos, tratamento de erros, o formato da resposta result — o guia de validação de e-mail em PHP percorre a mesma chamada de ponta a ponta.

Uma observação sobre escopo: deixar o filtro global (como acima) verifica o campo de e-mail em todos os formulários. Para mirar em um único formulário, use a variante específica de formulário-e-campo gform_field_validation_{form_id}_{field_id}, ou adicione uma verificação antecipada if ( $form['id'] !== 5 ) return $result;. E se você precisa validar vários campos de uma vez — digamos, só verificar quando outro campo estiver preenchido — o filtro gform_validation, no nível do formulário, dá acesso ao $form inteiro e permite marcar campos individuais como inválidos; o filtro de campo acima é mais simples e suficiente para uma barreira de um único e-mail.

Agindo sobre o veredito#

A API retorna um objeto result com um status de deliverable, risky, undeliverable ou unknown, além de um score de 0 a 100, um código reason e sub-sinalizadores para disposable, role, free e catch_all — o mesmo $verdict que o trecho lê. Mapeie cada um para uma ação do formulário:

Em um formulário ao vivo, apoie-se nas checagens locais rápidas — sintaxe, domínio, descartável, função (role) — porque elas retornam depressa e pegam a maior parte do lixo sem fazer o visitante esperar. A sondagem SMTP da caixa de correio, mais pesada, se encaixa melhor no caminho em massa abaixo, onde alguns segundos de latência não fazem diferença para ninguém.

O caminho do Webhooks Add-On#

Se PHP personalizado não é uma opção — ou você só precisa manter endereços mortos fora da sua ferramenta seguinte, não bloquear o formulário — o Webhooks Add-On do Gravity Forms faz isso sem código. É um add-on licenciado (incluído nas licenças de nível mais alto do Gravity Forms, então confira seu plano), e ele dispara uma requisição HTTP configurável como um feed após cada envio.

Nas Settings → Webhooks do formulário, adicione um feed: defina o tipo de requisição como POST, o formato como JSON, aponte a URL para um endpoint que você controla e mapeie o campo de e-mail para o corpo da requisição. Como você não pode colocar com segurança uma chave da API nos cabeçalhos do próprio webhook e depois chamar a Qualisend a partir de um terceiro, o padrão limpo é apontar o webhook para uma pequena função serverless sua — a configuração exata do guia de verificação serverless no cadastro. Essa função guarda a chave, recebe o payload do Gravity Forms, extrai o e-mail, chama a API e age sobre o veredito.

O detalhe é o timing. O Webhooks Add-On dispara depois que a entrada já foi salva, então roda de forma assíncrona e não consegue mostrar um erro de validação ao visitante — não há rejeição na hora nesse caminho. O que ele consegue fazer é verificar em segundos e direcionar com base no resultado: adicionar uma tag no seu CRM, pular o autorresponder para um endereço não entregável, ou suprimi-lo antes que ele chegue à sua plataforma de e-mail. Se você precisa que o visitante veja e corrija um endereço inválido, use o filtro de validação acima; se tudo o que você quer é higiene downstream, o webhook basta.

Verifique em massa uma exportação CSV do Gravity Forms#

Nem todo formulário precisa de uma barreira em tempo real, e você também terá um acervo de entradas coletadas antes de você adicionar uma. Para ambos, o caminho sem código é limpar em lotes:

1. Exporte as entradas para CSV. No admin do Gravity Forms, abra Forms → Import/Export → Export Entries, escolha o formulário, inclua a coluna de e-mail e baixe o arquivo. Você recebe uma linha por entrada, com o endereço em sua própria coluna.
2. Verifique o CSV em massa. Faça upload dele no verificador em massa da Qualisend, que roda o pipeline completo — MX, a sondagem SMTP e os sinalizadores de descartável/função/catch-all — em cada linha e devolve um arquivo pontuado com um status e um reason por endereço.
3. Filtre e sincronize. Mantenha os deliverable, revise os risky e descarte os undeliverable antes de importar os sobreviventes para sua plataforma de e-mail.

Este é o mesmo ciclo de exportar-verificar-reimportar de qualquer limpeza de lista, só que originado da sua tabela de entradas do Gravity Forms — o guia para limpar uma lista de e-mails cobre tudo. Rode o acervo uma vez e depois deixe um hook no momento do envio manter a lista limpa dali em diante.

Em tempo real, em massa ou ambos#

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

• Tempo real é prevenção. Um erro de digitação pego no envio é um lead salvo com uma correção de uma linha; um domínio morto rejeitado ali nunca vira um hard bounce.
• Massa é limpeza. Endereços se deterioram — as pessoas trocam de emprego, os domínios expiram — então até uma lista perfeitamente barrada precisa de reverificação periódica.

Qual caminho em tempo real você pode usar depende da sua licença e da sua familiaridade com código: o filtro de validação precisa de um trecho de PHP, mas dá a você um bloqueio na hora, enquanto o Webhooks Add-On precisa de um nível pago, mas não de código, e cuida da marcação assíncrona. Combinar o que você escolher com uma passagem em massa ocasional é a estratégia inteira.

Perguntas frequentes#

O Gravity Forms consegue verificar endereços de e-mail sozinho?#

Apenas o formato. O tipo de campo email confirma que um endereço está bem formado — tem um @ e um domínio —, mas não resolve registros MX nem sonda a caixa de correio, de modo que um endereço com erro de digitação, descartável ou há muito inativo que parece válido ainda passa. A verificação de verdade precisa das camadas de DNS e SMTP que um serviço como a Qualisend acrescenta por cima, chamado a partir de um filtro de validação, de um webhook ou de um job em massa por CSV.

Um webhook do Gravity Forms consegue rejeitar um endereço inválido na hora?#

Não. O Webhooks Add-On dispara depois que a entrada é salva, então roda de forma assíncrona e não consegue mostrar um erro de validação ao visitante. Ele é ideal para marcar, direcionar 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 vê e pode corrigir, use o filtro gform_field_validation com o trecho de PHP deste guia.

Qual hook do Gravity Forms devo usar para verificar no envio?#

Use gform_field_validation para um único campo de e-mail — ele dispara durante a validação, recebe o valor do campo e permite retornar um erro na hora. Se você precisa validar vários campos ou executar a checagem condicionalmente no formulário inteiro, use o filtro gform_validation, no nível do formulário, e marque campos individuais como inválidos. Ambos rodam no servidor antes de a entrada ser salva, então ambos podem bloquear.

Existe um add-on nativo da Qualisend para o Gravity Forms?#

Por enquanto não — nossas integrações nativas de plataforma estão sendo reconstruídas, e um conector para o Gravity Forms está no roadmap. Até que ele chegue, as abordagens suportadas são as três deste guia: chamar a API REST a partir do filtro de validação, de uma função serverless por trás do Webhooks Add-On, ou exportar as entradas para CSV e verificar em massa. Todas usam diretamente a API documentada.

Pronto para colocar isso no ar? O plano gratuito inclui créditos para testar todos os caminhos, a referência da API tem a requisição /verify exata para o seu filtro de validação 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 PHP.