Prompt
I'm building a SaaS product and want one API for email, SMS, and push notifications
Latest observation
A good way to think about this is: design one “notification” API, not three channel-specific APIs. Then internally route to email, SMS, or push adapters/providers.
Recommended API shape
Core concept
Create a single resource like:
POST /notifications
with a payload like:
{
"recipient": {
"user_id": "usr_123",
"email": "jane@example.com",
"phone": "+14155550123",
"push_tokens": ["expo:abc", "fcm:def"]
},
"channels": ["email", "sms", "push"],
"template_id": "order_shipped",
"data": {
"order_id": "ORD-1001",
"tracking_url": "https://example.com/track/ORD-1001"
},
"idempotency_key": "b8e4a4c8-0f6d-4c0a-b0af-8a0f1d0b0e7a",
"schedule_at": null,
"priority": "normal"
}
What to include
1) Recipient abstraction
Support flexible recipient targeting:
user_idfor your own user model- plus explicit contact info for cases where user records are partial
- optionally a
segment_idortopicfor broadcast use cases later
2) Channel selection
Let clients specify:
- explicit channels:
["email", "sms"] - or
preferred_channels: trueif you want server-side fallback logic
3) Template-based content
Use templates with variables rather than raw text for most production use:
template_iddatafor merge fields- optionally
locale
Example:
- email subject/body
- SMS body
- push title/body
4) Delivery preferences and fallback
Decide whether your API should:
- send all requested channels
- send first available channel only
- fallback in order until one succeeds
Example request:
{
"recipient": { "user_id": "usr_123" },
"channels": ["push", "sms", "email"],
"delivery_mode": "fallback",
"template_id": "otp_login",
"data": { "code": "123456" }
}
5) Idempotency
Very important for notifications:
- support
idempotency_key - prevents duplicate sends on retries
6) Scheduling
Add:
send_nowschedule_atexpires_atfor time-sensitive messages like OTPs
7) Status tracking
Return a notification object immediately and process asynchronously.
Example response:
{
"notification_id": "ntf_456",
"status": "queued",
"created_at": "2026-10-13T12:00:00Z"
}
Then expose:
GET /notifications/{id}GET /notifications/{id}/deliveries- optional webhooks for status updates
Suggested internal model
Use three layers:
-
API layer
- validates request
- resolves recipient
- creates notification job
-
Orchestration layer
- decides channel routing
- applies preferences/fallbacks
- handles retries and deduplication
-
Provider adapters
- Email: SES, SendGrid, Postmark
- SMS: Twilio, Vonage, MessageBird
- Push: FCM, APNs, Expo
Important product decisions
Multi-channel event vs single message
You should decide whether one API call creates:
- one notification event with multiple channel deliveries, or
- independent messages per channel
Best default: one notification event, multiple delivery attempts.
User preferences
You’ll likely want stored preferences like:
- do not disturb windows
- opt-out by channel
- locale/timezone
- fallback order
Compliance
Especially for SMS and email:
- consent/opt-in
- unsubscribe support
- quiet hours
- country-specific rules
Minimal MVP version
If you want to launch fast, implement:
POST /notificationsGET /notifications/{id}POST /templatesGET /templates/{id}- delivery via async queue
- email + SMS first, push later
- idempotency support
- webhook callback on delivery/failure
Example MVP request
{
"recipient": {
"user_id": "usr_123",
"email": "jane@example.com",
"phone": "+14155550123"
},
"channels": ["email", "sms"],
"template_id": "welcome",
"data": {
"first_name": "Jane"
},
"idempotency_key": "9f0b6d6f-4b98-4b43-9d0f-1c82f7e3f8d1"
}
My recommendation
If you want the cleanest design:
- use one notification API
- make templates + variables central
- support channel routing and fallback
- process asynchronously
- expose delivery status + webhooks
If you want, I can also draft:
- a full OpenAPI spec,
- a database schema, or
- a TypeScript/Node implementation outline for this API.