Skip to content
iMessage Relay

API basics

The relay listens on http://127.0.0.1:8080 by default. Every endpoint uses the /v1 prefix. The API reference describes parameters and schemas. These guides explain how to use the API and handle native behavior.

Authentication

Section titled “Authentication”

Every request requires the bearer token from RELAY_TOKEN:

Authorization: Bearer <token>

A missing or invalid token returns 401 invalid_authentication.

Public conversation IDs, message IDs, and Messages-owned media IDs are provider GUIDs. They are not SQLite row IDs.

Choose a guide

Section titled “Choose a guide”
ConversationsFind conversations, mark them as read, and manage typing indicators.
Messages and sendingRead messages, send text and media, update reactions, and retry safely.
Uploads and downloadsUpload raw bytes and safely download Messages attachments.
Live eventsFollow changes, reconnect, and recover when event history expires.
Service statusInspect database readiness and the sender's capabilities and permissions.
Cursors and paginationRead successive pages and understand when a cursor becomes invalid.

Handle errors

Section titled “Handle errors”

Read error responses for the shared JSON error shape and HTTP status codes. Before retrying a send, read retry behavior. For permission and database problems, use troubleshooting.

Compatibility

Section titled “Compatibility”

The Messages database schema is private and changes between macOS releases. The current mapping was verified against the local macOS 27 schema. Startup schema checks fail when required tables or columns are missing. Optional columns follow the generated schema for null values or omitted fields. Unsupported capabilities are reported without invented values.