# Look up a message

> GET /v1/messages — check the delivery status of a message you sent.
> Source: https://onpad.in/docs/api/get-message

Returns the current state of a message you sent through the API.

```text
GET https://app.onpad.in/api/v1/messages?id={id}
```

## Parameters

| Parameter | In | Required | Description |
|---|---|---|---|
| `id` | query | Yes | The message id returned by [POST /messages](https://onpad.in/docs/api/send-message) |

## Example

```bash
curl "https://app.onpad.in/api/v1/messages?id=6f1b9a2c-4d7e-4a31-9f08-2b5c7d1e3a40" \
  -H "Authorization: Bearer wh_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## Response

```json
{
  "ok": true,
  "message": {
    "id": "6f1b9a2c-4d7e-4a31-9f08-2b5c7d1e3a40",
    "to": "+919876543210",
    "type": "template",
    "status": "delivered",
    "meta_message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMUY4...",
    "attempts": 1,
    "error": null,
    "created_at": "2026-10-04T09:21:33+05:30",
    "sent_at": "2026-10-04T09:21:35+05:30",
    "delivered_at": "2026-10-04T09:21:37+05:30",
    "read_at": null
  }
}
```

## Statuses

| Status | Meaning |
|---|---|
| `queued` | Accepted, waiting for the worker |
| `processing` | Being sent to Meta right now |
| `sent` | Meta accepted it and is delivering |
| `delivered` | It reached the recipient's phone |
| `read` | The recipient opened it |
| `failed` | It did not go. `error` says why |

`read` only appears if the recipient has read receipts switched on. Plenty of people do not, so absence of `read` says nothing about whether the message was seen.

## Status codes

| Code | Meaning |
|---|---|
| `200` | Found |
| `401` | `invalid_api_key` |
| `404` | `message_not_found` — no such id in this workspace |
| `422` | `missing_message_id` — the `id` parameter was not provided |

A message belonging to a different workspace returns `404`, not `403` — the API does not confirm that an id exists somewhere else.

## How to poll

Delivery usually completes within seconds, but a switched-off phone can delay it for hours.

A reasonable approach:

1. Wait 2 seconds after the `202`, then check.
2. If still `queued` or `processing`, check again after 5 seconds, then 15, then 30.
3. Once `sent`, the message is with Meta — `delivered` may follow at any time, or much later.
4. Stop polling at `delivered`, `read` or `failed`. Those are final as far as the API is concerned.

Do not poll in a tight loop. Nothing changes faster than the worker runs, and every call is logged against your key.

If you need delivery updates pushed to you rather than polled, say so — webhooks are planned and knowing who needs them decides the order they arrive in.