What it does
- Per-account templates. Your wording, your tone, your placeholders. Changing a message is an edit on the platform, not a release on your side.
- Trigger-driven sends. Driver arriving soon, delivery confirmed, delivery attempt failed, job offered to a driver — the moments where a text is the right medium.
- A delivery log. What was sent, to which number, when, how many attempts it took, and the final outcome the carrier reported.
- Carrier-agnostic. The platform holds the carrier credentials and picks a route appropriate to the destination. You write the message and never sign a carrier contract.
How it works
A send is accepted, then delivered
Asking for a message is not the same as waiting for one to arrive. You request a send and receive an immediate acknowledgement with an identifier; the platform then takes responsibility for getting it out. If a carrier is degraded, the message queues and retries rather than failing back to you. Your integration is never left holding an open connection to a slow third party, and a burst of ten thousand messages queues instead of collapsing.
Read back what happened
Because a send is asynchronous, the outcome is something you read rather than something you receive as a return value. The delivery log is the record: every attempt, the final state, and the carrier’s reason if it failed. This is the difference between “we sent it” and “it arrived”, and it is the bit that matters when a customer says they were never told.
Messages to people, not machines
This is worth separating clearly from webhooks. Events and webhooks deliver machine-readable payloads to a server you run. Notifications deliver human-readable messages to a phone. If you want the raw event, subscribe to it. If you want the recipient texted “your delivery is 10 minutes away”, use this.
Separate from email on purpose
SMS and Email Notifications are independent modules because they have genuinely different costs and different uses. Text messages cost real money per message and are read within minutes; email is effectively free and is read whenever. Plenty of accounts want confirmations by email and only time-critical alerts by text, and should not have to pay for both.
Permissions
This module has no permissions of its own yet. The codes below are the ones planned for it — they cannot be attached to an API credential until the module ships. Anything you build against the module today uses the base-platform permissions listed alongside them.
| Permission | What it allows | Needed |
|---|---|---|
| notifications.read | Read message templates, channel configuration and the delivery log. Planned — not yet issuable. Shared with Email Notifications. | Planned |
| notifications.write | Create and edit templates, and request a send. Planned — not yet issuable. Shared with Email Notifications. | Planned |
| drivers.read | Resolve the driver a message is addressed to. | Available |
| stops.read | Resolve the stop and recipient a message concerns. | Available |
| subscriptions.read | Read the webhook subscriptions used to trigger sends from delivery events. | Available |
| subscriptions.write | Register the webhook endpoint that triggers your sends. | Available |
API reference
This module has no public API contract yet. Nothing is callable, and there is no spec to read.
When this module ships an API, its generated OpenAPI 3.1 contract will be published by the service itself and linked here — a browsable reference and the raw openapi.json, both resolving to the environment these docs are served from. Every other Mesh API already works that way; see Geofences for the shape of it.
Events
This module does not raise events of its own today. The events it is expected to raise are listed below so you can plan a subscription around them, but they are not yet published on the event stream.
Delivery-status events — sent, delivered, failed — are planned so you can reconcile without polling the log. Today, the events below are the ones you would subscribe to in order to trigger a text message.
| Event | Raised when | Tells you |
|---|---|---|
| stop.arrived | The driver arrives at a stop. | The trigger behind “your driver has arrived”. |
| stop.completed | A stop reaches its terminal completed state. | The trigger behind a delivery confirmation. |
| stop.failed | A delivery or collection attempt fails. | The reason, so the message can tell the recipient what to do next. |
| geofence.entered | A driver crosses into a boundary near the destination. | The most reliable trigger for “arriving soon”. Requires the Geofences module. |
| run.assigned | A run is assigned to a driver. | The trigger behind a job-offer text to the driver. |
| package.delivered | A package is delivered. | Per-package confirmation where a stop carries several. |
The envelope these arrive in, the delivery and retry guarantees, and every other event type are in Events & webhooks — or jump straight to the event catalog.