E-mail met Microsoft 365
E-mail met Microsoft 365
Microsoft heeft basisauthenticatie voor SMTP en IMAP op Microsoft 365 uitgeschakeld. Een mailboxwachtwoord in een Email Account werkt niet meer — mail moet authenticeren met OAuth 2.0, wat Frappe regelt via een Connected App.
Deze pagina beschrijft het volledige traject: de app-registratie in Entra ID, de Connected App, het Email Account en de autorisatie. Zie Email Account & Inbox voor het algemene e-mailmodel.
Voordat u begint
- Toegang tot Entra ID (Azure AD) om een app te registreren en beheerderstoestemming te geven
- De echte UPN van de mailbox — soms anders dan het adres waarvandaan u verstuurt
- SMTP AUTH ingeschakeld op die mailbox (in veel tenants standaard uit)
- Uw site bereikbaar via HTTPS op een vast domein, voor de redirect-URI
1. De applicatie registreren
Entra-beheercentrum → App registrations → New registration. Noem de app naar wat hem gaat gebruiken, kies single tenant en laat de redirect-URI leeg — die hangt af van een naam die nog niet bestaat (stap 5).
Noteer op Overview de Application (client) ID en de Directory (tenant) ID.
2. Een client secret aanmaken
Certificates & secrets → New client secret. Kopieer de Value meteen — die wordt één keer getoond en daarna nooit meer.
Eén registratie kan meerdere secrets bevatten, en een secret is achteraf niet meer uit te lezen. Geef elk secret dus een omschrijving die benoemt wat hem gebruikt, en noteer de vervaldatum. Er volgt geen waarschuwing wanneer er één verloopt.
3. De mailpermissies toekennen
API permissions → Add a permission → Microsoft Graph → Delegated permissions:
| Permissie | Nodig voor |
|---|---|
SMTP.Send |
Versturen |
IMAP.AccessAsUser.All |
Ontvangen |
Klik daarna op Grant admin consent voor de tenant. Zonder toestemming mislukt het autoriseren in stap 8.
In de lijst kunnen ook Application-permissies staan, zoals IMAP.AccessAsApp. Die horen bij de service-principal-stroom en zijn niet wat een gewoon Email Account gebruikt — de SMTP-sessie authenticeert met een delegated token.
4. De Connected App aanmaken
Connected App → New:
| Veld | Waarde |
|---|---|
| Provider Name | een label, bv. M365 |
| Client ID | Application (client) ID uit stap 1 |
| Client Secret | de Value uit stap 2 |
| Authorization URI | https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize |
| Token URI | https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token |
| Scopes | https://outlook.office365.com/.default, offline_access |
Gebruik de v2.0-endpoints van Microsoft. .default vraagt alles op waarvoor de registratie al toestemming heeft, zodat u de scopes hier niet hoeft op te sommen; SMTP.Send en IMAP.AccessAsUser.All expliciet benoemen werkt ook. offline_access levert het refresh token — zonder die scope valt de verbinding na een uur stil.
Provider Name is alleen een label. De documentnaam — onder de titel in de zijbalk, een korte hash tenzij u hem hernoemd heeft — bepaalt stap 5.
5. De redirect-URI whitelisten
Sla de Connected App op en lees het veld Redirect URI terug. Frappe plakt de documentnaam achter het callback-pad:
https://<site>/api/method/frappe.integrations.doctype.connected_app.connected_app.callback/<documentnaam>
Zet exact die URI in Azure onder Authentication → Add a platform → Web.
De kale .../callback zonder die naam erachter is de meest voorkomende reden dat een connect mislukt. Eén registratie kan meerdere sites bedienen — elke Connected App op elke site voegt zijn eigen callback toe, zoals hierboven.
Hernoemt u een Connected App, sla hem dan opnieuw op zodat validate() de URI herberekent, en whitelist de nieuwe.
6. Het Email Account aanmaken
Email Account → New:
| Veld | Waarde |
|---|---|
| Email Address | het adres waarvandaan u verstuurt |
| Method | OAuth |
| Connected App | het document uit stap 4 |
| Connected User | de desk-gebruiker die gaat autoriseren |
| Outgoing Server | smtp.office365.com, poort 587, TLS |
| Incoming Server | outlook.office365.com, poort 993, SSL |
Connected App en Connected User verschijnen pas zodra Method op OAuth staat.
Wijkt de UPN van de mailbox af van het afzenderadres — u verstuurt als info@bedrijf.nl terwijl de mailbox in werkelijkheid info@bedrijf.onmicrosoft.com is — vink dan Use different Email ID aan en zet de UPN in Alternative Email ID. XOAUTH2 authenticeert de identiteit van het token, niet het alias. Gaat dit mis, dan krijgt u een 535-fout met een token dat verder helemaal in orde is.
7. Instellingen delen over meerdere mailboxen
Bij meer dan één mailbox op dezelfde tenant: zet servers en poorten één keer in een Email Domain en wijs elk Email Account daarnaar door, in plaats van ze telkens te herhalen.
8. Autoriseren
Klik op Authorize API Access op het Email Account (of op Connect to <provider> op de Connected App). Meld u aan als de mailbox en accepteer het toestemmingsscherm. Dat maakt een Token Cache aan met de naam <connected-app>-<connected-user> — het record dat de SMTP-sessie daadwerkelijk uitleest.
Deze stap vereist een browser en is niet te scripten. De aangemelde gebruiker moet overeenkomen met Connected User, anders zoekt de sessie een token cache die niet bestaat. Elke gebruiker autoriseert apart, dus een gedeelde mailbox die meerdere mensen gebruiken krijgt per persoon een eigen cache.
9. Controleren
Verstuur een testmail vanaf het account en controleer of de regel in de Email Queue de status Sent haalt. Een mislukte mail blijft in de queue staan met de fout erbij — begin dan bij de tabel hieronder.
Problemen oplossen
| Symptoom | Oorzaak | Oplossing |
|---|---|---|
535 5.7.3 Authentication unsuccessful met een geldig token |
Aanmelden met het alias in plaats van de UPN van de mailbox | Use different Email ID + Alternative Email ID (stap 6) |
AADSTS50011 redirect-URI komt niet overeen |
Documentnaam ontbreekt in de gewhiteliste URI | Whitelist .../callback/<documentnaam> (stap 5) |
AADSTS65001 toestemming vereist |
Geen beheerderstoestemming gegeven | Geef admin consent op de delegated permissies (stap 3) |
invalid_client |
Client secret verlopen of verkeerd overgenomen | Maak een nieuw secret in Azure, plak het erin en sla op |
SmtpClientAuthentication is disabled |
SMTP AUTH staat uit voor die mailbox | Zet SMTP AUTH per mailbox aan in Exchange |
| Autoriseren lukt, versturen niet | Connected User komt niet overeen met wie geautoriseerd heeft | Corrigeer Connected User en autoriseer opnieuw |
| Werkte wekenlang en valt dan ineens volledig uit | Client secret verlopen | Zie hieronder |
Secret vernieuwen
Client secrets in Entra verlopen — maximaal 24 maanden. Zolang het secret geldig is vernieuwen refresh tokens zichzelf stilletjes, dus er gaat niets stuk tot het verloopt; daarna vallen alle mailboxen op die registratie tegelijk uit.
U kunt niet teruglezen welk secret een Connected App gebruikt: het is versleuteld opgeslagen en ook op het desk gemaskeerd. Probeer bij vernieuwing dus niet te achterhalen welke in gebruik is — maak een nieuw secret aan, plak het in de Connected App en sla op. Zet de nieuwe vervaldatum in een agendaherinnering.