> For the complete documentation index, see [llms.txt](https://docs.limecall.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limecall.com/developers/messages.md).

# Messages API

Send SMS and MMS, and list message history.

| Method | Path             | Scope            |
| ------ | ---------------- | ---------------- |
| `GET`  | `/messages`      | `messages:read`  |
| `GET`  | `/messages/{id}` | `messages:read`  |
| `POST` | `/messages`      | `messages:write` |

## Send a message

```bash
curl -X POST https://app.limecall.com/api/v1/messages \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900123",
    "from": "+441134960000",
    "body": "Your appointment is confirmed for Thursday at 9:30."
  }'
```

| Field       | Notes                                                     |
| ----------- | --------------------------------------------------------- |
| `to`        | Recipient, international format.                          |
| `from`      | One of **your** numbers, and it must have SMS capability. |
| `body`      | The message text.                                         |
| `mediaUrls` | Optional array of URLs for MMS.                           |

{% hint style="warning" %}
A `200` here means LimeCall accepted the message, **not** that it was delivered. Carriers filter silently — unregistered US traffic is accepted and then dropped with no error anywhere. If delivery looks wrong, check registration before debugging your code. See [US carrier registration (10DLC)](/virtual-numbers/us-carrier-registration.md).
{% endhint %}

Opt-outs are enforced upstream of this endpoint: a contact who replied STOP will not receive your message regardless of what you send.

## List messages

```bash
curl "https://app.limecall.com/api/v1/messages?peer=%2B447700900123" \
  -H "Authorization: Bearer sk_live_..."
```

Same filters as [Calls](/developers/calls.md): `page`, `limit`, `userId`, `phoneNumber` (repeatable, matches either leg), `peer`, `since`.

Returns the standard `{ data, pagination }` envelope.

## Get one message

```bash
curl https://app.limecall.com/api/v1/messages/9931 \
  -H "Authorization: Bearer sk_live_..."
```

Use this to check delivery state for a specific message rather than re-listing.