Messages - Pulsewave

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

Status	Meaning
`queued`	Accepted and waiting to be handed off. Can still be cancelled.
`sending`	Being handed off to the carrier. No longer cancellable.
`sent`	Handed off successfully. Doesn’t guarantee the recipient received it.
`delivered`	The receiving server confirmed delivery. Not available for every SMS carrier.
`bounced`	Permanently failed — invalid address, disconnected number, etc.
`failed`	Failed for a reason other than a bounce (e.g. carrier outage).
`cancelled`	Cancelled 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:

Channel	`to` format	Required content fields
`email`	Email address	`subject` and (`html` or `text`)
`sms`	E.164 phone number	`text`
`push`	Device token	`text`

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" }
}