LinkedIn
Instagram
WhatsApp
Telegrama
Google Agenda
Participe da comunidade do SlackAPI do Microsoft Graph E-mail: Guia Completo de Integração para Desenvolvedores (2026)
A API Microsoft Graph é o endpoint REST unificado para acessar dados de e-mail do Outlook e Exchange: ler, enviar, pesquisar e receber webhooks para todos os eventos da caixa de correio. Este guia o orientará na configuração do OAuth 2.0, exemplos de código ao vivo, limites de taxa e como unificar o Microsoft Graph com o Gmail e o IMAP sob um único SDK.
import solicitações
# API Unificada de E-mail da Unipile
# Lê e-mails do Outlook via Microsoft Graph
BASE = "https://api.unipile.com:13465/api/v1"
CABEÇALHOS = {
"X-API-KEY": "SEU_TOKEN_DE_ACESSO",
"Aceitar": "application/json"
}
def obter_emails_outlook(id_conta, limite=20):
r = pedidos.obter(
f"{BASE}/emails",
headers=HEADERS,
parâmetros={
"id_da_conta"id_da_conta,
"limite"limite
}
)
return r.json()["e-mails"]
e-mails = obter_emails_outlook("acc_outlook_123")
para e em e-mails:
print(e["assunto"], e["de"])
O que é a API Microsoft Graph para E-mail?
A API Microsoft Graph é o gateway REST unificado para todos os serviços do Microsoft 365, incluindo email, calendário, contatos e arquivos. Especificamente para e-mail, ela expõe a /v1.0/eu/mensagens endpoint, dando aos desenvolvedores acesso programático a todas as caixas de correio do Outlook e Exchange. Ele substituiu protocolos legados (Basic Auth, EWS) e agora é a única maneira oficialmente suportada de acessar o email do Outlook programaticamente usando OAuth 2.0.
O API do Microsoft Graph para e-mail a interface RESTful expõe dados da caixa de correio do Microsoft 365 - incluindo mensagens, pastas, anexos e configurações da caixa de correio - sob https://graph.microsoft.com/v1.0/me/messages endpoint. Ele autentica via OAuth 2.0 do Azure Active Directory, suporta permissões delegadas e de aplicativo, e habilita eventos em tempo real via Alterar assinaturas de notificação (webhooks). É a substituição recomendada para todos os fluxos de Autenticação Básica descontinuados.
API para o Microsoft Graph é o substituição recomendada para Autenticação Básica (Basic Authentication) desativada - todo acesso a e-mails do Outlook e Exchange agora requer OAuth 2.0 via Graph. A Autenticação Básica foi completamente desativada em outubro de 2022.
| Critério | API do Microsoft Graph | SMTP / IMAP Direto |
|---|---|---|
| Autenticação | OAuth 2.0 (MSAL) | Nome de usuário + senha (descontinuado) |
| Limites de taxas | 10.000 requisições / 10 min por aplicativo | Sem limite padrão (dependente do servidor) |
| Características | Ler, enviar, pesquisar, webhooks, pastas | Limitado: envio/recebimento básico apenas |
| Complexidade | Fluxo OAuth + Registro de Aplicativo Azure | Baixa configuração, alta manutenção |
| Suporte Unipile | Nativo - nenhum fluxo OAuth necessário | Nativo - Fallback IMAP |
Por que usar a API Microsoft Graph para integração de e-mail?
Desenvolver com o Microsoft Graph oferece ao seu aplicativo acesso seguro, baseado em token, ao maior ecossistema de e-mail corporativo do mundo - mais de 400 milhões de caixas de correio do Outlook e do Exchange. Aqui estão os quatro motivos principais pelos quais os desenvolvedores escolhem o endpoint de e-mail da API do Microsoft Graph.
Um Registro de Aplicativo do Azure cobre todas as caixas de correio do Outlook, Exchange e Microsoft 365. Permissões delegadas permitem que os usuários consintam uma vez; permissões de aplicativo habilitam acesso no lado do servidor sem interação do usuário.
Leia, envie, responda, mova e exclua mensagens. Gerencie pastas, pesquise toda a caixa de correio, lide com anexos e defina regras de e-mail - tudo através da mesma interface REST com um esquema de resposta JSON previsível.
Assine notificações de alteração de caixa de correio e receba um POST HTTP em seu endpoint sempre que um novo e-mail chegar, uma mensagem for lida ou uma pasta for alterada. Sem consultas, sem atrasos - eventos entregues em tempo quase real.
Um único endpoint de API abrange contas pessoais do Outlook, tenants corporativos do Microsoft 365 e servidores Exchange locais (via híbrido). Uma integração cuida de todo o ecossistema de e-mail da Microsoft sem caminhos de código separados.
Configurando o OAuth da Microsoft para a API do Outlook
Documentação do Microsoft OAuthPor padrão, sua integração usa as credenciais OAuth da Unipile. Para obter um experiência totalmente branca de marca quando usuários finais conectam sua conta Microsoft, criam seu próprio aplicativo em Microsoft Entra ID. Siga o 7 passos abaixo para registrar seu aplicativo, configurar permissões e conectá-lo ao Unipile.
Criar uma Conta do Microsoft Entra ID
Se você ainda não tem um, crie um gratuito Microsoft Entra ID conta (anteriormente Azure Active Directory). Este é o portal administrativo onde você registrará seu aplicativo OAuth.
Registrar um Novo Aplicativo no Portal do Azure
Faça login em portal.azure.com, vá para Microsoft Entra ID, e clique Nova inscrição.
- Nome do seu aplicativo: Este nome será visível para seus usuários finais durante a tela de consentimento do OAuth.
- Tipos de conta suportados: Selecione "Contas em qualquer diretório organizacional (Qualquer Microsoft Entra ID, Multilocatário) e contas Microsoft pessoais" para dar suporte a contas do Office 365 corporativas e pessoais.
Adicionar URIs de Redirecionamento
Vá para Autenticação painel e clique Adicionar URI na seção Web. Adicionar 2 URIs de redirecionamento usando seu DSN Unipile (disponível em Painel de controle da Unipile, canto superior direito):
https://{{YOUR_DSN_less_port}}/api/v1/hosted/microsoft_auth_request_callback/port{{YOUR_PORT}}
Configurar permissões de API
Ir Permissões da API > Adicionar uma permissão > Microsoft Graph, então adicione o seguinte Permissões delegadas:
Para funcionalidades de Calendário, adicione também: Calendars.ReadWrite, Calendars.Read, Calendars.Read.Shared, Calendars.ReadWrite.Shared. Adicione-as nas configurações de escopo do seu Painel Unipile também.
Criar um Segredo do Cliente
Ir Certificados e segredos, clique Novo segredo do cliente. Nomeie o segredo e defina um prazo de 730 dias (24 meses), então clique em "Adicionar".
Conecte-se ao painel de controle da Unipile
Vá para Painel de controle da Unipile, navegar até Configurações > Microsoft OAuth.
- Copie e cole o ID do Cliente (Aplicação) da página Visão Geral do Azure.
- Cole o valor secreto da página Certificates & secrets.
- Clicar Salvar.
Testar a Conexão
No Painel Unipile, acione um novo vínculo de conta Microsoft para verificar se suas credenciais OAuth personalizadas funcionam corretamente. Você deverá ver sua Nome do aplicativo e de branding no prompt de consentimento da Microsoft em vez dos padrões da Unipile.
8
Torne-se um Editor Verificado
Recomendado para produção, remove o aviso "não verificado" na tela de consentimento
Com a verificação, uma marca azul aparece no prompt de consentimento. Sem ela, as contas profissionais podem ver um aviso de "publicador não verificado".
Passo 1: Junte-se à Microsoft Partner Network
- Cadastre-se em parceiro.microsoft.com e escolher Microsoft AI Cloud Partner Program.
- Se você precisar de uma conta de trabalho, criar novo inquilino primeiro.
Passo 2: Verifique seu domínio
Criar um arquivo chamado microsoft-identity-association.json e hospedá-lo em:
Passo 3: Vincule seu ID da Conta Global de Parceiro (PGA)
- Encontre seu ID PGA via Central de Parceiros.
- No Portal do Azure, vá para Registros de Aplicativos > Seu Aplicativo > Marca e propriedades, insira o ID da PGA e salve.
Para mais detalhes, consulte o Documentação de Verificação do Microsoft Publisher.
9
Tratando sobre "Aprovação do Administrador Necessária"
Quando usuários finais veem um bloco de consentimento de seu administrador de TI
Se um usuário vir "É necessária aprovação do administrador", o consentimento necessário não foi concedido no nível do locatário. Dois métodos para resolver isso:
Método 1: Solicitação de Consentimento do Administrador no Microsoft Entra
Um administrador da Microsoft deve revisar e aprovar a solicitação de consentimento de administrador pendente. Veja a Documentação da Microsoft sobre a revisão de solicitações de consentimento de administrador.
Método 2: Login OAuth como administrador com consentimento do tenant completo
- O administrador inicia o fluxo de login OAuth a partir do seu aplicativo.
- Durante a autorização da Microsoft, o administrador deve marcar: "Consentimento em nome da sua organização".
- Isso concede consentimento para todos os usuários da organização e impede a solicitação para usuários futuros.
Detalhes completos em Guia de solução de problemas de consentimento da Microsoft.
Casos de Uso de E-mail da Microsoft Graph API
A API do Microsoft Graph para e-mail potencializa uma ampla gama de aplicativos SaaS que dependem de caixas de correio do Outlook e Exchange. Estes são os três padrões de integração mais comuns usados por equipes que desenvolvem na Graph API atualmente.
Sincronize threads de e-mail e contatos do Outlook diretamente no seu CRM. Combine remetentes com registros de negócios existentes, registre todas as conversas automaticamente e exiba o histórico de relacionamentos sem copiar e colar manualmente do Outlook.
Guia da API de e-mailRastreie conversas de e-mail de candidatos em caixas de correio do Outlook. Analise e-mails de inscrição recebidos, extraia anexos e os direcione para o pipeline de empregos correto - tudo via o endpoint de e-mail da API do Microsoft Graph, sem intervenção manual.
Enviar API de e-mailConverta e-mails recebidos do Outlook em chamados de suporte. Use webhooks do Graph para receber eventos de novos e-mails em tempo real, classifique por domínio de assunto ou remetente e encaminhe para a fila da equipe correta - substituindo o triagem manual por lógica automatizada.
API Unificada de E-mailPrincipais Recursos da API de E-mail do Microsoft Graph
A API Microsoft Graph para e-mail expõe um conjunto abrangente de recursos que vão muito além do envio e recebimento básicos. Aqui estão os seis recursos mais importantes que todo desenvolvedor deve conhecer antes de criar sobre a pilha de e-mail da API Microsoft Graph.
Recupere mensagens individuais ou listas paginadas. Envie novos e-mails ou responda diretamente. Mova mensagens entre pastas ou marque como lidas/não lidas.
OBTER /v1.0/eu/mensagensFaça upload, download e liste anexos de arquivos em qualquer mensagem. Suporta anexos inline (embutidos) e uploads de arquivos grandes via sessões de upload para arquivos acima de 3 MB.
OBTER /v1.0/me/mensagens/{id}/anexosCriar, renomear e excluir pastas de e-mail. Listar todas as pastas de e-mail, mover mensagens entre elas e gerenciar hierarquias de pastas filhas, idêntico ao que os usuários veem no Outlook.
OBTER /v1.0/me/pastasDeEmailUse parâmetros de consulta OData ($filter,$search, $orderby) para encontrar e-mails por remetente, assunto, intervalo de datas ou palavra-chave. Suporta KQL para pesquisa avançada de texto completo.
OBTER /me/messages?$search="projeto"Inscreva-se para receber notificações de alteração para eventos de caixa de correio. Receba callbacks HTTP POST quase em tempo real quando novos e-mails chegarem, mensagens forem lidas ou pastas forem alteradas.
POST /v1.0/assinaturasCombine até 20 solicitações individuais da Graph API em uma única chamada HTTP usando o endpoint de lote $. Reduz drasticamente as idas e vindas para operações como leitura em massa de e-mails.
POST /v1.0/$em loteComo Enviar, Ler e Sincronizar E-mails com a API Microsoft Graph
Três padrões prontos para produção cobrindo as operações essenciais que todo desenvolvedor precisa: envio de e-mail, leitura de mensagens com filtros e sincronização incremental de delta para monitoramento de caixa de correio em tempo real.
import solicitações
# API Unificada de E-mail da Unipile
# Envia via Microsoft Graph — nenhum OAuth direto necessário
BASE = "https://api.unipile.com:13465/api/v1"
CABEÇALHOS = {
"X-API-KEY": "SEU_TOKEN_DE_ACESSO",
"Tipo-de-Conteúdo": "application/json"
}
def enviar_email_outlook(id_conta, para, assunto, corpo):
carga útil = {
"id_da_conta"id_da_conta,
"para": [{"identificador": para}],
"assunto": assunto,
"corpo"corpo
}
r = pedidos.postagem(f"{BASE}/emails", cabeçalhos=Cabeçalhos, json=carga útil
return r.json()
# Exemplo de uso
enviar_email_outlook(
"acc_outlook_123",
para="recipient@company.com",
assunto="Acompanhamento da reunião",
corpo="Olá, dando seguimento à nossa ligação..."
)POST https://graph.microsoft.com/v1.0/me/sendMail com message.paraDestinatarios, assunto.mensageme mensagem.corpo.conteúdo. Unipile abstrai a atualização do token OAuth e o manuseio MIME. Veja a Guia da API para Envio de E-mail para suporte a anexos e encadeamento de respostas.
import solicitações
# Leia e-mails do Outlook com filtros via Unipile
BASE = "https://api.unipile.com:13465/api/v1"
CABEÇALHOS = {"X-API-KEY": "SEU_TOKEN_DE_ACESSO"}
def listar_e-mails_outlook(id_conta, filtro_remetente=Nenhum, limite=20):
parâmetros = {
"id_da_conta"id_da_conta,
"limite"limite
}
se filtro_remetente:
# Mapeia para $filter=from/emailAddress/address eq '...'
parâmetros["de"] = filtro_remetente
r = pedidos.obter(f"{BASE}/emails", cabeçalhos=CABEÇALHOS, parâmetros=parâmetros
return r.json().obter("itens", [])
# Buscar os últimos 20 e-mails de um remetente específico
e-mails = listar_e-mails_outlook("acc_outlook_123", filtro_remetente="hr@acme.com")
para e em e-mails:
print(e["assunto"], e["de"], e["data"])Filtro de $, $pesquisar, $selecionar, $ordenar por, $superior. Usar $pesquisar="assunto:nota fiscal" para busca de texto completo KQL. Anexos com mais de 3MB exigem um sessão de upload (POST /criarsessaoDeUpload) — nenhuma solicitação multipart única.
import solicitações
# Delta Sync — buscar apenas e-mails NOVOS desde a última sincronização
# Unipile gerencia o ciclo de vida do deltaToken automaticamente
BASE = "https://api.unipile.com:13465/api/v1"
CABEÇALHOS = {"X-API-KEY": "SEU_TOKEN_DE_ACESSO"}
def sincronizar_novos_emails(id_da_conta, cursor=Nenhum):
"""
Retorna apenas e-mails recebidos desde a última chamada.
cursor = token opaco de paginação (armazene entre chamadas).
"""
parâmetros = {"id_da_conta": id_da_conta}
se cursor:
parâmetros["cursor"] = cursor
r = pedidos.obter(f"{BASE}/emails/sincronizar", cabeçalhos=CABEÇALHOS, parâmetros=parâmetros
dados = r.json()
return dados.obter("itens", []), dados.obter("cursor")
# Primeira sincronização — sem cursor
e-mails, próximo_cursor = sincronizar_novos_emails("acc_outlook_123")
# Armazene o next_cursor em seu banco de dados, use-o para chamadas subsequentes
print(f"{len(emails)} novos e-mails — próximo cursor salvo")GET /me/mailFolders/inbox/messages/delta retorna um @odata.deltaLink na primeira chamada. Armazene-a e use-a da próxima vez — o Graph retorna apenas a diferença. Não há sondagem de caixa de correio cheia = 10x menos chamadas de API vs. padrão GET /mensagens. O da Unipile. /emails/sincronizar endpoint encapsula esse padrão com gerenciamento automático de tokens.
Webhooks da API do Microsoft Graph para Eventos de E-mail
As assinaturas do Microsoft Graph (webhooks) permitem que seu servidor receba notificações por POST HTTP no momento em que um e-mail chega, é lido, movido ou excluído. Abaixo está um exemplo completo em Python para assinar eventos da Caixa de Entrada, além de detalhes sobre gerenciamento de ciclo de vida.
Uma assinatura de webhook do Graph tem dois campos obrigatórios: alterarTipo (quais eventos assistir) e urlDeNotificação (seu endpoint HTTPS). A Microsoft envia um tokenDeValidacao parâmetro de consulta na primeira assinatura. Seu endpoint deve repeti-lo como texto puro em até 10 segundos para confirmar a propriedade.
As assinaturas do gráfico expiram após um máximo de 4230 minutos (~3 dias) para recursos de e-mail. Seu servidor deve renovar antes do vencimento via PATCH /v1.0/assinaturas/{id} ou você deixará de receber notificações silenciosamente.
Notificações de Ciclo de Vida
URLDeNotificacaoDoCicloDeVida quando uma assinatura estiver prestes a expirar ou tiver sido revogada. Seu servidor deve responder com HTTP 202 para reconhecer. A falha em responder causa a rescisão da assinatura.Token de validação Handshake
?tokenDeValidacao=XXX. Você deve retornar o token como texto puro (Content-Type: text/plain) com HTTP 200 dentro de 10 segundos. Tempo limite significa que a criação da assinatura falha.Expiração da Assinatura
dataHoraExpiracao antes que expire. Você também pode recriar uma assinatura do zero. A Microsoft não cobra extra por renovações.import solicitações, data e hora
TOKEN_DE_ACESSO = "SEU_TOKEN_DE_GRAFICO"
PONTO DE EXTREMIDADE = "https://graph.microsoft.com/v1.0/subscriptions"
# Expiração: máximo de 4230 min a partir de agora para recursos de e-mail
validade = (
datetime.datetime.agora()
+ datetime.timedelta(minutos=4200)
).isoformat() + "Z"
carga útil = {
"tipo de alteração": "criado",
"urlNotificacao": "https://seusite.com/webhook",
"recurso": "me/mailFolders('Caixa de Entrada')/messages",
"dataHoraValidade": validade,
"estadoDoCliente": "meuEstadoSecreto"
}
r = pedidos.postagem(
PONTO DE EXTREMIDADE,
json=carga útil,
cabeçalhos={
"Autorização": Bearer {ACCESS_TOKEN}",
"Tipo-de-Conteúdo": "application/json"
}
)
print(r.json()["identificador"])
# sub_xxxxxxxx-xxxx-xxxx-xxxxSimplifique a Complexidade - Use a API Unificada de E-mail da Unipile
Conecte Microsoft Graph, Gmail e IMAP com um único SDK. Sem fluxos OAuth por provedor, sem lógica de atualização de tokens, sem infraestrutura de webhooks para manter. Sua equipe lança recursos de e-mail em dias, não em semanas.
Comece de graçaNão é necessário cartão de crédito. Em conformidade com SOC 2 Tipo II.
Limites de taxa e tratamento de erros da API do Microsoft Graph
A API do Microsoft Graph para e-mail aplica limitações em vários níveis: por usuário, por aplicativo e por locatário. Compreender esses limites antes de ir para produção evita falhas silenciosas e degradação da confiabilidade em sua integração.
Quando em throttling, o Microsoft Graph retorna HTTP 429 Muitos Pedidos with a Tentar Novamente Após cabeçalho especificando segundos para esperar. Sempre leia este cabeçalho e recue de acordo - sobrecarregar após um 429 estenderá a janela de limitação, não a encurtará.
| Código HTTP | Nome do erro | Causa | Consertar |
|---|---|---|---|
| 429 | MuitasRequisições | Limite de taxa excedido (10.000 req / 10 min por app ou 1.000 req / 1 min por usuário) | Leia o cabeçalho Retry-After. Implemente backoff exponencial. Use o lote $para combinar solicitações. |
| 401 | Não autorizado | Token de acesso expirado ou cabeçalho de Autorização ausente | Renovar token via MSAL. Verificar expiração do token antes de cada solicitação. Usar cache de token. |
| 403 | Proibido | Permissão ausente Mail.Read ou Mail.Send no Azure App Registration | Adicione as permissões de Graph exigidas no Portal do Azure e consinta novamente (ou consenta o administrador para permissões de aplicativo). |
| 404 | RecursoNaoEncontrado | ID da mensagem ou ID da pasta não existe (excluído ou tenant errado) | Verifique IDs via GET antes de agir sobre eles. Trate o 404 graciosamente como um sinal de exclusão lógica. |
| 500 | ErroInternoServidor | Erro transitório do servidor Microsoft | Tente novamente com retrocesso exponencial (1s, 2s, 4s). Registre o cabeçalho request-id para o suporte da Microsoft. |
Além do Microsoft Graph: API unificada de e-mail para Gmail, Outlook e IMAP
Gerenciar a integração de e-mail da API do Microsoft Graph é apenas o começo. A maioria dos produtos SaaS precisa dar suporte a Gmail, Outlook e IMAP simultaneamente, o que significa três fluxos OAuth separados, três loops de atualização de token e três sistemas de webhook. Unipile's API de e-mail unificada abstrai todos os três provedores por trás de um único endpoint.
API do Gmail
Microsoft Graph
IMAP / SMTP
Com o Unipile's integração de API de email unificada, você escreve uma integração e instantaneamente suporta todos os três tipos de provedores. As contas vinculadas são gerenciadas pelo Unipile - seu backend só se comunica com um endpoint REST, independentemente se a caixa de correio do usuário é executada no Microsoft Graph, Gmail ou IMAP.
Fluxos OAuth para gerenciar - O Unipile cuida da aquisição, atualização e revogação de tokens para o Microsoft Graph e Gmail em seu nome.
Eventos unificados de webhook - uma notificationUrl recebe eventos de e-mail de todos os provedores com um esquema JSON normalizado. Sem gerenciamento de assinatura por provedor.
Em conformidade com o SOC 2 Tipo II - todos os dados de e-mail em trânsito são criptografados. Unipile não armazena o conteúdo de e-mail além do que sua integração requer.
Comece a integrar e-mails do Microsoft Graph em minutos
Junte-se a mais de 200 equipes de SaaS que usam o Unipile para conectar Outlook, Gmail e IMAP sob uma única API. Sem vendor lock-in. Em conformidade com SOC 2.
Perguntas frequentes
Tudo o que desenvolvedores perguntam antes de criar na API de e-mail do Microsoft Graph - de autenticação a limites de taxa e cobertura de provedores.
https://graph.microsoft.com/v1.0/me/messages e usa autenticação OAuth 2.0 via Azure Active Directory. Ele suporta leitura, envio, pesquisa e gerenciamento de e-mails, bem como recebimento de notificações de alteração em tempo real via assinaturas de webhook./v1.0/assinaturas with a alterarTipo (por exemplo, "criado"), um urlDeNotificação apontando para o seu endpoint HTTPS e um recurso (por exemplo, "me/mailFolders('Inbox')/messages"). A Microsoft envia imediatamente uma solicitação GET com um tokenDeValidacao - seu servidor deve ecoá-lo de volta como texto puro em no máximo 10 segundos. As assinaturas expiram em no máximo 4230 minutos e devem ser renovadas via PATCH antes da expiração.
BR 
EN 
FR 
ES 
DE 
IT 
NL 
PL 
TR