Migrar do EWS para o Microsoft Graph

O cronograma de descontinuacao

A Microsoft bloqueara permanentemente o Exchange Web Services (EWS) para o Exchange Online em 1 de outubro de 2026, com remocao completa em 1 de abril de 2027. A descontinuacao afeta mais de 400 milhoes de licencas comerciais do Microsoft 365 no mundo todo. A Microsoft anunciou a aposentadoria pela primeira vez em setembro de 2023 e apertou o cronograma tres vezes desde entao.

De acordo com a pagina oficial de descontinuacao da Microsoft, as datas principais sao:

Se voce nao fizer nada, seu codigo baseado em EWS comeca a retornar erros a partir de outubro de 2026. O anuncio no TechCommunity confirma que a Microsoft definira EWSEnabled=False nos tenants que nao optaram pela extensao.

Exchange on-premises: nao afetado

A descontinuacao do EWS se aplica apenas ao Exchange Online (Microsoft 365). O Exchange Server 2016 e 2019 rodando on-premises mantem suporte completo ao EWS sem data de fim de vida anunciada. Organizacoes rodando Exchange hibrido -- que a Microsoft estima em aproximadamente 40% das implantacoes corporativas do Exchange -- enfrentam uma divisao: caixas de correio na nuvem devem migrar para o Graph API enquanto caixas de correio on-prem continuam usando EWS.

Essa realidade de protocolo duplo significa que ambientes hibridos precisam de dois fluxos de autenticacao e duas superficies de API, ou uma camada de abstracao que direciona requisicoes para o protocolo correto com base na localizacao da caixa de correio.

Modelo de autenticacao: NTLM/Basic para OAuth 2.0

Migrar do EWS para o Microsoft Graph requer substituir NTLM, Kerberos ou Basic Auth por OAuth 2.0 atraves de registros de aplicativo no Azure AD (agora Entra ID). A Microsoft descontinuou o Basic Auth para o Exchange Online em outubro de 2022, e o Graph API exige OAuth 2.0 desde o lancamento. Tokens de acesso expiram a cada 60-90 minutos, e tokens de atualizacao duram 90 dias antes de exigir reautenticacao.

• Registre um aplicativo no Azure AD com os escopos Mail.Read, Mail.Send, Calendars.ReadWrite ou outros
• Escolha um fluxo: authorization code (delegado) para contexto de usuario, client credentials (aplicacao) para apps daemon/servico
• Gerencie o ciclo de vida dos tokens: tokens de acesso expiram em 60-90 minutos, tokens de atualizacao em 90 dias
• Consentimento do administrador: permissoes em nivel de aplicacao precisam de aprovacao do administrador do tenant

O codigo abaixo mostra a diferenca entre o Basic Auth do EWS e a autenticacao OAuth 2.0 do Graph. O EWS precisava de apenas 3 linhas para conectar, enquanto o Graph precisa de um registro de aplicativo no Azure AD com os escopos corretos configurados antes que qualquer chamada de API funcione.

# EWS (antigo) - Basic Auth ou NTLM
$cred = Get-Credential
$service = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService
$service.Credentials = $cred
$service.Url = "https://outlook.office365.com/EWS/Exchange.asmx"

# Graph API (novo) - OAuth 2.0 com MSAL
Connect-MgGraph -Scopes "Mail.Read","Mail.Send"
$messages = Get-MgUserMessage -UserId "me" -Top 10

Lacunas de paridade de recursos (em abril de 2026)

O Microsoft Graph API cobre operacoes principais de email, calendario e contatos, mas ainda nao tem paridade completa com o EWS em pelo menos 4 areas: acesso a caixa de correio de arquivo, CRUD de pastas publicas, importacao/exportacao de caixas de correio e consultas delta de eventos recorrentes. A Microsoft vem fechando lacunas em uma cadencia trimestral desde 2024, mas nao se comprometeu com uma data para paridade completa de recursos.

A tabela abaixo mapeia cada recurso do EWS ao seu status no Graph API. Os dados vem da atualizacao da Microsoft no TechCommunity e cobrem as 10 capacidades do EWS mais comumente referenciadas:

A Microsoft lancou a Exchange Admin API como uma ponte temporaria para algumas lacunas. Mas nao ha data firme para quando todas as lacunas de paridade serao fechadas.

Tres caminhos de migracao

