1. Begin with customer intent
The lifecycle starts before an API request. A business event—an order shipped, a login challenge started, an appointment changed—creates an intention to communicate. That event needs a stable identity, policy, eligible recipient, approved template, channel decision, and owning application.
If the caller cannot name that operation independently of an HTTP attempt, duplicate prevention will be fragile. Persist a business event ID and derive an idempotency key before making the network call.
2. Durable acceptance is the first platform commitment
Validation should resolve the credential, tenant, app, action, channel, entitlement, price, budget, and recipient format before acceptance. The accepted record, idempotency identity, price snapshot, reservation, queue outbox, customer projection, and audit evidence should commit together.
An HTTP 202 Accepted can then mean something precise: the platform has durably recorded the operation for asynchronous work. It still says nothing about what a provider or recipient has done.
Why the provider call does not belong in the request
A synchronous provider call creates an ambiguous edge: the provider may accept while the customer connection times out. Separating durable acceptance from dispatch gives the system a stable fact to recover from without asking the customer to guess.
3. Provider dispatch is another boundary
A worker claims accepted work with a lease, resolves an allowed route and managed secret, submits one bounded attempt, and records the result. Provider acknowledgement usually proves only that the provider accepted responsibility for further processing. It may not prove downstream network acceptance or handset delivery.
Timeouts after a provider call are especially dangerous. A correct system records the outcome as ambiguous or retryable according to provider semantics; it does not blindly create another customer charge or duplicate message.
4. Delivery evidence can arrive late, twice, or out of order
Callbacks may be duplicated, delayed, replayed, or contradictory. Authenticate the provider, bind each event to the expected account and message, apply monotonic transitions, and preserve contrary terminal evidence for reconciliation instead of overwriting history.
Even a legitimate delivered state usually means a network or provider reported delivery to a device or endpoint. It does not prove the intended person read, understood, or acted on the content.
5. Billing follows evidence, not wishful state
At acceptance, the platform can reserve an amount from a versioned price snapshot. Provider evidence can lead to settlement, release, or a provisional position. Reconciliation may later create an immutable adjustment. A mutable balance is a projection of those ledger events, not the source of truth.
Keep provider cost, service markup, tax, currency, rounding basis, and price version with the billable event. A "live" total should state freshness and whether unresolved events remain.
6. Support needs the same evidence graph
A support agent should be able to work from safe Organization, Project, App, request, message, provider, and billing references without seeing raw credentials or copying full message content. Customer-visible replies and internal operational notes must remain distinct states.
A practical state checklist
| State | What it proves | What it does not prove |
|---|---|---|
| Requested | The customer application intended an operation | Platform acceptance |
| Accepted | MessageHop durably recorded it | Provider or recipient outcome |
| Provider accepted | The selected provider acknowledged it | Destination delivery |
| Delivered | Authenticated delivery evidence was applied | Reading, identity, or business completion |
| Settled | Billing policy posted the event | Universal finality if reconciliation remains open |