MCM-11 — Shared Email API

← Back to MCM Nexus overview

As the platform (any MCM instance or the mcm-api service that needs to send email),
I want to call a single Nexus-hosted API to send email rather than each deployment holding its own copy of the email provider credentials,
so that email credentials common to all customers live and rotate in one place instead of being duplicated per customer/instance.

Acceptance Criteria

• Nexus holds the shared email provider credentials (e.g. the Microsoft Graph integration already used by mcm-api, reused rather than standing up a second integration) — these are not distributed to individual customer MCM deployments.
• Nexus exposes an authenticated "send email" API that other MCM services call with a template/payload rather than raw SMTP credentials.
• Callers authenticate using a service identity scoped to "send email only" — no caller can read back the underlying provider credentials through this API.
• Failed sends are retried with backoff and logged; the caller receives a clear success/failure result rather than a silent drop.

---

Technical Design

Nexus exposes a single POST /api/internal/email/send endpoint in mcm-nexus/backend, authenticated by a service identity scoped to send-email-only, so callers — starting with mcm-nexus itself (signup confirmation, request status changes, MCM-07 — Subscription Activation credential delivery, MCM-12 — Nexus Admin Operational Visibility trial-expiry reminders) and mcm-api — pass a template key and variables rather than holding raw SMTP/Microsoft Graph credentials themselves. It reuses the Microsoft Graph integration pattern already implemented in mcm-api (MicrosoftGraphConfig) rather than standing up a second provider integration. Failed sends are retried with backoff and logged, and the API surface never returns credential material — only a send success/failure result.

---

UI / Frontend Changes

• No dedicated customer-facing screen — this story is a backend service other Nexus stories call into, so its visible effect is the emails those stories already send (signup confirmation, activation, trial-expiry reminders).
• Nexus Admin console gains a way to see recent send failures/retries per organization, for support to debug a customer-reported "I never got the email" report.
• No credential-entry UI anywhere: individual MCM services never need to configure their own email provider credentials, since Nexus is the sole holder.