Skip to main content
The BlueBubbles SDK is a TypeScript library that gives you a clean, fully-typed interface to the BlueBubbles Server REST API. Instead of constructing raw HTTP requests and parsing untyped JSON, you work with resource-grouped service objects — client.chats, client.messages, client.handles, and more — each backed by generated TypeScript interfaces that match the API’s request and response shapes exactly.

​
What it solves

The BlueBubbles Server exposes a powerful REST API for controlling iMessage on macOS, but calling it directly means hand-rolling authentication, managing query parameters, typing responses yourself, and remembering endpoint paths. The SDK handles all of that for you. Authentication is injected automatically on every request. Responses are typed. The API surface is organized around logical resources rather than raw endpoint paths.

​
Key features

  • Fully typed interfaces — every request parameter and response field is typed from the OpenAPI spec, giving you autocomplete and compile-time safety throughout your code
  • Resource-grouped API — client.chats, client.messages, client.handles, and client.attachments organize the API into logical groups that match how you think about messaging
  • Native fetch — the SDK uses the platform’s built-in fetch with no heavy HTTP client dependency
  • Universal runtime support — runs in Node.js (18+), modern browsers, and React Native without polyfills or bundler configuration
  • Tree-shakable — import only the services you use; unused services are eliminated at build time
  • Automatic authentication — pass your server password once at construction and it is injected as a query parameter on every outgoing request

​
Prerequisites

Before using the SDK you need:
  • A macOS machine running BlueBubbles Server
  • The server’s network address (local IP, domain, or ngrok URL) and password
  • Node.js 18 or later (for server-side use), or a modern browser/React Native environment
  • A package manager: npm, yarn, or pnpm
The SDK communicates exclusively with your self-hosted BlueBubbles Server. It does not connect to any BlueBubbles cloud service or relay. Your messages and credentials never leave your own infrastructure.

​
Where to go next

Quickstart

Install the SDK and make your first API call in under five minutes.

Authentication

Understand how password-based auth works and how to configure credentials.

Sending messages

Step-by-step guide to sending text messages and attachments.

API reference

Complete method reference for every service in the SDK.