Four guarantees
An endpoint is a contract about what happens before a visitor sees success. These four matter when something breaks later.
1. origin control
accept your origin, refuse others
2. durability before acknowledgement
store the answer before returning success
3. a receipt
name the stored record, so it can be found later
4. separate delivery
notifications are attempts, and they may fail without losing the answer
The response shape
{
"status": "saved",
"saved": true,
"receiptId": "r_71aa"
}
Read it literally. saved: true means the record exists. It says nothing
about whether an email arrived.
A filled contract test
One endpoint, tested on 2026-09-26, four checks in order.
check 1, origin control
POST from the production origin 202, saved true
POST from another origin 403, refused
result pass
check 2, durability before acknowledgement
response time to 202 180ms
row readable immediately after yes, receipt r_8b02
result pass
check 3, receipt
receipt id returned r_8b02
receipt resolves to the stored row yes
result pass
check 4, separate delivery
delivery row created yes, state queued
provider attempt accepted in 42 seconds
response still readable if delivery fails yes, tested by disabling
result pass
what was not tested
- behaviour under a provider outage, which needs fault injection
Acceptance: the endpoint is usable when
- each of the four checks has a recorded result
- the receipt resolves to a stored row
- a failed delivery leaves the response readable
- a retry cannot create a second stored response
- the refuse path is tested, not assumed
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Success with nothing stored | The response is generated before the write | Change the order in the handler |
| Two rows for one submission | No idempotency key | Send one, and honour it |
| Another origin is accepted | The origin rule is missing | Fix the rule, then re-test |
| A retry duplicates a notification | No deduplication | Key the consumer by response id |
| Unknown state after a timeout | The request left, no answer came back | Reconcile, never retry blind |
Limits
An endpoint can prove storage. It cannot prove a person read a message.
Keep the inbox as the source of truth for responses, and treat delivery as a separate, retryable attempt.