Notes
Requirements
The requirements. A caller sends one request: a user, a template and variables. The service fans it out to email, SMS and push, with text written for each channel. It respects the user's preferences, except that security alerts always go out. Marketing is rate-limited per user. Failed sends are retried with backoff and finally parked in a dead-letter list. A caller retrying the same request must not cause a second message. And we track sends, opens and clicks.
Clarify. Notify does not wait for delivery; it queues the work and returns, because providers can take seconds. The guarantee is at least once, with idempotency keys removing duplicate requests. Three categories: transactional, marketing and security. Marketing is limited to two per channel per hour. Three attempts per message, waiting one second and then two. And a template with a missing variable is rejected before anything is queued.
- notify(user, template, vars)
- channels: email, SMS, push
- one template, text per channel
- respect user preferences
- security alerts always sent
- rate-limit marketing per user
- retry failures with backoff,
- then a dead-letter list
- a retried request sends once
- track sent, opened, clicked
- does notify() wait for delivery?
- no: queue it, return at once
- delivery guarantee?
- at least once, deduped by key
- which categories?
- transactional, marketing,
- security
- limits?
- 2 marketing per channel per hour
- retries? 3 attempts: 1 s, 2 s
- missing variable? reject early
Entities
The entities. The service sits in the middle. Templates hold text per channel. Preferences say which channels a user accepts and which categories they muted. The rate limiter counts messages per user, channel and category. Idempotency keys remember requests already handled. The outbox holds messages waiting to be sent. Channel senders talk to the providers, and delivery listeners hear about everything that happens.
Class diagram
The model. Channels and categories are enums. A request carries an idempotency key, the user, the template and the variables. Fan-out turns one request into several messages, one per channel, each with its own id, address and rendered body. Every step produces an event with a status: queued, sent, retrying, dead, skipped, rate limited, opened or clicked. All of these are immutable records, so they can be passed between threads freely.
enum Channel { EMAIL, SMS, PUSH }
enum Category { TRANSACTIONAL,
MARKETING, SECURITY }
record Request(String idempotencyKey,
String userId, String templateId,
Map<String, String> vars)
record Message(id, userId, channel,
to, body)
record Event(messageId, userId,
channel, Status status, attempt) Templates
Templates. One template has a body per channel, because an email can be friendly and long while an SMS must be short. Rendering replaces each variable in double braces. All channels are rendered before anything is queued, so a missing variable rejects the whole request instead of sending the email and failing the SMS. In the demo, forgetting the order number is rejected with a clear message naming the template and the variable.
EMAIL: Hi {{name}}, order {{order}}
has shipped. Track it in the app.
SMS: Order {{order}} shipped.
PUSH: Your order {{order}} is on
its way
render: replace each {{var}};
missing var -> throw, nothing sent
"order_shipped: missing variable
order" Preferences
Preferences. Each user lists the channels they accept and the categories they muted. The rule lives in one method on the preferences record: the channel must be accepted, and the category must not be muted, unless it is security. A sign-in alert must reach you even if you turned off everything else. In the demo, the second customer muted marketing and transactional messages, so the sale is skipped but the login alert still arrives by email.
record Preferences(Set<Channel> chans,
Set<Category> muted) {
boolean allows(Channel c, Category k) {
return chans.contains(c)
&& (k == SECURITY
|| !muted.contains(k));
}
}
customer-2 muted marketing:
sale skipped, login alert sent Strategy: channels
Each channel is a Strategy behind one interface: it names its channel and sends a message, throwing on failure. The service keeps them in an enum map and picks one by the message's channel, so there is no switch statement on channel anywhere in the service. Adding a chat app channel means one enum value and one sender class. In tests, a fake sender records what it sent and can be told to fail its next few calls.
interface ChannelSender {
Channel channel();
void send(Message m); // throws
}
EmailSender: SMTP or an email API
SmsSender: an SMS gateway
PushSender: a push provider
Map<Channel, ChannelSender> senders
= new EnumMap<>(Channel.class)
new channel: one class + one enum Flow: notify
The notify flow. First add the idempotency key to a concurrent set; if it was already there, this is a retry of a request we have handled, so return zero. Render every channel. Then for each channel: if the user has no address there or the preferences forbid it, record skipped; if the limiter says no, record rate limited; otherwise put a job in the outbox, due now, and record queued. The demo queues three messages, and the identical retry queues none.
if (!seenKeys.add(key)) return 0
render every channel (may throw)
for each channel:
no address or !prefs.allows
-> SKIPPED
!limiter.tryAcquire
-> RATE_LIMITED
else outbox.add(job due now)
-> QUEUED
Queued 3; duplicate queued 0 Rate limits
Rate limits protect users from being spammed. Each category has an hourly limit, and only marketing has one here; a shipping update or a security alert should never be dropped for being too frequent. The key is user, channel and category, and a fixed one-hour window counts messages. The check and the increment happen inside one atomic compute call on a concurrent map, so two threads can never both take the last slot. Four sale requests send two and limit two.
Map<Category, Integer> perHour
MARKETING -> 2, others: no limit
key = user|channel|category
windows.compute(key, (k, w) -> {
new hour? w = {hour, 0}
ok = w.count < limit; if ok count++
return w
})
4 sale requests -> 2 sent, 2 limited Flow: deliver and retry
Delivery. Workers call process-due in a loop. The outbox is a priority queue ordered by due time, so the next job to send is always at the head. A worker takes each due job and sends it. On failure, if attempts remain, the job goes back in with a later due time, one second, then two, then four. After the third attempt it moves to the dead-letter list for a human or a later replay. In the demo the SMS provider fails twice and the third attempt succeeds.
while ((j = takeDue()) != null)
try { sender(j).send(j.msg)
-> SENT }
catch (RuntimeException e)
attempt == 3 -> deadLetters, DEAD
else re-add with dueAt =
now + 1000 << (attempt - 1)
-> RETRYING
outbox: PriorityBlockingQueue by dueAt Observer: engagement
Engagement tracking is the Observer pattern. The service publishes an event for every status change, and the tracker is just one listener, counting events per channel and status. Opens come from a tracking pixel and clicks from a redirect link, both calling track with the message id. In the demo, four emails were sent and one was opened, a twenty-five percent open rate. An audit log, a metrics exporter or an alert on dead letters are more listeners, with no change to the service.
- listens to every event
- counts per channel and status
- track(id, OPENED) from a pixel
- track(id, CLICKED) from a link
- Email sent 4, opened 1,
- open rate 25%
- other listeners: audit log,
- metrics, alerting on DEAD
Concurrency
Concurrency. The idempotency set's add is atomic, so when two threads submit the same key, exactly one wins. The limiter uses compute per key. The outbox is a blocking priority queue, but peeking at the head and polling it are two steps, so take-due is synchronized; otherwise two workers could both see the same due job. In the demo, eight threads send eight hundred requests, every key twice, four workers drain the outbox, and exactly four hundred emails go out.
- seen keys: ConcurrentHashMap set
- add() is atomic: one winner
- limiter: compute() per key
- outbox: PriorityBlockingQueue
- takeDue(): synchronized peek+poll
- so two workers never share a job
- listeners: CopyOnWriteArrayList
- 8 threads, 800 requests, 400
- unique -> exactly 400 emails
Extensibility
Extensions. A new channel is one sender class. Quiet hours delay a message to the morning by setting its due time, rather than dropping it. Low-priority messages can be batched into a daily digest. If push fails permanently, fall back to SMS. Give security its own high-priority lane. Store templates per locale. And in production the outbox must be durable, a database table or a message queue, so a restart never loses a message.
- new channel: chat app, webhook
- quiet hours: delay, do not drop
- digest: batch low-priority ones
- channel fallback: push failed?
- try SMS (chain of strategies)
- priority lanes: security first
- per-locale templates
- durable outbox: a database table
- or a message queue
Testing
The full code is below the player. Fake senders record messages and fail on command, and a fake clock moves the retry timers. The demo fans one order out to three channels and retries SMS twice, ignores a duplicate request, skips a muted sale but delivers a login alert, rate-limits marketing, dead-letters a message after three failures, rejects a missing variable, computes an open rate, and finally proves exactly-once sending under concurrent duplicate requests.
Queued 3 Duplicate request queued 0 [RETRYING] SMS m2 attempt 1 [RETRYING] SMS m2 attempt 2 SMS after retries: Order A-1001 shipped. customer-2 got: New sign-in to your.. 4 sale requests: 2 rate limited [DEAD] SMS m17 attempt 3 open rate 25% 800 requests (400 unique) -> 400
Follow-ups
Expect follow-ups. Exactly once is not possible across a provider, so aim for at least once with idempotency keys and provider-side deduplication. A provider down for an hour? Put a circuit breaker per provider and stop burning retries. A campaign to millions of users? Partition the work through a message queue to many workers. Delivery receipts come back by webhook as more events. And re-check preferences at send time, in case the user unsubscribed while the message waited.
- at most once vs at least once?
- at least once + provider dedupe
- a provider is down for an hour?
- circuit breaker per provider
- millions of users per campaign?
- partition, queue, many workers
- did the SMS arrive?
- delivery receipts by webhook
- user unsubscribes mid-campaign?
- check preferences at send time
Say it like this
The short version. Notify dedupes the request by its key, renders every channel up front, then for each channel checks preferences and the rate limit and queues a job in an outbox ordered by due time. Each channel is a sender strategy. Workers send due jobs, retry failures with exponential backoff, and dead-letter after three attempts. Every status change is an event, and engagement tracking is one observer of those events.
- "notify() dedupes by key, renders
- every channel first, then per
- channel checks preferences and a
- rate limit and queues a job. One
- sender strategy per channel.
- Workers retry with backoff, then
- dead-letter. Every status change
- is an event for observers."