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

# Messages

Send and read SMS/MMS on your LimePhone numbers.

## Send a message

`POST /v1/messages` — scope `messages:write`

Sends an SMS (or MMS with `mediaUrls`) from one of your LimePhone numbers. Returns `201` with the created message.

| Field       | Type      | Required | Notes                                                                                                  |
| ----------- | --------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `to`        | string    | yes      | Destination number, E.164 (`+14155550134`)                                                             |
| `from`      | string    | yes      | One of your LimePhone numbers                                                                          |
| `body`      | string    | yes      | Message text. Supports personalization tokens like `{{firstName}}`, rendered from the matching contact |
| `mediaUrls` | string\[] | no       | Public media URLs to attach (MMS)                                                                      |

Content is screened before sending; prohibited content returns `400` with the violations listed.

```bash
curl -X POST https://dashboard.limephone.io/api/v1/messages \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550134",
    "from": "+442080580300",
    "body": "Hi {{firstName}}, your appointment is confirmed for 3pm."
  }'
```

```javascript
// Node.js
const res = await fetch('https://dashboard.limephone.io/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LIMEPHONE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+14155550134',
    from: '+442080580300',
    body: 'Hi {{firstName}}, your appointment is confirmed for 3pm.',
  }),
});
const message = await res.json();
```

```python
# Python
import os, requests

message = requests.post(
    "https://dashboard.limephone.io/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['LIMEPHONE_API_KEY']}"},
    json={
        "to": "+14155550134",
        "from": "+442080580300",
        "body": "Hi {{firstName}}, your appointment is confirmed for 3pm.",
    },
).json()
```

## List messages

`GET /v1/messages` — scope `messages:read`

Lists messages, newest first, with standard [pagination](/api-reference/rate-limits-errors-and-pagination.md).

## Get a message

`GET /v1/messages/{id}` — scope `messages:read`

Fetches one message by id, including direction, body, status and timestamps.