# Messages API

> Read stable message pages and send idempotent text or one-file replies to accessible conversations.


## List messages

```http
GET /v1/conversations/{conversation_id}/messages?limit=50&cursor=<opaque_cursor>
Authorization: Bearer <token>
```

Requires `messages:read`. Messages are ordered by source timestamp and ID, newest first.

```json
{
  "data": [
    {
      "id": "m12345678901234567890123",
      "conversation_id": "c23456789012345678901234",
      "sender_identity_id": "s12345678901234567890123",
      "direction": "inbound",
      "service": "imessage",
      "status": "observed",
      "delivery_status": "unknown",
      "text": "Can you send the invoice?",
      "version": 1,
      "source_timestamp": "2026-09-24T00:59:58Z",
      "created_at": "2026-09-24T01:00:00Z"
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  }
}
```

`observed` means Coop found the message in Apple Messages. It does not mean that the recipient read it.

## Send a message

```http
POST /v1/messages
Authorization: Bearer <token>
Idempotency-Key: crm-event-01J8...
Content-Type: application/json

{
  "conversation_id": "c23456789012345678901234",
  "sender_identity_id": "s12345678901234567890123",
  "text": "The invoice is on its way."
}
```

Requires `messages:send`. A successful request returns `202 Accepted`, a `Location: /v1/messages/{message_id}` header, and the current Message representation.

By default, the request sends only to an existing conversation allowed by the team policy. Find the Contact and conversation first.

An Owner can turn on **Allow new recipients** for a specific token in **Settings → API**. That token may replace `conversation_id` with a one-address `to` array:

```json
{
  "to": ["+15551234567"],
  "sender_identity_id": "s12345678901234567890123",
  "text": "Your appointment is confirmed."
}
```

Supply exactly one of `conversation_id` or `to`. The request accepts one normalized phone number or email address and does not create group conversations. A token without the setting receives `403 Forbidden` for `to` requests.

To send one file, upload it first. The upload and the message each use their own idempotency key. The file must be 25 MiB or smaller, and the sender must be an iMessage identity on a Relay that can send attachments.

```http
POST /v1/media?name=invoice.pdf
Authorization: Bearer <token>
Content-Type: application/pdf
X-Coop-Upload-Request-ID: crm-file-01J8...
X-Coop-Content-SHA256: <lowercase sha256 of the raw bytes>
```

The body is the raw file. Requires `messages:send`. A successful upload returns `201 Created`:

```json
{
  "upload_id": "u12345678901234567890123",
  "message_id": "m12345678901234567890123",
  "attachment": {
    "id": "a12345678901234567890123",
    "name": "invoice.pdf",
    "mime_type": "application/pdf",
    "size": 1204,
    "sha256": "<lowercase sha256>",
    "state": "complete"
  }
}
```

Send that file by repeating both ids. Text is optional when an attachment is present. Supply both ids together, or neither.

```json
{
  "conversation_id": "c23456789012345678901234",
  "sender_identity_id": "s12345678901234567890123",
  "message_id": "m12345678901234567890123",
  "attachment_upload_id": "u12345678901234567890123",
  "text": "The invoice is attached."
}
```

The same pair works when `to` replaces `conversation_id`. An upload belongs to the token that created it. Another token, or a dashboard member, cannot claim it.

A message that has a file includes `attachments`. Each item has `id`, `name`, `mime_type`, `size`, `sha256`, and `state`. The array is omitted when the message has no file.

## Download an attachment

```http
GET /v1/messages/{message_id}/attachments/{attachment_id}
Authorization: Bearer <token>
```

Requires `messages:read`. The token must already be allowed to read that message. The response is the decrypted file with `Content-Disposition: attachment`, `Cache-Control: private, no-store`, `X-Content-Type-Options: nosniff`, and a sandbox content security policy. Coop does not return a storage URL. Images are downloaded the same way as other files.

An arbitrary-recipient send follows the Owner New Chat privacy boundary. The resulting unknown conversation stays hidden from team members until an Owner shares it. A token with `messages:read` can follow the returned `Location` to inspect the messages it created. Conversation history remains unavailable to the token until the team policy allows that conversation.

Every create request requires an `Idempotency-Key`. Repeating the same key with the same normalized input returns the existing Message without sending twice. Reusing the key with different input returns `409 Conflict` with problem type `urn:coop:error:idempotency_conflict`.

Outbound status can be `blocked`, `sending`, `uncertain`, `observed`, or `failed`. `blocked` means no Relay accepted dispatch. `uncertain` means dispatch may have begun but Coop has not confirmed the Apple Messages observation; do not create another send to compensate because that can duplicate the message.

## Get message status

```http
GET /v1/messages/{message_id}
Authorization: Bearer <token>
```

Requires `messages:read`. The response contains the current Message representation. Follow the `Location` header from a successful create request to check the latest status and resource version.