Organizacoes saindo do EWS tem tres opcoes: migrar diretamente para o Microsoft Graph API, registrar-se para uma extensao temporaria via AppID AllowList, ou adotar uma camada de abstracao agnostica de provedor. A escolha certa depende do cronograma, dos requisitos de Exchange hibrido e de quantos provedores seu aplicativo suporta. A maioria dos times precisa de 2-6 meses para uma migracao direta para o Graph, segundo a propria orientacao de planejamento da Microsoft.

Caminho 1: Migrar para o Microsoft Graph API

O caminho oficial substitui cada chamada EWS pelo equivalente no Graph. A Microsoft fornece um analisador de codigo EWS que escaneia sua base de codigo e mapeia operacoes EWS para equivalentes no Graph API. O analisador gera um relatorio CSV listando cada metodo EWS, sua contagem de chamadas e o endpoint Graph correspondente.

# EWS: Encontrar emails por assunto
$view = New-Object Microsoft.Exchange.WebServices.Data.ItemView(50)
$filter = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+ContainsSubstring(
  [Microsoft.Exchange.WebServices.Data.ItemSchema]::Subject, "invoice")
$results = $service.FindItems(
  [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Inbox, $filter, $view)

# Graph: Mesma operacao
$messages = Get-MgUserMessage -UserId "me" -Filter "contains(subject, 'invoice')" -Top 50

Vantagens: Permanece dentro do ecossistema Microsoft, acesso aos recursos mais recentes. Desvantagens: Registro de aplicativo no Azure AD, gerenciamento de tokens OAuth, sem suporte para provedores nao-Microsoft, lacunas de paridade de recursos.

Caminho 2: AppID AllowList temporaria

A AllowList estende o acesso ao EWS por 6 meses, de outubro de 2026 ate 1 de abril de 2027. Administradores do tenant devem registrar o client ID do aplicativo antes de agosto de 2026, ou a isencao nao tera efeito. A documentacao da Microsoft alerta que esta e uma extensao unica sem opcao de renovacao alem de abril de 2027.

# Verificar configuracoes atuais do EWS
Get-OrganizationConfig | Select-Object EwsEnabled, EwsAllowList

# Adicionar seu app a AllowList
Set-OrganizationConfig -EwsAllowList @{Add="your-app-client-id"}
Set-OrganizationConfig -EwsEnabled $true

Vantagens: Nenhuma mudanca de codigo necessaria imediatamente. Desvantagens: Apenas adia o problema por 6 meses. O EWS e removido permanentemente em 1 de abril de 2027.

Caminho 3: Usar uma abstracao unificada

Uma abstracao agnostica de provedor lida com o roteamento de EWS e Graph internamente, entao seu codigo nao muda quando a Microsoft aposenta um protocolo. O Nylas CLI conecta ao Exchange Online, Exchange on-prem, Gmail, Outlook, Yahoo, iCloud e IMAP atraves de uma unica interface. Os mesmos comandos funcionam em todos os 6 provedores sem logica especifica de protocolo.

# Instalar
brew install nylas/nylas-cli/nylas

# Autenticar (lida com OAuth, EWS, Graph internamente)
nylas auth config

# Ler email -- funciona independente de a caixa de correio ser
# Exchange Online (Graph), Exchange on-prem (EWS) ou Gmail
nylas email list --limit 10

# Pesquisar
nylas email search "invoice" --limit 50

# Enviar
nylas email send \
  --to "colleague@company.com" \
  --subject "Report" \
  --body "The report is ready: <report-download-link>"

Vantagens: Sem codigo especifico de protocolo, sem registro de aplicativo no Azure AD, funciona com todos os provedores, on-prem e nuvem atraves de uma unica interface. Desvantagens: Dependencia externa. Requer chave de API Nylas.

Comparacao lado a lado

As tres abordagens diferem em complexidade de autenticacao, cobertura de provedores e esforco de migracao. O EWS suportava 3 metodos de autenticacao (NTLM, Kerberos, Basic), o Graph API exige OAuth 2.0 exclusivamente, e o Nylas CLI lida com autenticacao atraves de um unico comando de configuracao. A tabela abaixo compara os tres em 7 preocupacoes operacionais que afetam o planejamento de migracao.

Exchange hibrido: o problema do codigo duplo

Ambientes Exchange hibridos devem manter dois caminhos de codigo separados apos outubro de 2026: Microsoft Graph para caixas de correio na nuvem e EWS para Exchange Server on-premises. O Microsoft Graph nao tem suporte para Exchange Server on-prem, o que significa que organizacoes com implantacoes divididas nao podem consolidar em uma unica API Microsoft. De acordo com a documentacao de ambiente hibrido da Microsoft, configuracoes hibridas representam uma parcela significativa das implantacoes corporativas do Exchange.

Essa divisao de protocolo duplo forca dois fluxos de autenticacao (Azure AD OAuth para Graph, NTLM ou Kerberos para EWS on-prem), duas superficies de API e dois conjuntos de tratamento de erros no mesmo aplicativo. A plataforma Nylas lida com esse roteamento internamente -- ela detecta se uma caixa de correio esta na nuvem ou on-prem e usa o protocolo apropriado sem mudancas de codigo.

Checklist de migracao

Uma migracao completa do EWS envolve autenticacao, superficie de API, tratamento de erros e testes em todos os tipos de licenca afetados. A Microsoft recomenda iniciar a migracao pelo menos 3 meses antes do prazo de outubro de 2026 para acomodar o registro de aplicativo no Azure AD, consentimento do administrador e ciclos de teste. Os 6 passos abaixo cobrem o processo de ponta a ponta, da auditoria ate a implantacao em producao.

1. Audite seu uso do EWS -- Execute o analisador de codigo EWS da Microsoft para inventariar cada chamada EWS
2. Verifique lacunas de paridade -- Compare suas operacoes EWS com a tabela de lacunas de recursos acima
3. Registre seu aplicativo antes de agosto de 2026 -- Se precisar de mais tempo, adicione seu app a AllowList
4. Teste com licencas F1/F3 primeiro -- Estas foram bloqueadas em marco de 2026, entao ja estao no novo comportamento
5. Planeje para hibrido -- Se voce tem Exchange on-prem, decida como lidar com a divisao de protocolo duplo
6. Monitore as atualizacoes da Microsoft -- Lacunas de paridade de recursos estao sendo fechadas trimestralmente

Perguntas frequentes

A descontinuacao do EWS levanta perguntas sobre cronogramas, impacto on-premises, lacunas de recursos e alternativas de migracao. Estas sao as 4 perguntas mais comuns de desenvolvedores planejando sua migracao, baseadas nos topicos discutidos nos foruns TechCommunity da Microsoft e na documentacao oficial de descontinuacao.

Quando o EWS sera aposentado para o Exchange Online?

A Microsoft bloqueia requisicoes EWS de apps nao-Microsoft a partir de 1 de outubro de 2026. Tenants que configurarem uma AppID AllowList antes de agosto de 2026 recebem uma isencao temporaria. Todo o acesso EWS e removido permanentemente em 1 de abril de 2027.

O EWS esta sendo descontinuado para o Exchange Server on-premises?

Nao. O EWS continua totalmente suportado para o Exchange Server 2016 e 2019. A descontinuacao afeta apenas o Exchange Online (Microsoft 365).

Quais recursos do EWS estao faltando no Graph API?

Em abril de 2026, o Graph API nao possui acesso a caixa de correio de arquivo, CRUD de pastas publicas, importacao/exportacao de caixas de correio e suporte completo a delta de eventos recorrentes. A Microsoft esta fechando lacunas trimestralmente, mas nao se comprometeu com uma data para paridade completa.

Posso pular a migracao completamente?

Sim, se voce usar uma camada de abstracao. A plataforma Nylas conecta ao Exchange Online, Exchange on-prem e 4 outros provedores atraves de uma unica interface. Descontinuacoes no lado do provedor nao exigem mudancas de codigo da sua parte.

Proximos passos

Apos planejar seu caminho de migracao do EWS, os guias abaixo cobrem operacoes especificas do Exchange atraves do Nylas CLI. Cada guia inclui comandos testados, solucao de problemas especificos do provedor e exemplos de codigo para os 6 provedores suportados.

• Checklist de aposentadoria do EWS -- inventarie scripts arriscados e execute o teste de verificacao do Exchange com 2 comandos
• Listar emails do Exchange pela CLI -- leia e pesquise caixas de correio do Exchange sem EWS ou Graph
• Gerenciar calendario do Exchange pela CLI -- crie, atualize e exclua eventos
• Substituir Send-MgUserMessage -- migre dos cmdlets Graph PowerShell
• Gerenciar email do Office 365 com PowerShell -- leia, pesquise e organize sua caixa de entrada M365
• Enviar email pelo terminal -- o guia de envio de email multi-provedor
• Referencia completa de comandos -- cada flag e subcomando documentado