> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moritosh.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages

> The core object you send and track

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

```mermaid theme={null}
stateDiagram-v2
    [*] --> queued
    queued --> sending
    queued --> cancelled
    sending --> sent
    sent --> delivered
    sent --> bounced
    sending --> failed
```

| Status      | Meaning                                                                                          |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `queued`    | Accepted and waiting to be handed off. Can still be [cancelled](/api-reference/messages/cancel). |
| `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](/api-reference/messages/retrieve) or, better, by subscribing to [webhooks](/webhooks).

## Channels

A single endpoint, [Send a message](/api-reference/messages/send), 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](/concepts/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.

```json theme={null}
{
  "channel": "email",
  "to": "ada@example.com",
  "from": "billing@notifications.acme.com",
  "template_id": "tmpl_8f3e2a",
  "metadata": { "invoice_id": "inv_1042", "customer_id": "cus_88a1" }
}
```