API
Messages API
Read stable message pages and send idempotent text or one-file replies to accessible conversations.
List messages
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.
{
"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
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:
{
"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.
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:
{
"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.
{
"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
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
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.