Notificações por e-mail automáticas para agendamentos na Vila Prudente: guia técnico

Você já perdeu um agendamento porque o cliente não recebeu a confirmação por e-mail? Na Vila Prudente, onde a demanda por serviços locais cresce rápido, uma falha na comunicação automática pode significar agenda vazia e prejuízo direto. O WordPress oferece todas as peças necessárias para resolver isso, mas exige arquitetura correta — não apenas instalar um plugin e torcer para funcionar.

O segredo está em separar responsabilidades: o gatilho (quando disparar), o transporte (como entregar) e o conteúdo (o que comunicar). Misturar essas camadas no mesmo arquivo de funções cria débito técnico que custa caro para manter. Vamos estruturar uma solução profissional, escalável e auditável.

Arquitetura de disparo: hooks certos no momento certo

O erro mais comum é usar ‘wp_mail’ direto no ‘save_post’ sem verificar transição de status. Isso dispara e-mails em autosave, quick edit e até na lixeira. O padrão robusto compara o status anterior com o novo:

add_action( 'transition_post_status', 'dvwp_enviar_confirmacao_agendamento', 10, 3 );
function dvwp_enviar_confirmacao_agendamento( $new_status, $old_status, $post ) {
    if ( 'agendamento' !== $post->post_type ) return;
    if ( 'publish' !== $new_status || 'publish' === $old_status ) return;
    
    // Agenda envio assíncrono
    as_enqueue_async_action( 'dvwp_enviar_email_agendamento', [ 'post_id' => $post->ID ] );
}

Note o uso do Action Scheduler (as_enqueue_async_action). Ele desacopla o envio da resposta HTTP, evita timeout e permite retentativas automáticas. Se seu projeto não usa WooCommerce, instale a biblioteca standalone via Composer: composer require woocommerce/action-scheduler.

Transporte confiável: além do PHP mail()

A função nativa wp_mail() usa mail() do servidor — sem autenticação, sem rastreamento, com reputação compartilhada. Em produção, configure WP Mail SMTP apontando para provedor transacional. No wp-config.php ou plugin de configuração:

define( 'WP_MAIL_SMTP_HOST', 'smtp.sendgrid.net' );
define( 'WP_MAIL_SMTP_PORT', 587 );
define( 'WP_MAIL_SMTP_AUTH', true );
define( 'WP_MAIL_SMTP_USER', 'apikey' );
define( 'WP_MAIL_SMTP_PASS', 'SG.xxxxx' );
define( 'WP_MAIL_SMTP_SECURE', 'tls' );

Valide com o teste nativo do plugin (Tools → WP Mail SMTP → Email Test). Depois, monitore métricas no painel do provedor: taxa de entrega > 99%, bounce < 0,5%, spam complaint < 0,1%.

Templates dinâmicos por tipo de serviço

Cada serviço (desentupimento, manutenção preventiva, inspeção) exige informações diferentes no e-mail. Crie um Custom Post Type email_template com campos ACF: servico_relacionado (taxonomy), assunto, corpo_html, corpo_texto. No disparo:

function dvwp_get_template_por_servico( $servico_slug ) {
    $args = [
        'post_type' => 'email_template',
        'tax_query' => [[
            'taxonomy' => 'tipo_servico',
            'field' => 'slug',
            'terms' => $servico_slug,
        ]],
        'posts_per_page' => 1,
    ];
    $query = new WP_Query( $args );
    return $query->posts[0] ?? null;
}

Substitua placeholders com wp_kses_post para sanitizar HTML ou wp_strip_all_tags para versão texto. Mantenha versão texto puro para clientes que desabilitam HTML — acessibilidade e entregabilidade agradecem.

Logs, auditoria e retentativa inteligente

Não confie apenas no log do provedor SMTP. Crie tabela customizada:

No callback assíncrono, atualize status para ‘sent’ ou incremente ’tentativas’ e agende nova execução com backoff exponencial:

