Adeus, Get-MessageTrace: migrando scripts do Exchange Online para o Get-MessageTraceV2

Adeus, Get-MessageTrace: como migrar seus scripts de Exchange Online para o Get-MessageTraceV2 antes da depreciação total

Se você administra Exchange Online e tem scripts PowerShell que usam Get-MessageTrace ou Get-MessageTraceDetail para investigar entrega de e-mail, hoje é um bom dia para parar e revisar essas automações. A Microsoft já começou a desativar os cmdlets legados e a interface antiga de Message Trace no Exchange Admin Center, e a substituição definitiva — Get-MessageTraceV2 e Get-MessageTraceDetailV2 — já está em disponibilidade geral.[1][2]

Neste artigo, explico o que mudou, por que isso importa para quem mantém scripts de troubleshooting de mail flow, e como adaptar as consultas mais comuns para a nova sintaxe.

O que está mudando, e quando

A nova experiência de Message Trace entrou em preview público em dezembro de 2024 e atingiu disponibilidade geral no Exchange Admin Center (caminho: Mail flow > Message Trace), trazendo interface modernizada, filtros mais detalhados de status de entrega (como "Quarentenado" e "Filtrado como spam"), colunas personalizáveis por conta e timestamps que respeitam o fuso horário configurado no admin.[2]

O cronograma de depreciação, segundo o Message Center da Microsoft (MC1092458), é direto:

• A partir de 1º de setembro de 2025: começou a depreciação da interface legada de Message Trace no EAC e dos cmdlets Get-MessageTrace e Get-MessageTraceDetail.
• A partir de 18 de março de 2026: começa a depreciação do suporte do Reporting Web Service para dados de Message Trace (usado por integrações mais antigas).[1]

Ou seja: scripts que ainda chamam Get-MessageTrace continuam funcionando por um período de transição, mas a Microsoft já deixou claro que é questão de tempo até a remoção completa. Quem só for atualizar script depois que parar de funcionar vai descobrir isso em produção, no peor momento possível — durante um incidente de entrega de e-mail.

Diferenças práticas entre o cmdlet antigo e o novo

A sintaxe do Get-MessageTraceV2 é parecida com a do Get-MessageTrace, mas tem pontos de atenção importantes:

• Sem paginação por -Page/-PageSize. O novo cmdlet não suporta esses parâmetros. Para buscar resultados além do limite, usa-se -StartingRecipientAddress combinado com -EndDate, pegando os valores de Recipient address e Received Time do último registro da consulta anterior.[4]
• Janela de consulta mais ampla, mas limitada por intervalo. A nova experiência permite consultar até 90 dias de histórico, porém cada consulta individual é limitada a um intervalo de 10 dias — é preciso fatiar consultas maiores.[2]
• Boas práticas recomendadas pela própria Microsoft: usar -ResultSize para controlar o volume de retorno, ser o mais específico possível (reduzir o intervalo entre -StartDate e -EndDate e usar filtros como -SenderAddress), e usar -MessageTraceId sempre que possível — obrigatório, inclusive, para mensagens enviadas a mais de 1.000 destinatários.[4]
• Timestamps em UTC. A saída do Get-MessageTraceV2 vem em UTC, o que pode exigir ajuste se seu script compara horários locais.[4]

Exemplo prático: localizar o caminho de um e-mail

Consulta básica, filtrando por remetente e intervalo de datas:

Connect-ExchangeOnline

Get-MessageTraceV2 -SenderAddress [e-mail] `
    -StartDate 11/01/2026 -EndDate 11/03/2026

Para detalhar o percurso completo de uma mensagem específica (equivalente ao antigo Get-MessageTraceDetail), use o MessageTraceId retornado na consulta acima e passe para o Get-MessageTraceDetailV2:

Get-MessageTraceV2 -MessageTraceId 2bbad36a-a467-4c7b-a82f-4b307fff549f `
    -SenderAddress [e-mail] `
    -StartDate 11/01/2026 -EndDate 11/03/2026 |
    Get-MessageTraceDetailV2

Esse padrão de pipeline — rodar o Get-MessageTraceV2 e encadear direto no Get-MessageTraceDetailV2 — é a forma recomendada pela documentação oficial para investigar o status detalhado (recebido, entregue, atrasado, bloqueado, em quarentena) de uma mensagem específica.[5]

Atualizando scripts de automação e monitoramento

Se você tem rotinas agendadas (Task Scheduler, Azure Automation, runbooks) que chamam Get-MessageTrace para gerar relatórios de entrega, SLA de e-mail ou alertas de bounce, o caminho prático é:

1. Localize todas as referências aos cmdlets legados nos seus repositórios de script:

   Get-ChildItem -Path C:\Scripts -Filter *.ps1 -Recurse |
       Select-String -Pattern 'Get-MessageTrace\b|Get-MessageTraceDetail\b'

1. Troque o nome do cmdlet para a versão V2 e remova parâmetros de paginação (-Page, -PageSize), substituindo por laços que usam -StartingRecipientAddress/-EndDate quando o volume de resultados for alto.
2. Teste em um intervalo pequeno primeiro (poucas horas) antes de rodar contra 90 dias de histórico — lembre que cada chamada é limitada a 10 dias de janela.
3. Valide o fuso horário na saída, já que o V2 trabalha em UTC.

Vale reforçar: isso não é apenas um alerta de depreciação. Esse processo de migração de script é também uma boa oportunidade para revisar se o relatório/alerta ainda faz sentido, e se as novas colunas de status mais granulares (como diferenciar "Filtrado como spam" de "Quarentenado") podem melhorar seus relatórios de mail flow.

Conclusão

A troca do Get-MessageTrace legado pelo Get-MessageTraceV2 é uma daquelas migrações pequenas em esforço, mas fáceis de esquecer até o dia em que o script para de funcionar sem aviso. Os pontos centrais para levar desta leitura:

• O cronograma já está em curso: cmdlets legados em depreciação desde setembro de 2025, com o suporte via Reporting Web Service encerrando em março de 2026.[1]
• Get-MessageTraceV2 não tem paginação por página/tamanho — o padrão agora é -StartingRecipientAddress + -EndDate.[4]
• Consultas são limitadas a janelas de 10 dias, dentro de um histórico de até 90 dias.[2]
• Priorize -MessageTraceId, -ResultSize e filtros específicos para consultas mais rápidas e confiáveis, como recomenda a própria documentação da Microsoft.[4][5]

Se você mantém scripts de troubleshooting ou relatórios de mail flow no seu ambiente, essa é uma boa quinta à tarde para rodar aquele Select-String no repositório de scripts e ver quantas referências ao cmdlet antigo ainda estão pendentes.

📚 Recursos recomendados

• Guía del administrador de Microsoft Exchange Server (Subscription Edition) — guia prático de administração do Exchange Server/Exchange Online, útil como referência de consulta para quem lida no dia a dia com mail flow e troubleshooting de mensagens.

Sources

[1] https://mc.merill.net/message/MC1092458 — MC1092458 Message Center - New Message Trace GA, legacy retire
[2] https://petri.com/new-message-trace-exchange-online — Petri - New Message Trace Experience Coming to Exchange Online
[4] https://learn.microsoft.com/en-us/powershell/module/exchangepowershell/get-messagetracev2 — Microsoft Learn - Get-MessageTraceV2 cmdlet reference
[5] https://learn.microsoft.com/en-us/powershell/module/exchangepowershell/get-messagetracedetailv2 — Microsoft Learn - Get-MessageTraceDetailV2 cmdlet reference