Skip to main content
A message is a single email, SMS, or push notification sent to one recipient. Every send creates a message, and every message progresses through a well-defined set of statuses.

​
The message lifecycle

StatusMeaning
queuedAccepted and waiting to be handed off. Can still be cancelled.
sendingBeing handed off to the carrier. No longer cancellable.
sentHanded off successfully. Doesn’t guarantee the recipient received it.
deliveredThe receiving server confirmed delivery. Not available for every SMS carrier.
bouncedPermanently failed — invalid address, disconnected number, etc.
failedFailed for a reason other than a bounce (e.g. carrier outage).
cancelledCancelled before it left the queue.
Track these transitions either by polling Retrieve a message or, better, by subscribing to webhooks.

​
Channels

A single endpoint, Send a message, handles all three channels. The channel field determines which other fields are required:
Channelto formatRequired content fields
emailEmail addresssubject and (html or text)
smsE.164 phone numbertext
pushDevice tokentext
In every channel, template_id can replace the content fields — see Templates.

​
Metadata

Attach your own key-value pairs to a message with metadata. Pulsewave stores it and echoes it back on the message and every event it generates, so you can correlate deliveries with records in your own system without maintaining a separate mapping table. 
{
  "channel": "email",
  "to": "ada@example.com",
  "from": "billing@notifications.acme.com",
  "template_id": "tmpl_8f3e2a",
  "metadata": { "invoice_id": "inv_1042", "customer_id": "cus_88a1" }
}