# Notification Service Refinement — Design

**Date**: 2026-03-16
**Component**: Notification Service (`docs/requirements/Component-NotificationService.md`)
**Status**: Approved

## Problem

The Notification Service doc covered notification lists and the script API but lacked concrete SMTP configuration details, OAuth2 support for Microsoft 365, delivery behavior (recipient handling, error classification), and content format specification.

## Decisions

### SMTP Configuration
- Standard fields: server hostname, port, TLS mode, from address.
- **Dual authentication modes**: Basic Auth (username/password) for on-prem relays, and OAuth2 Client Credentials (Tenant ID, Client ID, Client Secret) for Microsoft 365.
- OAuth2 token lifecycle (fetch, cache, refresh) handled internally by the Notification Service.
- Connection timeout (default 30s) and max concurrent connections (default 5) configurable.

### Email Delivery
- **Single email per send** with all recipients in BCC. From address in To field. Recipients don't see each other.
- **Plain text only** — no HTML content. Operational notifications don't need rich formatting.

### Error Classification
- Consistent with External System Gateway pattern:
  - **Transient failures** (connection errors, SMTP 4xx): Go to Store-and-Forward for retry.
  - **Permanent failures** (SMTP 5xx): Error returned synchronously to calling script. No retry.

### Rate Limiting
- **No application-level rate limiting**. SMTP server limits (e.g., Microsoft 365 throttling) manifest as transient failures handled by S&F naturally.

## Affected Documents

| Document | Change |
|----------|--------|
| `docs/requirements/Component-NotificationService.md` | Expanded SMTP configuration with OAuth2 support, connection settings. Added Email Delivery Behavior section (recipient handling, error classification, rate limiting). Specified plain text content. |

## Alternatives Considered

- **Basic Auth only**: Rejected — Microsoft 365 has deprecated basic auth for SMTP. OAuth2 Client Credentials is required.
- **Individual email per recipient**: Rejected — adds SMTP traffic and S&F complexity for rare partial-failure scenario.
- **All recipients in To (visible)**: Rejected — BCC is safer, avoids exposing email addresses across teams.
- **All SMTP failures to S&F**: Rejected — permanent 5xx errors (bad address) would waste buffer space and never succeed.
- **HTML email support**: Rejected — YAGNI. Operational notifications are plain text. HTML adds injection risk with script-generated content.
- **App-level rate limiting**: Rejected — SMTP server enforces its own limits. S&F handles transient throttling naturally.
- **No OAuth2 / connection tuning**: Rejected — user requires Microsoft 365 support (OAuth2 mandatory) and wants connection timeout/concurrency control.
