LinkedIn
Instagram
WhatsApp
Telegramma
Calendario di Google
Partecipare alla comunità SlackMicrosoft Graph API Email: Guida completa all'integrazione per Sviluppatori (2026)
L'API Microsoft Graph è l'endpoint REST unificato per accedere ai dati di posta elettronica di Outlook e Exchange: leggere, inviare, cercare e ricevere webhook per ogni evento della casella di posta. Questa guida ti accompagna nella configurazione di OAuth 2.0, esempi di codice live, limiti di frequenza e come unificare Microsoft Graph con Gmail e IMAP sotto un unico SDK.
import richieste
# API Unificata per le Email di Unipile
# Legge le email di Outlook tramite Microsoft Graph
BASE = "https://api.unipile.com:13465/api/v1"
INTÈSTAZIONI = {
"X-API-KEY": "IL_TUO_TOKEN_DI_ACCESSO",
"Accetta": "application/json"
}
def ottenere_email_outlook(id_account, limite=20):
r = richieste.ottenere(
{BASE}/email",
headers=HEADERS,
parametri={
"account_id": id_account,
"limite"limite
}
)
return r.json()["email"]
e-mail = ottenere_email_outlook("acc_outlook_123")
per e in email:
print(e["soggetto"], e["da"])
Cos'è l'API Microsoft Graph per le e-mail?
L'API Microsoft Graph è il gateway REST unificato per tutti i servizi Microsoft 365, tra cui e-mail, calendario, contatti e file. Nello specifico per le e-mail, espone l /v1.0/me/messaggi endpoint, offrendo agli sviluppatori un accesso programmatico a ogni casella di posta di Outlook ed Exchange. Ha sostituito i protocolli legacy (Basic Auth, EWS) ed è ora l'unico modo ufficialmente supportato per accedere programmaticamente alle e-mail di Outlook utilizzando OAuth 2.0.
Il Microsoft Graph API per email l'interfaccia RESTful espone i dati della cassetta postale di Microsoft 365 - inclusi messaggi, cartelle, allegati e impostazioni della cassetta postale - in base a https://graph.microsoft.com/v1.0/me/messages endpoint. Si autentica tramite Azure Active Directory OAuth 2.0, supporta le autorizzazioni delegate e di applicazione e abilita eventi in tempo reale tramite modifica iscrizioni alle notifiche (webhook). È la sostituzione raccomandata per tutti i flussi di autenticazione base deprecati.
Microsoft Graph API è la sostituzione consigliata Per l'autenticazione di base deprecata, tutto l'accesso alle e-mail di Outlook e Exchange richiede ora OAuth 2.0 tramite Graph. L'autenticazione di base è stata completamente ritirata nell'ottobre 2022.
| Criterio | API Microsoft Graph | SMTP / IMAP diretto |
|---|---|---|
| Autenticazione | OAuth 2.0 (MSAL) | Nome utente + password (deprecato) |
| Limiti tariffari | 10.000 richieste / 10 min per app | Nessun limite standard (dipendente dal server) |
| Caratteristiche | Completo: leggi, invia, cerca, webhook, cartelle | Limitato: solo invio/ricezione di base |
| Complessità | Flusso OAuth + Registrazione dell'app Azure | Bassa configurazione, alta manutenzione |
| Supporto unipolare | Nativo - nessun flusso OAuth necessario | Nativo - Fallback IMAP |
Perché usare Microsoft Graph API per l'integrazione delle e-mail?
Costruire su Microsoft Graph offre alla tua applicazione un accesso sicuro basato su token al più grande ecosistema di posta elettronica aziendale del mondo: oltre 400 milioni di caselle di posta di Outlook ed Exchange. Ecco i quattro motivi principali per cui gli sviluppatori scelgono l'endpoint di posta elettronica dell'API Microsoft Graph.
Una singola Registrazione App di Azure copre tutte le cassette postali di Outlook, Exchange e Microsoft 365. Le autorizzazioni delegate consentono agli utenti di dare il consenso una sola volta; le autorizzazioni dell'applicazione consentono l'accesso lato server non presidiato senza alcuna interazione utente.
Leggi, invia, rispondi, sposta ed elimina messaggi. Gestisci cartelle, cerca nell'intera casella di posta, gestisci allegati e imposta regole di posta, tutto tramite la stessa interfaccia REST con uno schema di risposta JSON prevedibile.
Abbonati alle notifiche di modifica della casella di posta e ricevi un POST HTTP al tuo endpoint ogni volta che arriva una nuova e-mail, un messaggio viene letto o una cartella viene modificata. Nessun polling, nessun ritardo: eventi consegnati quasi in tempo reale.
Un singolo endpoint API copre account Outlook personali, tenant Microsoft 365 aziendali e server Exchange on-premises (tramite hybrid). Una singola integrazione gestisce l'intero ecosistema di posta elettronica Microsoft senza percorsi di codice separati.
Configurazione di Microsoft OAuth per l'API di Outlook
Documentazione OAuth MicrosoftPer impostazione predefinita, la tua integrazione utilizza le credenziali OAuth di Unipile. Per ottenere un esperienza completamente personalizzabile quando gli utenti finali collegano il loro account Microsoft, crea la tua app in Microsoft Entra ID. Segui il 7 passi qui sotto per registrare la tua app, configurare i permessi e collegarla a Unipile.
Creare un account Microsoft Entra ID
Se non ne hai già uno, creane uno gratuito Microsoft Entra ID account (precedentemente Azure Active Directory). Questo è il portale di amministrazione dove registrerai la tua applicazione OAuth.
Registra una nuova app nel portale di Azure
Accedere a portal.azure.com, vai a Microsoft Entra ID, e clicca Nuova registrazione.
- Dai il nome alla tua app: Questo nome sarà visibile ai tuoi utenti finali durante la schermata di consenso OAuth.
- Tipi di account supportati: selezionare "Account in qualsiasi directory organizzativa (qualsiasi Microsoft Entra ID, multitenant) e account personali Microsoft" per supportare entrambi gli account Office 365 aziendali e personali.
Aggiungi URI di reindirizzamento
Vai al Autenticazione pannello e clicca Aggiungi URI sotto la sezione Web. Aggiungi 2 URI di reindirizzamento utilizzando il tuo DSN Unipile (disponibile nel Cruscotto Unipile, in alto a destra):
https://{{YOUR_DSN_less_port}}/api/v1/hosted/microsoft_auth_request_callback/port{{YOUR_PORT}}
Configurare i permessi API
Vai a Autorizzazioni API > Aggiungi un'autorizzazione > Microsoft Graph, poi aggiungi quanto segue Permessi delegati:
Per le funzionalità del calendario, aggiungi anche: Calendars.ReadWrite, Calendars.Read, Calendars.Read.Shared, Calendars.ReadWrite.Shared. Aggiungili anche nelle impostazioni degli ambiti del tuo Dashboard Unipile.
Crea un segreto per il client
Vai a Certificati e segreti, fare clic Nuovo segreto client. Nomina il segreto e imposta una scadenza 730 giorni (24 mesi), quindi fai clic su "Aggiungi".
Collegarsi al cruscotto Unipile
Vai al Cruscotto Unipile, naviga a Impostazioni > Microsoft OAuth.
- Incolla il ID applicazione (client) dalla pagina Panoramica di Azure.
- Incolla il valore segreto dalla pagina Certificati e segreti.
- Fare clic Risparmiare.
Prova la connessione
Dalla Dashboard Unipile, attiva un nuovo collegamento all'account Microsoft per verificare che le tue credenziali OAuth personalizzate funzionino correttamente. Dovresti vedere il tuo nome dell'app e del branding nel prompt di consenso di Microsoft anziché quelli predefiniti di Unipile.
8
Diventa un Editore Verificato
Consigliato per la produzione, rimuove l'avviso "non verificato" nella schermata di consenso
Con la verifica, appare un segno di spunta blu nel prompt di consenso. Senza di essa, gli account professionali potrebbero visualizzare un avviso "editore non verificato".
Passaggio 1: Unisciti alla Microsoft Partner Network
- Registrati su partner.microsoft.com e scegli Programma partner Microsoft AI Cloud.
- Se hai bisogno di un account di lavoro, crea un nuovo tenant primo.
Passaggio 2: Verifica il tuo dominio
Crea un file chiamato microsoft-identity-association.json e ospitarlo su:
Passaggio 3: Collega il tuo ID Partner Global Account (PGA)
- Trova il tuo ID PGA tramite Partner Center.
- Nel portale di Azure, vai a Registrazioni app > La tua app > Branding e proprietà, inserisci l'ID PGA e salva.
Per maggiori dettagli, vedere Documentazione di verifica di Microsoft Publisher.
9
Gestione di "Approvazione dell'amministratore richiesta"
Quando gli utenti finali vedono un blocco di consenso dal loro amministratore IT
Se un utente vede "Approvazione dell'amministratore richiesta", il consenso richiesto non è stato concesso a livello di tenant. Due metodi per risolvere questo problema:
Metodo 1: Richiesta di consenso amministratore in Microsoft Entra
Un amministratore Microsoft deve rivedere e approvare la richiesta di consenso amministrativo in sospeso. Vedi la Documentazione Microsoft sulla revisione delle richieste di consenso dell'amministratore.
Metodo 2: accesso OAuth come amministratore con consenso a livello di tenant
- L'amministratore avvia il flusso di accesso OAuth dalla tua app.
- Durante l'autorizzazione di Microsoft, l'amministratore deve selezionare: "Consenso per conto della tua organizzazione".
- Ciò concede il consenso a tutti gli utenti dell'organizzazione e impedisce la richiesta di conferma per gli utenti futuri.
Completa i dettagli in Guida alla risoluzione dei problemi di consenso Microsoft.
Casi d'uso dell'API Microsoft Graph per le e-mail
L'endpoint email di Microsoft Graph API supporta una vasta gamma di applicazioni SaaS che si basano sulle caselle di posta di Outlook e Exchange. Questi sono i tre modelli di integrazione più comuni utilizzati oggi dai team che sviluppano su Graph API.
Sincronizza le conversazioni e i contatti di Outlook direttamente nel tuo CRM. Abbina i mittenti ai record delle trattative esistenti, registra automaticamente ogni conversazione e visualizza la cronologia delle relazioni senza dover copiare e incollare manualmente da Outlook.
Guida alle API per le e-mailTraccia le conversazioni via email dei candidati tra le caselle di posta di Outlook. Analizza le email di candidatura in arrivo, estrai gli allegati e indirizzali alla giusta pipeline di lavoro, tutto tramite l'endpoint email delle API di Microsoft Graph, senza alcun intervento manuale.
Invio di e-mail APIConverti le email in arrivo di Outlook in ticket di supporto. Utilizza i webhook di Graph per ricevere eventi di nuove email in tempo reale, classificare per oggetto o dominio del mittente e instradare alla coda del team giusto, sostituendo il triage manuale con logica automatizzata.
API unificata per e-mailFunzionalità chiave dell'API Microsoft Graph per le e-mail
La Microsoft Graph API per le e-mail espone un set completo di funzionalità che vanno ben oltre le funzionalità di base di invio e ricezione. Ecco le sei funzionalità più importanti che ogni sviluppatore dovrebbe conoscere prima di creare sulla Microsoft Graph API per le e-mail.
Recupera messaggi individuali o elenchi paginati. Invia nuove email o rispondi in linea. Sposta messaggi tra cartelle o contrassegnali come letti/non letti.
GET /v1.0/me/messaggiCaricare, scaricare ed elencare allegati di file su qualsiasi messaggio. Supporta allegati inline (incorporati) e caricamenti di file di grandi dimensioni tramite sessioni di caricamento per file superiori a 3 MB.
GET /v1.0/me/messages/{id}/allegatiCrea, rinomina ed elimina cartelle di posta elettronica. Elenca tutte le cartelle di posta elettronica, sposta i messaggi tra di esse e gestisci le gerarchie delle sottocartelle, identiche a quelle che gli utenti vedono in Outlook.
GET /v1.0/me/cartellePostaUtilizza i parametri di query OData ($filter,$search, $orderby) per trovare email per mittente, oggetto, intervallo di date o parola chiave. Supporta KQL per la ricerca full-text avanzata.
GET /me/messages?$cerca="progetto"Abbonati per ricevere notifiche di modifica degli eventi della casella di posta. Ricevi callback HTTP POST quasi in tempo reale quando arrivano nuove email, i messaggi vengono letti o le cartelle cambiano.
POSTA /v1.0/abbonamentiUnisci fino a 20 richieste API di Graph individuali in una singola chiamata HTTP utilizzando l'endpoint batch $. Riduce drasticamente i round-trip per operazioni come la lettura di email in blocco.
POSTA /v1.0/$batchCome Inviare, Leggere e Sincronizzare le Email con Microsoft Graph API
Tre pattern pronti per la produzione che coprono le operazioni fondamentali di cui ogni sviluppatore ha bisogno: invio di email, lettura di messaggi con filtri e sincronizzazione delta incrementale per il monitoraggio della casella di posta in tempo reale.
import richieste
# API Unificata per le Email di Unipile
# Invia tramite Microsoft Graph — nessuna OAuth diretta richiesta
BASE = "https://api.unipile.com:13465/api/v1"
INTÈSTAZIONI = {
"X-API-KEY": "IL_TUO_TOKEN_DI_ACCESSO",
"Content-Type": "application/json"
}
def inviare_email_outlook(id_account, a, oggetto, corpo)
carico utile = {
"account_id": id_account,
"a": [{"identificatore": a}],
"soggetto"soggetto,
"corpo"corpo
}
r = richieste.posta(f"{BASE}/email", intestazioni=HEADERS, json=payload)
return r.json()
# Esempio di utilizzo
inviare_email_outlook(
"acc_outlook_123",
a="recipient@company.com",
soggetto="Seguito della riunione",
corpo="Ciao, in seguito alla nostra chiamata..."
)POST https://graph.microsoft.com/v1.0/me/sendMail con messaggio.aiDestinatari, Oggetto del messaggio, e messaggio.corpo.contenuto. Unipile astrae il rinnovo del token OAuth e la gestione MIME. Vedi la Guida all'API per l'invio di email per il supporto degli allegati e la visualizzazione delle risposte in thread.
import richieste
# Leggi le email di Outlook con filtri tramite Unipile
BASE = "https://api.unipile.com:13465/api/v1"
INTÈSTAZIONI = {"X-API-KEY": "IL_TUO_TOKEN_DI_ACCESSO"}
def elenca_email_outlook(id_account, filtro_mittente=Nessuno, limite=20):
parametri = {
"account_id": id_account,
"limite"limite
}
se filtro_mittente:
# Mappa a $filter=from/emailAddress/address eq '...'
parametri["da"] = filtro mittente
r = richieste.ottenere(f"{BASE}/email", intestazioni=Intestazioni, parametri=parametri)
return r.json().prendi("articoli", [])
# Recupera le ultime 20 email da un mittente specifico
e-mail = elenca_email_outlook("acc_outlook_123", filtro mittente="hr@acme.com")
per e in email:
print(e["soggetto"], e["da"], e["data"])$filtro, $ricerca, $seleziona, $ordina per, $sopra. Usa $ricerca="oggetto:fattura" per la ricerca full-text KQL. Gli allegati superiori a 3 MB richiedono un caricare sessione (POST /createUploadSession) — nessuna richiesta multimarparte singola.
import richieste
# Delta Sync — scarica solo le email NUOVE dall'ultima sincronizzazione
# Unipile gestisce il ciclo di vita di deltaToken automaticamente
BASE = "https://api.unipile.com:13465/api/v1"
INTÈSTAZIONI = {"X-API-KEY": "IL_TUO_TOKEN_DI_ACCESSO"}
def sincronizza_nuove_email(id_account, cursore=Nessuno):
"""
Restituisce solo le email ricevute dall'ultima chiamata.
cursore = token di paginazione opaco (conservare tra le chiamate).
"""
parametri = {"account_id": id_account
se cursore
parametri["cursore"] = cursore
r = richieste.ottenere(f"{BASE}/email/sincronizzazione", intestazioni=Intestazioni, parametri=parametri)
dati = r.json()
return data.ottenere("articoli", []), dati.get("cursore")
# Prima sincronizzazione — nessun cursore
email, cursore_successivo = sincronizza_nuove_email("acc_outlook_123")
# Memorizza next_cursor nel tuo DB, usalo per chiamate successive
print(f"{len(emails)} nuove email — cursore successivo salvato")GET /me/cartellePosta/postaInArrivo/messaggi/delta restituisce un @odata.deltaLink alla prima chiamata. Salvalo e usalo la prossima volta — Il grafo restituisce solo la differenza. Nessun sondaggio completa piena la casella di posta = 10 volte meno chiamate API rispetto allo standard GET /messaggi. Unipile's /email/sincronizzazione endpoint incapsula questo pattern con gestione automatica dei token.
Webhook di Microsoft Graph API per eventi di posta elettronica
Gli abbonamenti a Microsoft Graph (webhook) consentono al tuo server di ricevere notifiche POST HTTP nel momento in cui una e-mail viene ricevuta, letta, spostata o eliminata. Di seguito è riportato un esempio Python completo per l'iscrizione agli eventi della Posta in arrivo, oltre ai dettagli sulla gestione del ciclo di vita.
Una sottoscrizione webhook di Graph ha due campi obbligatori: cambiaTipo (quali eventi guardare) e URL di notifica (il tuo endpoint HTTPS). Microsoft invia un token di convalida parametro di query alla prima sottoscrizione. Il tuo endpoint deve restituirlo come testo semplice entro 10 secondi per confermare la proprietà.
Le sottoscrizioni del grafo scadono dopo un massimo di 4230 minuti (~3 giorni) per risorse di posta. Il tuo server deve rinnovare prima della scadenza tramite PATCH /v1.0/abbonamenti/{id} o smetterai di ricevere notifiche in silenzio.
Notifiche del ciclo di vita
URL notifica ciclo di vita quando una sottoscrizione sta per scadere o è stata revocata. Il tuo server deve rispondere con HTTP 202 per confermare. Il mancato invio di una risposta causa la terminazione della sottoscrizione.Token di validazione Handshake
?tokenDiValidazione=XXX. Devi restituire il token come testo semplice (Content-Type: text/plain) con HTTP 200 entro 10 secondi. Il timeout comporterà il mancato completamento della creazione della sottoscrizione.Scadenza abbonamento
dataOraScadenza prima che scada. Puoi anche ricreare un abbonamento da zero. Microsoft non addebita costi aggiuntivi per i rinnovi.import richieste, data e ora
TOKEN_DI_ACCESSO = "TOKEN_GRAFICO_TUO"
PUNTO DI ESTREMO = "https://graph.microsoft.com/v1.0/subscriptions"
# Scadenza: massimo 4230 min da ora per le risorse di posta
scadenza = (
datetime.datetime.l'ora universale coordinata()
+ datetime.timedelta(minuti=4200)
).isoformat() + "Z"
carico utile = {
"tipoDiCambio": "creato",
"urlNotifica": "https://tuodominio.com/webhook",
"risorsa": "me/cartellePosta/('Posta in arrivo')/messaggi",
"dataOraScadenza": scadenza,
"statoCliente": "ilMioStatoSegreto"
}
r = richieste.posta(
PUNTO FINALE,
json=carico utile,
intestazioni={
"Autorizzazione": Bearer {TOKEN_DI_ACCESSO}",
"Content-Type": "application/json"
}
)
print(r.json()["id"])
# sub_xxxxxxxx-xxxx-xxxx-xxxxSalta la Complessità - Usa l'API Unificata di Unipile per le Email
Collega Microsoft Graph, Gmail e IMAP con un unico SDK. Nessun flusso OAuth per provider, nessuna logica di refresh dei token, nessuna infrastruttura webhook da mantenere. Il tuo team rilascia funzionalità email in giorni, non settimane.
Iniziare gratisNessuna carta di credito richiesta. Conforme a SOC 2 Type II.
Limiti di frequenza e gestione degli errori dell'API Microsoft Graph
L'endpoint e-mail dell'API Microsoft Graph applica il throttling a più livelli: per utente, per applicazione e per tenant. Comprendere questi limiti prima di andare in produzione evita errori silenziosi e una minore affidabilità nella tua integrazione.
Quando viene limitato, Microsoft Graph restituisce 429 Troppe Richieste with a Ritenta dopo intestazione che specifica i secondi da attendere. Leggi sempre questa intestazione e attieniti di conseguenza: sovraccaricare dopo un 429 estenderà la finestra di throttling, non la accorcerà.
| Codice HTTP | Nome errore | Causa | Risolvi |
|---|---|---|---|
| 429 | TroppeRichieste | Sostituita la frequenza dei tentativi (10.000 richieste / 10 minuti per app o 1.000 richieste / 1 minuto per utente) | Leggi l'header Retry-After. Implementa il backoff esponenziale. Usa il batch $per combinare le richieste. |
| 401 | Non autorizzato | Token di accesso scaduto o intestazione di autorizzazione mancante | Rinnova il token tramite MSAL. Controlla la scadenza del token prima di ogni richiesta. Utilizza la cache del token. |
| 403 | Proibito | Permesso mancante Mail.Read o Mail.Send nella registrazione dell'app di Azure | Aggiungere le autorizzazioni Graph richieste nel portale di Azure e concedere nuovamente il consenso (o il consenso dell'amministratore per le autorizzazioni dell'app). |
| 404 | RisorsaNonTrovata | ID del messaggio o ID della cartella non esiste (eliminato o tenant errato) | Verifica gli ID tramite GET prima di agire su di essi. Gestisci il 404 con grazia come segnale di eliminazione logica. |
| 500 | Errore interno del server | Errore transitorio del server Microsoft | Riprova con backoff esponenziale (1s, 2s, 4s). Registra l'header request-id per il supporto Microsoft. |
Oltre Microsoft Graph: API unificata per email di Gmail, Outlook e IMAP
La gestione dell'integrazione delle email di Microsoft Graph API è solo l'inizio. La maggior parte dei prodotti SaaS deve supportare contemporaneamente Gmail, Outlook e IMAP, il che significa tre flussi OAuth separati, tre cicli di refresh dei token e tre sistemi di webhook. Unipile's API email unificata astratta tutti e tre i provider dietro un singolo endpoint.
API Gmail
Microsoft Graph
IMAP / SMTP
Con Unipile's Integrazione API email unificata, scrivi un'integrazione e supporti istantaneamente tutti e tre i tipi di provider. Gli account collegati sono gestiti da Unipile: il tuo backend parla solo con un endpoint REST, indipendentemente dal fatto che la casella di posta dell'utente utilizzi Microsoft Graph, Gmail o IMAP.
Nessun flusso OAuth da gestire Unipile gestisce l'acquisizione, il rinnovo e la revoca dei token per Microsoft Graph e Gmail per tuo conto.
Eventi webhook unificati - un notificationUrl riceve eventi via email da tutti i provider con uno schema JSON normalizzato. Nessuna gestione degli abbonamenti per provider.
Conforme a SOC 2 di tipo II - tutti i dati delle e-mail in transito sono crittografati. Unipile non memorizza il contenuto delle e-mail oltre quanto richiesto dalla tua integrazione.
Inizia a integrare l'email di Microsoft Graph in pochi minuti
Unisciti a oltre 200 team SaaS che utilizzano Unipile per collegare Outlook, Gmail e IMAP sotto un'unica API. Nessun vendor lock-in. Conforme a SOC 2.
Domande frequenti
Tutto ciò che gli sviluppatori chiedono prima di costruire sull'endpoint e-mail dell'API Microsoft Graph: dall'autenticazione ai limiti di frequenza alla copertura dei provider.
https://graph.microsoft.com/v1.0/me/messages e utilizza l'autenticazione OAuth 2.0 tramite Azure Active Directory. Supporta la lettura, l'invio, la ricerca e la gestione delle email, oltre a ricevere notifiche di modifiche in tempo reale tramite sottoscrizioni webhook./v1.0/abbonamenti with a cambiaTipo (ad esempio, "creato"), un URL di notifica indicando il tuo endpoint HTTPS, e un risorsa (ad esempio, "me/mailFolders('Inbox')/messages"). Microsoft invia immediatamente una richiesta GET con un token di convalida - il tuo server deve ripeterlo come testo normale entro 10 secondi. Gli abbonamenti scadono entro un massimo di 4230 minuti e devono essere rinnovati tramite PATCH prima della scadenza.
IT 
EN 
FR 
ES 
DE 
BR 
NL 
PL 
TR