MessageBlue TypeScript SDK | Message Blue

The MessageBlue TypeScript SDK is a typed client for the MessageBlue API. It is generated from the same OpenAPI specification that produces this documentation, so the methods, parameters and response types always match the endpoints described here — there is no second source of truth to drift from.

Install

npm install messageblue

The package ships its own type declarations and has no runtime dependencies, so it adds nothing to your dependency tree beyond itself. It works in Node and any TypeScript or JavaScript project.

Send your first message

You need an App ID and an App Secret from Settings → API & secrets.

import { MessageBlueClient } from "messageblue";
const client = new MessageBlueClient({
  // Never hard-code credentials — read them from the environment.
  appId: process.env.MESSAGEBLUE_APP_ID!,
  appSecret: process.env.MESSAGEBLUE_APP_SECRET!,
});
await client.messages.send({
  to: "+15551234567",
  text: "Hello from MessageBlue",
});

Phone numbers must be entered in E.164 format — a leading +, the country code, then the national number, with no spaces, dashes or brackets. For example +15550109988. The app rejects anything else before it reaches the gateway.

Your App Secret is a server-side credential. It is shown once when created and grants full API access to your app, so it must never appear in browser code, a mobile bundle, or a public repository. If one leaks, regenerate it from Settings → API & secrets — and note that regenerating takes effect immediately.

What you can reach

The client covers the same surface as the API reference, grouped the same way:

Area	What it is for
Messages	Send iMessages, list conversations, read message history
Agents	Read and manage the AI agent for an app
Mappings	The number-to-device mappings behind your Mac agents
Analytics	Usage, senders and delivery statistics
Webhooks	Inbound and status webhook configuration

Every endpoint in the API reference is available on the client; the reference is the exhaustive list.

Versioning

The package follows the API. While it is on a 0.x version, treat minor releases as potentially breaking and pin an exact version in production:

{ "dependencies": { "messageblue": "0.0.7" } }

Getting help

If a method is missing or a type looks wrong, that usually means the OpenAPI spec behind it needs updating rather than the SDK — contact support with the endpoint and what you expected, and both this documentation and the SDK are regenerated together.