Como pesquisar itens do Outlook pelo valor do cabeçalho de internet com propriedade personalizada

Você precisa encontrar um e-mail específico com base em um valor no cabeçalho de internet, como um ID de rastreamento personalizado ou uma pontuação de spam. A pesquisa integrada do Outlook não permite pesquisar diretamente dentro dos campos de cabeçalho de internet. Este artigo explica como criar uma propriedade personalizada no Outlook que extrai um valor do cabeçalho de internet e, em seguida, usar essa propriedade para pesquisar e filtrar seus itens.

O método usa VBA do Outlook para ler o texto do cabeçalho, analisar o valor desejado e armazená-lo em um campo definido pelo usuário. Depois que a propriedade personalizada é preenchida, você pode pesquisá-la com a Pesquisa Instantânea ou criar uma pasta de pesquisa. Essa abordagem funciona para qualquer campo de cabeçalho, incluindo X-Spam-Status, Received, Authentication-Results ou cabeçalhos X personalizados.

Você aprenderá a escrever a macro VBA, atribuí-la a um botão e aplicar a propriedade personalizada aos seus critérios de pesquisa. Nenhum complemento de terceiros é necessário.

Como cabeçalhos de internet e propriedades personalizadas funcionam no Outlook

Cada e-mail contém cabeçalhos de internet que registram informações de roteamento, resultados de autenticação e metadados personalizados adicionados por servidores de e-mail. O Outlook armazena o cabeçalho completo na propriedade MAPI PR_TRANSPORT_MESSAGE_HEADERS (nome DASL: http://schemas.microsoft.com/mapi/proptag/0x007D001E). Essa propriedade não é exposta na interface padrão do Outlook.

Uma propriedade personalizada, também chamada de campo definido pelo usuário, é um campo de texto que você adiciona a uma pasta. Você pode gravar dados nela usando VBA e depois pesquisar esse campo com consultas de Pesquisa Instantânea como nome_do_campo:valor. O campo reside no esquema da pasta e persiste até que você o remova. Cada item na pasta pode ter um valor diferente para o mesmo campo personalizado.

Para pesquisar por valor de cabeçalho, você precisa de uma macro que faça três coisas:

• Ler o cabeçalho completo de um e-mail selecionado.
• Analisar a linha do cabeçalho alvo e extrair o valor.
• Gravar esse valor em uma propriedade personalizada no mesmo item.

Depois que a propriedade personalizada é preenchida, você pode pesquisar em toda a pasta usando essa propriedade como critério. Este método funciona apenas em itens que você já processou com a macro. Para novos e-mails recebidos, você pode executar a macro automaticamente usando o evento ItemAdd.

Passos para criar uma propriedade personalizada e pesquisar por valor de cabeçalho de internet

Siga estes passos para configurar a macro VBA, criar o campo personalizado e executar a extração em seus e-mails.

1. Habilitar a guia Desenvolvedor
   Abra o Outlook. Vá em Arquivo > Opções > Personalizar Faixa de Opções. Na coluna da direita, marque a caixa Desenvolvedor e clique em OK. A guia Desenvolvedor aparece na faixa de opções.
2. Abrir o Editor VBA
   Clique na guia Desenvolvedor e depois em Visual Basic. Como alternativa, pressione Alt+F11 no teclado.
3. Inserir um novo módulo
   No editor VBA, vá em Inserir > Módulo. Uma janela de código em branco é aberta.
4. Colar o código da macro
   Copie e cole o código a seguir na janela do módulo. Substitua X-Custom-Header pelo nome exato do cabeçalho que você deseja pesquisar.

   Sub ExtractHeaderToCustomField()
       Dim olApp As Outlook.Application
       Dim olExp As Outlook.Explorer
       Dim olSel As Outlook.Selection
       Dim olMail As Outlook.MailItem
       Dim strHeader As String
       Dim strHeaderName As String
       Dim strValue As String
       Dim intPos As Integer
       Dim intEndPos As Integer
       
       Set olApp = Outlook.Application
       Set olExp = olApp.ActiveExplorer
       Set olSel = olExp.Selection
       
       ' Altere para o cabeçalho que deseja extrair
       strHeaderName = "X-Custom-Header"
       
       If olSel.Count = 0 Then
           MsgBox "Selecione pelo menos um e-mail."
           Exit Sub
       End If
       
       For Each olMail In olSel
           ' Lê o cabeçalho de internet completo
           strHeader = olMail.PropertyAccessor.GetProperty(
               "http://schemas.microsoft.com/mapi/proptag/0x007D001E")
           
           ' Encontra a linha do cabeçalho alvo
           intPos = InStr(1, strHeader, strHeaderName & ":", vbTextCompare)
           If intPos > 0 Then
               ' Obtém o início do valor (após ": ")
               intPos = intPos + Len(strHeaderName) + 2
               intEndPos = InStr(intPos, strHeader, vbCrLf)
               If intEndPos = 0 Then intEndPos = Len(strHeader) + 1
               strValue = Mid(strHeader, intPos, intEndPos - intPos)
               strValue = Trim(strValue)
               
               ' Grava o valor em um campo definido pelo usuário
               olMail.UserProperties("HeaderValue") = strValue
               olMail.Save
           End If
       Next
       
       Set olMail = Nothing
       Set olSel = Nothing
       Set olExp = Nothing
       Set olApp = Nothing
       
       MsgBox "Concluído."
   End Sub
   

5. Adicionar o campo personalizado à pasta
   No Outlook, clique com o botão direito na pasta que deseja pesquisar (por exemplo, Caixa de Entrada). Escolha Propriedades. Vá para a guia Geral e clique no botão Novo em Campos disponíveis nesta pasta. Crie um novo campo de texto chamado HeaderValue e clique em OK duas vezes.
6. Executar a macro nos e-mails selecionados
   No Outlook, selecione um ou mais e-mails. Pressione Alt+F8 para abrir a caixa de diálogo Macros. Escolha ExtractHeaderToCustomField e clique em Executar. A macro lê o cabeçalho de cada e-mail, extrai o valor do cabeçalho especificado e o grava no campo HeaderValue.
7. Pesquisar usando a propriedade personalizada
   Clique dentro da caixa de Pesquisa Instantânea no topo da pasta. Digite HeaderValue:seuvalor substituindo seuvalor pelo valor real que deseja encontrar. O Outlook filtra a lista para mostrar apenas os itens onde o campo personalizado corresponde.

Automatizar a macro para novos e-mails

Para executar a extração automaticamente quando um novo e-mail chegar, use o evento Items.ItemAdd no VBA. Abra o editor VBA, clique duas vezes em ThisOutlookSession no Explorador de Projetos e cole o código abaixo. Substitua Inbox pelo nome da sua pasta alvo, se necessário.

Private WithEvents olInboxItems As Outlook.Items

Private Sub Application_Startup()
    Dim olNS As Outlook.NameSpace
    Set olNS = Application.GetNamespace("MAPI")
    Set olInboxItems = olNS.GetDefaultFolder(olFolderInbox).Items
End Sub

Private Sub olInboxItems_ItemAdd(ByVal Item As Object)
    If TypeOf Item Is Outlook.MailItem Then
        Dim olMail As Outlook.MailItem
        Set olMail = Item
        ' Chama a sub-rotina de extração
        Call ExtractHeaderToCustomFieldSingle(olMail)
    End If
End Sub

Sub ExtractHeaderToCustomFieldSingle(olMail As Outlook.MailItem)
    Dim strHeader As String
    Dim strHeaderName As String
    Dim strValue As String
    Dim intPos As Integer
    Dim intEndPos As Integer
    
    strHeaderName = "X-Custom-Header"
    
    On Error Resume Next
    strHeader = olMail.PropertyAccessor.GetProperty(
        "http://schemas.microsoft.com/mapi/proptag/0x007D001E")
    If Err.Number <> 0 Then Exit Sub
    
    intPos = InStr(1, strHeader, strHeaderName & ":", vbTextCompare)
    If intPos > 0 Then
        intPos = intPos + Len(strHeaderName) + 2
        intEndPos = InStr(intPos, strHeader, vbCrLf)
        If intEndPos = 0 Then intEndPos = Len(strHeader) + 1
        strValue = Mid(strHeader, intPos, intEndPos - intPos)
        strValue = Trim(strValue)
        
        olMail.UserProperties("HeaderValue") = strValue
        olMail.Save
    End If
End Sub

Problemas comuns e limitações ao pesquisar por valor de cabeçalho

A macro retorna um erro em alguns e-mails

Alguns e-mails, como convites de reunião, não possuem a propriedade PR_TRANSPORT_MESSAGE_HEADERS. Adicione uma instrução On Error Resume Next antes da chamada GetProperty para ignorar esses itens sem problemas. A macro acima já inclui isso na versão automatizada.

O campo personalizado não aparece nos resultados da pesquisa

A Pesquisa Instantânea indexa apenas campos que existem no esquema da pasta. Verifique se o nome do campo é exatamente HeaderValue e se você o adicionou à pasta correta. Se a pasta estiver em um escopo de pesquisa que exclui campos personalizados, use Ferramentas de Pesquisa > Opções de Pesquisa > Opções de Indexação para reconstruir o índice.

O valor do cabeçalho contém espaços extras ou quebras de linha

Os cabeçalhos podem ser quebrados em várias linhas. A macro acima extrai apenas a primeira linha do valor do cabeçalho. Para valores multilinha, modifique o loop para concatenar linhas que começam com espaço ou tabulação. Um analisador robusto leria todo o bloco de cabeçalho entre o nome do cabeçalho e o próximo cabeçalho.

A pesquisa não encontra o valor após executar a macro

A propriedade personalizada é preenchida apenas nos itens processados pela macro. Itens que não foram selecionados ou que não estão na pasta alvo não terão o campo. Execute a macro em todos os itens existentes na pasta ou use o evento ItemAdd automatizado para e-mails futuros.

Pesquisa Instantânea vs Pasta de Pesquisa: Comparação de métodos

Item	Consulta de Pesquisa Instantânea	Pasta de Pesquisa com Propriedade Personalizada
Esforço de configuração	Nenhum após a macro ser executada	Criar uma pasta de pesquisa uma vez
Atualizações em tempo real	Não, é necessário reexecutar a macro para novos itens	Sim, se a macro for executada no ItemAdd
Sintaxe da consulta	HeaderValue:valor	Localização Avançada com critério de campo personalizado
Visualização persistente	Temporária até limpar a pesquisa	A pasta permanece até ser excluída
Funciona com indexação	Sim, se o campo estiver indexado	Sim, mesmo índice

Agora você pode extrair qualquer valor de cabeçalho de internet para um campo personalizado do Outlook e pesquisar seus itens usando esse valor. A macro VBA oferece controle total sobre qual cabeçalho usar e em qual pasta atuar. Para pesquisas recorrentes, configure uma pasta de pesquisa com o campo HeaderValue como critério e ative a automação ItemAdd para mantê-la atualizada.

Para estender este método, modifique a macro para extrair vários valores de cabeçalho em campos personalizados separados. Você também pode exportar os valores para uma planilha do Excel usando VBA do Outlook e a propriedade Range.Value para análise posterior. O objeto PropertyAccessor pode ler muitas propriedades MAPI ocultas além de cabeçalhos, como ID da mensagem ou endereço de resposta.