Systeem-mailbox configureren en koppelen

Aan het einde van deze gids verstuurt de monitor-systeem-mailbox (monitor) productie-mails via Microsoft Graph vanuit één centraal adres, en heb je de werking met een testmail bevestigd.

Voorwaarden:

  • Je hebt admin-rechten op de Tapster-admin-omgeving.
  • De Azure-mailbox bestaat en je kent het adres, het Azure-tenant-id en de gewenste display name.
  • Je kunt admin-consent geven op de Azure app-registratie (AZURE_CLIENT_ID), of laat dit doen door een collega met die rechten.
  • De backend staat op een versie waarin systeem-mailboxen aanwezig zijn.

Voor achtergrond, zie de explanation. Voor velden en endpoints, zie de reference.

1. Seed-record aanmaken (alleen eerste keer per omgeving)

Vanuit de repo-root, op de doelomgeving (of via je deploy-pipeline):

npm run seed:system-mailbox-monitor -w apps/api

Verwachte output:

[seed-system-mailbox-monitor] seed-record aangemaakt voor 'monitor'. Admin moet via UI configuratie en consent voltooien.

Of, als het record al bestond:

[seed-system-mailbox-monitor] bestaand record voor 'monitor', geen wijziging.

Het script is idempotent, herhaling is veilig.

2. Monitor-templates taggen (alleen eerste keer per omgeving) 

npm run tag:monitor-templates -w apps/api

Dit zet systemMailboxKey: 'monitor' op alle bestaande monitor-campagne-templates (uitnodiging, 1e reminder, 2e reminder) over alle tenants. Templates met al een gezette key worden overgeslagen.

3. Configuratie invoeren via de admin-UI

  1. Open /admin/systeem-mailboxen. Je ziet één rij: monitor.
  2. Klik op de rij. Je komt op /admin/systeem-mailboxen/monitor.
  3. Vul in:
  • Display name: de naam die respondenten in hun inbox zien (bijvoorbeeld Monitor Cliëntmedezeggenschap).
  • Azure tenant id: de tenant-id van het Azure-account waar de mailbox staat.
  • Mailbox-adres: het volledige e-mailadres, bijvoorbeeld info@monitorclientmedezeggenschap.nl.
  • Bewaar in Verzonden: aanvinken als Microsoft Graph een kopie in de Verzonden-map moet plaatsen.
  1. Klik Opslaan. Je krijgt een snackbar “Opgeslagen”.

Op dit moment staat de status nog op “consent niet verleend” en gaat er nog niets uit.

  1. Op dezelfde detailpagina, klik Koppel met Microsoft. Er opent een Microsoft-popup.
  2. Log in met een account dat admin-consent mag verlenen op de Azure app-registratie van Tapster.
  3. Bevestig de gevraagde permissies.
  4. Microsoft redirect naar /system/mailboxes/azure/callback. De popup toont een succes-bericht.
  5. De detailpagina polt elke 5 seconden (max 2 minuten) op de consent-status. Zodra die op granted = true springt, sluit de popup en zie je een snackbar “Mailbox gekoppeld”.

Lukt het niet binnen 2 minuten? Sluit de popup en klik nogmaals op Koppel met Microsoft. De polling-status reset.

5. Testmail versturen

  1. Vul onder “Stuur testmail” je eigen e-mailadres in.
  2. Klik Stuur testmail. De backend gebruikt de net gekoppelde mailer om een mail naar dat adres te sturen.
  3. Bij succes: snackbar “Testmail verstuurd”. Check je inbox, controleer afzender en display name.
  4. Bij fout: snackbar toont de foutboodschap, en de detailpagina herlaadt zodat lastErrorAt/Message zichtbaar wordt.

6. Productie-monitor-mails verifiëren

Vanaf nu pakt de BullMQ-worker send-scheduled-messages automatisch de tag op:

  • Nieuwe Messages aangemaakt vanuit getagde templates erven systemMailboxKey: 'monitor'.
  • MailProviderService.send routeert ze naar de systeem-mailbox.

Wil je verifiëren? Trigger een monitor-uitnodiging via de normale UI of dispatch handmatig, en controleer in MongoDB op de tenant dat de gegenereerde Message het veld systemMailboxKey: 'monitor' heeft. De afzender van de uitgaande mail is dan het systeem-adres.

Wat te doen bij fouten

Symptoom Oorzaak Actie
Snackbar “Testmail verstuurd”, maar geen mail in inbox Spam-filter, of Graph wel geaccepteerd, levering vertraagd Wacht enkele minuten, check spam, controleer in Azure Mail Flow
Snackbar “Mislukt: … 401 …” of “… 403 …” Consent ingetrokken Azure-side Status springt automatisch naar granted = false. Klik opnieuw Koppel met Microsoft
Snackbar “Mislukt: … is not configured” Veld leeg of seed niet gedraaid Controleer formuliervelden, draai stap 1 als het record ontbreekt
Banner toont lastErrorAt na productie-mails Transient Graph-fout (rate limit, 5xx) Bekijk lastErrorMessage, BullMQ-retry pakt opnieuw op
Monitor-mail blijft op status ERROR Systeem-mailbox niet bereikbaar, geen fallback ontworpen Los de mailbox-fout op, retry de message via bestaande retry-flow

Er is bewust geen automatische terugval op de tenant-mailbox. De afspraak is dat monitor-mails altijd vanuit één adres komen. Bij outage stapelen mails op tot de mailbox weer werkt.

Inrichten aliassen i.c.m. shared-mailboxen

Om aliassen te kunnen gebruiken is het noodzakelijk om de mailbox te koppelen aan een alias. Gebruik deze handleiding: https://michev.info/blog/post/4081/send-as-alias-for-a-shared-mailbox-in-exchange-online