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

# Send and receive messages

> Send multipart Messages with text, media, links, replies, mentions, and reactions.

A message is an ordered list of parts sent to one chat.

Your agent sends a message with one to 100 parts. Text carries the words and an optional mention, and media carries a file you uploaded or a public HTTPS URL. A link carries one URL that Relay shows as a preview on the phone, and it must be the only part in its message.

Relay stores the message, records Delivered for each recipient at the moment it commits, and returns it to you with `202`. Recipients receive it as a `message.received` event on their webhook or WebSocket. Later, the same message ID lets you reply to it or react to one part.
A read-back message also carries its `thread` originator; see [Threads](/messages/replies#read-threads).

## Choose a send path

| Path                                | Use                                                                                              |
| ----------------------------------- | ------------------------------------------------------------------------------------------------ |
| `POST /v1/messages`                 | You know the recipient handles but not the chat. Relay resolves or creates the chat, then sends. |
| `POST /v1/chats/{chatId}/messages`  | You know the chat ID.                                                                            |
| `POST /v1/chats/{chatId}/voicememo` | Send an uploaded audio Attachment as a voice memo.                                               |

Follow [Send a message](/messages/send) for both text paths and [Voice memos](/messages/voice-memos) for the third.

## Read the delivery state

Every message you read carries `delivery_status`. It moves in one direction.

| State       | Meaning                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `sent`      | Relay stored the message and delivered it to nobody. A send blocked for every recipient stays here. |
| `delivered` | Relay stored the message and recorded delivery for at least one recipient.                          |
| `read`      | Every recipient whose delivery was not withheld marked the chat Read.                               |

[Delivery receipts](/messages/receipts) explains what Delivered means and how an agent marks Read.

## When it fails

A send is refused before anything is stored when the chat could not exist:

| Cause                                         | Status | Code                               |
| --------------------------------------------- | ------ | ---------------------------------- |
| The chat would have no agent                  | `403`  | [2028](/api-reference/errors#2028) |
| A blocked pair                                | `403`  | [2026](/api-reference/errors#2026) |
| A person whose setting screens your agent out | `403`  | [2030](/api-reference/errors#2030) |

A send that conflicts with an earlier one under the same idempotency key returns `409`. Each send page lists its own errors.

## Next steps

* [Send a message](/messages/send)
* [Build message parts](/messages/parts)
* [Upload attachments](/messages/attachments)
* [Read delivery receipts](/messages/receipts)