notification-service API

Standalone transactional email microservice for Hello World DAO and FounderyOS. Dispatches dual-branded emails via Resend across 14 template types with a CAN-SPAM–compliant digest flow.

Service: notification-service · Port 3100 · AX42-U k3s (founderyos namespace) Epic: PLATFORM-002 (stable)

For the full reference including all endpoints, schemas, sequence diagrams, template catalog, env vars, and error table, see the root API reference at api/notification-service.md.

Quick Reference

Endpoints

Method	Path	Auth	Purpose
POST	/api/v1/send	Bearer service token	Dispatch a single email
GET	/api/v1/health	Public	Liveness probe

Authentication

Authorization: Bearer <TOKEN_NOTIFICATION_SERVICE>

Token source: platform/service-tokens k8s Secret, key TOKEN_NOTIFICATION_SERVICE. Callers read it from NOTIFICATION_SERVICE_TOKEN in their own environment.

Fail-closed: SERVICE_TOKEN unset at boot → 503 on all requests.

Request Shape

{
  "type": "password-reset",       // one of 14 template types
  "to": "user@example.com",
  "domain": "helloworlddao.com",  // or "founderyos.dev"
  "data": { /* template-specific fields */ },
  "attachments": [ ... ]          // optional, max 10, 25 MiB each
}

Success Response

{
  "id": "re_...",
  "status": "sent",
  "stubbed": false,
  "request_id": "aae9048a-31af-4f42-9758-48de4a0fbd8f"
}

14 Template Types

Type	Brand(s)	Category
welcome	DAO + FOS	Transactional
password-reset	DAO + FOS	Transactional
password-changed	DAO + FOS	Transactional
verification	DAO + FOS	Transactional
invitation	DAO + FOS	Transactional
membership-confirm	DAO only	Transactional
renewal-receipt	DAO only	Transactional
payment-receipt	DAO + FOS	Transactional
refund-confirmation	DAO + FOS	Transactional
treasury-milestone	DAO only	Transactional
e2e-test-results	DAO + FOS	Transactional
parental-consent	DAO + FOS	Transactional
event-reminder	DAO + FOS	Transactional + ICS attachment
notification-digest	DAO + FOS	Opt-in (unsubscribe required)

Caller Env Vars

Var	Notes
NOTIFICATION_SERVICE_URL	In-cluster: http://notification-service.founderyos.svc.cluster.local:3100 · Via gateway: https://apis.helloworlddao.com/notify
NOTIFICATION_SERVICE_TOKEN	Matches TOKEN_NOTIFICATION_SERVICE in platform/service-tokens

Related

• Repository — notification-service
• Full API reference
• payment-gateway — fires payment-receipt, refund-confirmation, membership-confirm
• cross-domain-auth — peer off-chain microservice