Microsoft Graph API e-mailberichten: Volledige Integratiegids voor ontwikkelaars (2026)
De Microsoft Graph API is het uniforme REST-eindpunt voor toegang tot e-mailgegevens van Outlook en Exchange: lezen, verzenden, zoeken en webhooks ontvangen voor elke mailboxgebeurtenis. Deze gids leidt u door de OAuth 2.0-instellingen, live codevoorbeelden, limieten voor aanvraagsnelheid en hoe Microsoft Graph te verenigen met Gmail en IMAP onder een enkele SDK.
importeer verzoekt
# Unipile Unified E-mail API
# Leest Outlook e-mails via Microsoft Graph
BASIS = "https://api.unipile.com:13465/api/v1"
KOPTEKSTEN = {
"X-API-SLEUTEL": "UW_TOEGANGSTOKEN",
"Accepteren": "application/json"
}
def haal_outlook_emails(account_id, limiet=20):
r = verzoeken.krijgen(
f"{BASE}/emails",
headers=HEADERS,
params={
"account_id"account_id,
"limiet"limiet
}
)
return r.json()["e-mails"]
e-mails = haal_outlook_emails("acc_outlook_123")
voor e in e-mails
print(e["onderwerp"], e["van"])Wat is de Microsoft Graph API voor e-mail?
De Microsoft Graph API is de uniforme REST-gateway voor alle Microsoft 365-services, waaronder e-mail, agenda, contacten en bestanden. Specifiek voor e-mail stelt deze de /v1.0/mij/berichten eindpunt, dat ontwikkelaars programmatische toegang geeft tot elke Outlook- en Exchange-mailbox. Het heeft verouderde protocollen (Basic Auth, EWS) vervangen en is nu de enige officieel ondersteunde manier om programmatisch toegang te krijgen tot Outlook-e-mail met OAuth 2.0.
De Microsoft Graph API voor e-mail biedt de RESTful-interface toegang tot Microsoft 365-mailboxgegevens, waaronder berichten, mappen, bijlagen en postvakinstellingen, onder de https://graph.microsoft.com/v1.0/me/messages endpoint. Het authenticeert via Azure Active Directory OAuth 2.0, ondersteunt gedelegeerde en applicatiemachtigingen en maakt realtime gebeurtenissen mogelijk via meldingsabonnementen wijzigen (webhooks). Het is de aanbevolen vervanging voor alle verouderde Basic Authentication-stromen.
Microsoft Graph API is de Aanbevolen vervanging voor verouderde Basic Authenticatie - alle Outlook- en Exchange-e-mailtoegang vereist nu OAuth 2.0 via Graph. Basic Auth werd volledig stopgezet in oktober 2022.
| Criterium | Microsoft Graph API | Directe SMTP / IMAP |
|---|---|---|
| Authenticatie | OAuth 2.0 (MSAL) | Gebruikersnaam + wachtwoord (verouderd) |
| Tariefgrenzen | 10.000 verzoeken / 10 minuten per app | Geen standaardlimiet (serverafhankelijk) |
| Kenmerken | Volledig: lezen, verzenden, zoeken, webhooks, mappen | Beperkt: alleen basis verzenden/ontvangen |
| Complexiteit | OAuth-stroom + Azure-appregistratie | Lage opzet, hoog onderhoud |
| Unipile-ondersteuning | Native - geen OAuth flow nodig | Native - IMAP-back-up |
Waarom de Microsoft Graph API gebruiken voor e-mailintegratie?
Door te bouwen op Microsoft Graph krijgt uw toepassing veilige, op tokens gebaseerde toegang tot 's werelds grootste enterprise e-mailecosysteem: meer dan 400 miljoen Outlook- en Exchange-mailboxen. Hier zijn de vier belangrijkste redenen waarom ontwikkelaars de e-mail-endpoint van de Microsoft Graph API kiezen.
Eén Azure App Registratie dekt alle Outlook-, Exchange- en Microsoft 365-postbussen. Gedelegeerde machtigingen laten gebruikers eenmalig toestemming geven; toepassingsmachtigingen maken onbewaakte toegang aan de serverzijde mogelijk zonder enige gebruikersinteractie.
Berichten lezen, verzenden, beantwoorden, verplaatsen en verwijderen. Mappen beheren, de hele mailbox doorzoeken, bijlagen verwerken en mailregels instellen - allemaal via dezelfde REST-interface met een voorspelbaar JSON-antwoordschema.
Abonneer u op meldingen van mailboxwijzigingen en ontvang een HTTP POST naar uw eindpunt telkens wanneer er een nieuwe e-mail arriveert, een bericht wordt gelezen of een map verandert. Geen polling, geen vertragingen - gebeurtenissen worden bijna in realtime geleverd.
Eén API-eindpunt dekt persoonlijke Outlook-accounts, zakelijke Microsoft 365-tenants en on-premises Exchange-servers (via hybride). Eén integratie regelt het volledige Microsoft e-mailecosysteem zonder aparte code.
Microsoft OAuth instellen voor Outlook API
Microsoft OAuth DocumentatieStandaard gebruikt je integratie de OAuth-gegevens van Unipile. Om een volledige white-label ervaring wanneer eindgebruikers hun Microsoft-account koppelen, maak uw eigen app in Microsoft Entra ID. Volg de 7 stappen hieronder om uw app te registreren, machtigingen te configureren en deze te verbinden met Unipile.
Maak een Microsoft Entra ID-account
Als je er nog geen hebt, maak dan een gratis Microsoft Entra ID account (voorheen Azure Active Directory). Dit is het beheerdersportaal waar u uw OAuth-toepassing registreert.
Registreer een nieuwe app in Azure Portal
Aanmelden bij portal.azure.com, ga naar Microsoft Entra ID, en klik Nieuwe registratie.
- Noem je app: deze naam zal zichtbaar zijn voor uw eindgebruikers tijdens het OAuth-autorisatiescherm.
- Ondersteunde accounttypen: selecteer "Accounts in een organisatie directory (elke Microsoft Entra ID, multitenant) en persoonlijke Microsoft-accounts" om zowel zakelijke als persoonlijke Office 365-accounts te ondersteunen .
Omleidings-URI's toevoegen
Ga naar de Authenticatie paneel en klik URI toevoegen onder de sectie Web. Toevoegen 2 omleidings-URI's met uw Unipile DSN (beschikbaar in de Unipile Dashboard, rechtsboven):
https://{{YOUR_DSN_less_port}}/api/v1/hosted/microsoft_auth_request_callback/port{{YOUR_PORT}}
API-machtigingen configureren
Ga naar API Mandaat > Mandaat toevoegen > Microsoft Graph, voeg dan het volgende toe Gedelegeerde machtigingen:
Voeg voor Agenda-functies ook toe: Calendars.ReadWrite, Calendars.Read, Calendars.Read.Shared, Calendars.ReadWrite.Shared. Voeg ze ook toe aan de scope-instellingen van je Unipile Dashboard.
Maak een clientgeheim
Ga naar Certificaten en geheimen, klik Nieuw clientgeheim. Noem het geheim en stel een vervaldatum in van 730 dagen (24 maanden), klik vervolgens op "Toevoegen".
Verbinding maken met Unipile Dashboard
Ga naar de Unipile Dashboard, navigeer naar Instellingen > Microsoft OAuth.
- Plak de Applicatie (Client) ID vanaf de Azure Overzichtspagina.
- Plak de geheime waarde van de pagina Certificaten en geheimen.
- Klik Sla.
Test de verbinding
Vanuit het Unipile Dashboard, activeer een nieuwe Microsoft accountkoppeling om te verifiëren dat uw aangepaste OAuth-referenties correct werken. U zou uw appnaam en branding in de Microsoft-prompt voor toestemming in plaats van de standaardinstellingen van Unipile.
8
Word een Geverifieerde Uitgever
Aanbevolen voor productie, verwijdert de "niet geverifieerde" waarschuwing op het toestemmingsscherm
Met verificatie verschijnt er een blauwe vink in de toestemmingsprompt. Zonder verificatie kunnen professionele accounts een waarschuwing zien voor een "geverifieerde uitgever".
Stap 1: Word lid van het Microsoft Partner Network
- Meld je aan bij partner.microsoft.com en kies Microsoft AI Cloud Partner Program.
- Als u een werkaccount nodig heeft, Maak een nieuwe tenant eerst.
Stap 2: Verifieer je domein
Maak een bestand met de naam microsoft-identiteitsassociatie.json en host het op:
Stap 3: Koppel uw Partner Global Account (PGA) ID
- Vind uw PGA ID via Partnercentrum.
- In Azure Portal, ga naar Appregistraties > Je app > Branding en eigenschappen, voer het PGA-ID in en sla op.
Voor volledige details, zie de Microsoft Publisher Verificatie documentatie.
9
"Administratorgoedkeuring vereist" afhandelen"
Wanneer eindgebruikers een toestemmingsblok zien van hun IT-beheerder
Als een gebruiker "Goedkeuring van de beheerder vereist" ziet, is de vereiste toestemming op tenantniveau niet verleend. Twee methoden om dit op te lossen:
Methode 1: Admin toestemmingsverzoek in Microsoft Entra
Een Microsoft-beheerder moet de lopende aanvraag voor beheerdersgoedkeuring beoordelen en goedkeuren. Zie de Microsoft-documentatie over het beoordelen van beheerdersstemverzoeken.
Methode 2: OAuth-aanmelding als beheerder met tenant-brede toestemming
- De beheerder start de OAuth-inlogstroom vanuit uw app.
- Tijdens de Microsoft-autorisatie moet de beheerder aanvinken: "Toestemming namens uw organisatie".
- Dit verleent toestemming voor alle gebruikers in de organisatie en voorkomt de prompt voor toekomstige gebruikers.
Volledige details in de Microsoft-handleiding voor het oplossen van problemen met toestemming.
E-mail Gebruiksgevallen van Microsoft Graph API
De Microsoft Graph API e-mail-endpoint drijft een breed scala aan SaaS-applicaties aan die afhankelijk zijn van Outlook- en Exchange-mailboxen. Dit zijn de drie meest voorkomende integratiepatronen die vandaag de dag door teams worden gebruikt die op de Graph API bouwen.
Synchroniseer Outlook e-mailthreads en contacten rechtstreeks in uw CRM. Koppel afzenders aan bestaande dealrecords, log elk gesprek automatisch en toon de relatiegeschiedenis zonder handmatig kopiëren en plakken vanuit Outlook.
Handleiding voor e-mail-APIVolg e-mailthreads van kandidaten in Outlook-mailboxen. Verwerk inkomende sollicitatiemails, extraheer bijlagen en roteer ze naar de juiste vacaturepijplijn - allemaal via de e-indpoint van de Microsoft Graph API met nul handmatige interventie.
Verzend e-mail APIConverteer inkomende Outlook-e-mails naar supporttickets. Gebruik Graph webhooks om realtime gebeurtenissen van nieuwe e-mails te ontvangen, te classificeren op onderwerp of afzenderdomein en te routeren naar de juiste teamwachtrij - ter vervanging van handmatige triage door geautomatiseerde logica.
Unified E-mail APIBelangrijkste kenmerken van Microsoft Graph API E-mail
De Microsoft Graph API voor e-mail biedt een uitgebreide reeks mogelijkheden die veel verder gaan dan het basis verzenden en ontvangen. Hier zijn de zes belangrijkste functies die elke ontwikkelaar moet kennen voordat hij bouwt op de Microsoft Graph API e-mailstack.
Haal individuele berichten of gepagineerde lijsten op. Stuur nieuwe e-mails of antwoord inline. Verplaats berichten tussen mappen of markeer als gelezen/ongelézen.
GET /v1.0/mij/berichtenBestanden uploaden, downloaden en weergeven als bijlagen in elke bericht. Ondersteunt inline (ingesloten) bijlagen en grote bestandsuploads via uploadsessies voor bestanden groter dan 3 MB.
GET /v1.0/mij/berichten/{id}/bijlagenMaak, hernoem en verwijder mailmappen. Geef alle mailmappen weer, verplaats berichten ertussen en beheer hiërarchieën van onderliggende mappen, identiek aan wat gebruikers in Outlook zien.
GET /v1.0/mij/mailMappenGebruik OData-queryparameters ($filter,$search, $orderby) om e-mails te vinden op afzender, onderwerp, datumbereik of trefwoord. Ondersteunt KQL voor geavanceerd full-text zoeken.
GET /mijn/berichten?$zoekopdracht="project"Abonneren op wijzigingsmeldingen voor postbusevenementen. Ontvang bijna real-time HTTP POST callbacks wanneer nieuwe e-mails binnenkomen, berichten worden gelezen of mappen wijzigen.
POST /v1.0/abonnementenCombineert maximaal 20 individuele Graph API-aanvragen in één HTTP-aanroep met behulp van het $batch-eindpunt. Vermindert het aantal retouren drastisch voor bewerkingen zoals het in bulk lezen van e-mails.
POST /v1.0/$partijHoe e-mails te verzenden, lezen en synchroniseren met de Microsoft Graph API
Drie productieklare patronen die de kernoperaties dekken die elke ontwikkelaar nodig heeft: e-mails verzenden, berichten lezen met filters en incrementele delta-synchronisatie voor realtime mailboxbewaking.
importeer verzoekt
# Unipile Unified E-mail API
# Verzenden via Microsoft Graph — geen directe OAuth vereist
BASIS = "https://api.unipile.com:13465/api/v1"
KOPTEKSTEN = {
"X-API-SLEUTEL": "UW_TOEGANGSTOKEN",
"Content-Type": "application/json"
}
def stuur_outlook_e-mail(account_id, aan, onderwerp, bericht):
lading = {
"account_id"account_id,
"naar": [{"identificatiemiddel": naar}],
"onderwerp"onderwerp,
"lichaam": lichaam
}
r = verzoeken.postf"{BASE}/e-mails", kopteksten=HEADERS, json=lading
return r.json()
# Voorbeeldgebruik
stuur_outlook_e-mail(
"acc_outlook_123",
naar="recipient@company.com",
onderwerp="Follow-up van vergadering",
lichaam="Hallo, even terugkomend op ons telefoongesprek..."
)POST https://graph.microsoft.com/v1.0/me/sendMail met bericht.aanOntvangers, onderwerpen bericht.body.inhoud. Unipile abstraheert het vernieuwen van OAuth-tokens en de MIME-verwerking. Zie de E-mail verzenden API-gids voor ondersteuning van bijlagen en het groeperen van antwoorden.
importeer verzoekt
# Lees Outlook-e-mails met filters via Unipile
BASIS = "https://api.unipile.com:13465/api/v1"
KOPTEKSTEN = {"X-API-SLEUTEL": "UW_TOEGANGSTOKEN"}
def e-mails weergeven in Outlook(account_id, afzender_filter=Geen, limiet=20):
parameters = {
"account_id"account_id,
"limiet"limiet
}
als afzender_filter:
# Komt overeen met $filter=from/emailAddress/address eq '...'
params["van"] = afzenderfilter
r = verzoeken.krijgenf"{BASE}/e-mails", kopteksten=HEADERS, params=params)
return r.json().verkrijgen("items", [])
# Haal de laatste 20 e-mails op van een specifieke afzender
e-mails = e-mails weergeven in Outlook("acc_outlook_123", afzenderfilter="hr@acme.com")
voor e in e-mails
print(e["onderwerp"], e["van"], e["datum"])$filter, $zoeken, $selecteer, $sorteren op, $boven. Gebruik $zoeken="onderwerp:factuur" voor KQL full-text search. Bijlagen van meer dan 3MB vereisen een sessie uploaden (POST /createUploadSession) — geen enkele multipartverzoek.
importeer verzoekt
# Delta Sync — alleen E-MAILS OPHALEN DIE NIEUW zijn sinds de laatste synchronisatie
# Unipile beheert de levenscyclus van de deltaToken automatisch
BASIS = "https://api.unipile.com:13465/api/v1"
KOPTEKSTEN = {"X-API-SLEUTEL": "UW_TOEGANGSTOKEN"}
def synchroniseer_nieuwe_e-mails(account_id, cursor=Geen):
"""
Geeft alleen e-mails die sinds de laatste aanroep zijn ontvangen.
cursor = ondoorzichtig pagineringstoken (opslaan tussen oproepen).
"""
parameters = {"account_id": account_id}
als aanwijzer
params["cursor"] = cursor
r = verzoeken.krijgenf"{BASE}/emails/sync", kopteksten=HEADERS, params=params)
gegevens = r.json()
return data.haalOp("items", []), data.get("cursor")
# Eerste synchronisatie — geen cursor
e-mails, volgende_cursor = synchroniseer_nieuwe_e-mails("acc_outlook_123")
# Sla next_cursor op in je database, gebruik het voor volgende aanroepen
printf"{len(emails)} nieuwe e-mails — volgende cursor opgeslagen")GET /mij/mailFolders/inbox/messages/delta retourneert een @odata.deltaLink bij de eerste aanroep. Sla het op en gebruik het de volgende keer dat de grafiek alleen het verschil retourneert. Geen mailbox vol met enquêtes = 10x minder API-aanroepen vs standaard GET /berichten. Unipile's /e-mails/synchroniseren endpoint omhult dit patroon met automatisch tokenbeheer.
Microsoft Graph API Webhooks voor E-mailgebeurtenissen
Microsoft Graph-abonnementen (webhooks) laten uw server direct na binnenkomst, lezen, verplaatsen of verwijderen van een e-mail HTTP POST-meldingen ontvangen. Hieronder vindt u een compleet Python-voorbeeld voor het abonneren op Inbox-gebeurtenissen, plus details over levenscyclusbeheer.
Een Graph webhook-abonnement heeft twee vereiste velden: typeWijziging (welke evenementen je moet bekijken) en meldingUrl je HTTPS-eindpunt). Microsoft stuurt een validatietoken queryparameter bij eerste abonnement. Je endpoint moet deze binnen 10 seconden als platte tekst terugsturen om eigendom te bevestigen.
Grafiekabonnementen verlopen na maximaal 4230 minuten (~3 dagen) voor mailbronnen. Uw server moet vernieuwen voor het verlopen via PATCH /v1.0/abonnementen/{id} anders ontvang je stilzwijgend geen meldingen meer.
Levenscyclusmeldingen
levenscyclusMeldingsURL wanneer een abonnement bijna afloopt of is ingetrokken. Uw server moet reageren met HTTP 202 om dit te bevestigen. Als er niet wordt gereageerd, wordt het abonnement beëindigd.validatietoken Handshake
?validatietoken=XXX. U moet het token retourneren als platte tekst (Content-Type: text/plain) met HTTP 200 binnen 10 seconden. Een time-out betekent dat het aanmaken van de abonnement mislukt.Abonnement verlopen
verloopdatum voordat deze verloopt. Je kunt een abonnement ook helemaal opnieuw aanmaken. Microsoft rekent geen extra kosten voor verlengingen.importeer verzoekt, datumtijd
TOEGANGSTOKEN = "JOUW_GRAFIEK_TOKEN"
EINDDPUNT = "https://graph.microsoft.com/v1.0/abonnementen"
# Vervaltijd: max 4230 min vanaf nu voor mailbronnen
verval = (
datetime.datetime.huidige_utc_tijd()
+ datetime.timedelta(minuten=4200)
).isoformaat() + "Z"
lading = {
"wijzigingstype": "geschapen",
"notificatieUrl": "https://uwdomein.nl/webhook",
"bron": "me/mailFolders('Inbox')/berichten",
"vervaldatumTijd": verval,
"clientStatus": "mijnGeheimeStatus"
}
r = verzoeken.post(
Eindpunt,
json=lading,
kopteksten={
"Autorisatie": Bearer {ACCESS_TOKEN}",
"Content-Type": "application/json"
}
)
print(r.json()["id"])
# sub_xxxxxxxx-xxxx-xxxx-xxxxVermijd Complexiteit - Gebruik Unipile's Unified Email API
Integreer Microsoft Graph, Gmail en IMAP met één SDK. Geen OAuth-stromen per provider, geen logica voor het vernieuwen van tokens, geen webhook-infrastructuur om te onderhouden. Uw team levert e-mailfuncties in dagen, niet in weken.
Gratis startenGeen creditcard vereist. SOC 2 Type II-conform.
Microsoft Graph API Snelheidslimieten en Foutafhandeling
De Microsoft Graph API e-mail-endpoint past throttling toe op meerdere niveaus: per gebruiker, per toepassing en per tenant. Het begrijpen van deze limieten voordat u naar productie gaat, voorkomt stille storingen en verminderde betrouwbaarheid in uw integratie.
Wanneer je wordt beperkt, retourneert Microsoft Graph HTTP 429 Te veel verzoeken with a Opnieuw-Proberen-Na header die de te wachten seconden specificeert. Lees deze header altijd en pas je gedrag dienovereenkomstig aan - te veel verzoeken na een 429 verlengt het beperkingsvenster, verkort het niet.
| HTTP-code | Foutnaam | Oorzaak | Repareer |
|---|---|---|---|
| 429 | TeVeelVerzoeken | Rate limit overschreden (10.000 verzoeken / 10 min per app of 1.000 verzoeken / 1 min per gebruiker) | Lees de Retry-After header. Implementeer exponentiële backoff. Gebruik $batch om verzoeken te combineren. |
| 401 | Ongeautoriseerd | Toegangstoken verlopen of ontbrekende autorisatiekop | Vernieuw token via MSAL. Controleer tokenverval voordat elke aanvraag wordt gedaan. Gebruik token-caching. |
| 403 | Verboden | Ontbrekende Mail.Read of Mail.Send toestemming in Azure App Registratie | Voeg vereiste Graph-machtigingen toe in Azure Portal en geef opnieuw toestemming (of admin-toestemming voor app-machtigingen). |
| 404 | ResourceNietGevonden | Bericht-ID of map-ID bestaat niet (verwijderd of verkeerde tenant) | Verifieer ID's via GET voordat je erop reageert. Behandel 404's als een signaal voor een zachte verwijdering. |
| 500 | Interne Serverfout | Tijdelijke Microsoft-serverfout | Probeer opnieuw met exponentieel uitstel (1s, 2s, 4s). Log de request-id header voor Microsoft-ondersteuning. |
Voorbij Microsoft Graph: Unified Email API voor Gmail, Outlook en IMAP
Het beheren van de Microsoft Graph API-e-mailintegratie is slechts het begin. De meeste SaaS-producten moeten Gmail, Outlook en IMAP tegelijkertijd ondersteunen - wat betekent drie afzonderlijke OAuth-stromen, drie token-vernieuwingslussen en drie webhook-systemen. Unipile's unificerende e-mail-API abstraheert alle drie de providers achter een enkel eindpunt.
Met Unipile's geïntegreerde e-mail API-integratie, u schrijft één integratie en ondersteunt direct alle drie de providerstypes. Gekoppelde accounts worden beheerd door Unipile – uw backend communiceert met slechts één REST-eindpunt, ongeacht of de mailbox van de gebruiker draait op Microsoft Graph, Gmail of IMAP.
Geen OAuth-stromen om te beheren Unipile behandelt de acquisitie, verversing en intrekking van tokens namens u voor Microsoft Graph en Gmail.
Geünificeerde webhook-gebeurtenissen - één notificationUrl ontvangt e-mailgebeurtenissen van alle providers met een genormaliseerd JSON-schema. Geen per-provider abonnementenbeheer.
SOC 2 Type II conform - alle e-mailgegevens onderweg zijn versleuteld. Unipile bewaart geen e-mailinhoud buiten wat uw integratie vereist.
Integreer Microsoft Graph E-mail binnen enkele minuten
Sluit u aan bij 200+ SaaS-teams die Unipile gebruiken om Outlook, Gmail en IMAP te verbinden onder één enkele API. Geen vendor lock-in. SOC 2 compliant.
Veelgestelde vragen
Alles wat ontwikkelaars vragen voordat ze bouwen op de Microsoft Graph API e-mail-eindpunten - van authenticatie tot limieten en providerdekking.
https://graph.microsoft.com/v1.0/me/messages en maakt gebruik van OAuth 2.0-authenticatie via Azure Active Directory. Het ondersteunt het lezen, verzenden, zoeken en beheren van e-mails, evenals het ontvangen van realtime wijzigingsmeldingen via webhookabonnementen./v1.0/abonnementen with a typeWijziging (bijv. "gemaakt"), een meldingUrl wijzend naar je HTTPS-eindpunt, en een bron (bijvoorbeeld, "me/mailFolders('Inbox')/messages"). Microsoft stuurt onmiddellijk een GET-verzoek met een validatietoken - uw server moet dit binnen 10 seconden als platte tekst terug echoën. Abonnementen verlopen na maximaal 4230 minuten en moeten vóór het verstrijken ervan worden vernieuwd via PATCH.