add_action( 'dvwp_enviar_email_agendamento', 'dvwp_processar_envio_email', 10, 1 );
function dvwp_processar_envio_email( $args ) {
    $post_id = $args['post_id'];
    $log_id = $args['log_id'] ?? dvwp_criar_log_inicial( $post_id );
    
    try {
        $enviado = wp_mail( $to, $subject, $message, $headers );
        if ( $enviado ) {
            dvwp_atualizar_log( $log_id, 'sent' );
        } else {
            throw new Exception( 'wp_mail retornou false' );
        }
    } catch ( Throwable $e ) {
        $tentativas = dvwp_incrementar_tentativa( $log_id );
        if ( $tentativas < 5 ) {
            $delay = min( 300 * pow( 2, $tentativas - 1 ), 7200 ); // 5min a 2h
            as_schedule_single_action( time() + $delay, 'dvwp_enviar_email_agendamento', [ 'post_id' => $post_id, 'log_id' => $log_id ] );
        } else {
            dvwp_atualizar_log( $log_id, 'failed', $e->getMessage() );
            dvwp_notificar_admin_falha( $log_id, $e );
        }
    }
}

Integração com área do cliente e histórico

O e-mail não vive isolado. O cliente deve ver o mesmo conteúdo na área logada. Se você já implementou área do cliente para histórico de manutenções em Moema, reutilize o endpoint REST que lista agendamentos e adicione campo email_enviado: true/false baseado na tabela de logs. Isso evita duplicidade e dá transparência.

Para equipes que gerenciam múltiplos prestadores, o fluxo de notificação pode seguir regras de roteamento: e-mail para o técnico responsável, cópia para gestor, SMS para urgências. Essa lógica pertence a uma camada de serviço (Dvwp_Notification_Service) injetada via container PSR-11, não espalhada em hooks.

Testes automatizados e staging seguro

Escreva testes PHPUnit para o disparo:

public function test_email_disparado_apenas_no_publish() {
    $post = $this->factory->post->create([ 'post_type' => 'agendamento', 'post_status' => 'draft' ]);
    $this->assertFalse( dvwp_deve_enviar_email( $post ) );
    
    wp_update_post([ 'ID' => $post, 'post_status' => 'publish' ]);
    $this->assertTrue( dvwp_deve_enviar_email( get_post( $post ) ) );
    
    wp_update_post([ 'ID' => $post, 'post_status' => 'publish' ]); // segunda vez
    $this->assertFalse( dvwp_deve_enviar_email( get_post( $post ) ) );
}

Em staging, force redirecionamento de todos os e-mails para Mailtrap via filtro:

add_filter( 'wp_mail', function( $args ) {
    if ( defined( 'WP_STAGING' ) && WP_STAGING ) {
        $args['to'] = 'teste@mailtrap.io';
        $args['headers'][] = 'X-Original-To: ' . $args['to'];
    }
    return $args;
} );

Checklist de entrega para o cliente final

Antes de liberar em produção, valide:

1. SPF, DKIM, DMARC alinhados no domínio do remetente
2. Teste de renderização no Litmus ou Email on Acid (Outlook, Gmail, iOS, Android)
3. Link de descadastro funcional e processado em < 48h (LGPD)
4. Assunto < 50 caracteres, pré-header otimizado
5. Imagens com alt text, largura máxima 600px, hospedadas em CDN com HTTPS
6. Versão texto puro legível sem o HTML

Conclusão prática

Notificações automáticas confiáveis exigem mais que wp_mail(): precisam de arquitetura assíncrona, transporte autenticado, templates versionados, logs auditáveis e testes automatizados. Implemente camada por camada, meça métricas de entregabilidade semanalmente e trate e-mail como feature crítica — porque para o cliente da Vila Prudente, é o único canal de confirmação que ele tem. Para ver como isso se integra a um fluxo completo de agendamento, consulte o case de consultor WordPress resolve logística em oficina mecânica em Americanópolis e o guia de autenticação via Application Passwords na REST API.

Dez Jato na Vila Prudente

Checklist prático

Perguntas frequentes