Apple Messages. A local API.
Read conversations, send messages, download attachments, and follow live events from your Mac.
Choose your next step
Section titled “Choose your next step”Set up your MacInstall the relay, grant macOS permissions, and make your first request.
Build an integrationSet up authentication, then follow guides for messages, media, and events.
Look up an endpointBrowse request fields, response shapes, and generated model definitions.
Resolve a problemUnderstand permissions, database access, and uncertain native results.
How the relay works
Section titled “How the relay works”The relay runs on macOS 14 or newer. Reads use your local Messages database. Sends use Messages.app. The relay does not use private frameworks or process injection.
The HTTP server listens on http://127.0.0.1:8080 by default. Every request requires your bearer token.
The relay process needs Full Disk Access to read Messages.
Read the configuration guide before changing its listening address or allowed recipients.
Common tasks
Section titled “Common tasks”Send a messageChoose a destination, send text, and track the result without sending twice.
Follow live changesConnect to the event stream and resume after a disconnect.
Upload or download a fileStore files for sending or retrieve a Messages attachment.
Read sender capabilitiesFind out which operations the Mac can perform before calling them.
Source code and releases are available on GitHub.