> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.messageblue.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.messageblue.ai/_mcp/server.

# MessageBlue TypeScript SDK

The MessageBlue TypeScript SDK is a typed client for the [MessageBlue API](/api-reference). 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`**

```bash npm
npm install messageblue
```

**`pnpm`**

```bash pnpm
pnpm add messageblue
```

**`yarn`**

```bash yarn
yarn add 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](/settings#api-and-secrets).

```typescript maxLines=20
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](/settings#api-and-secrets) — and note that regenerating takes effect immediately.

## What you can reach

The client covers the same surface as the [API reference](/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](/ai-agent-studio) for an app                                         |
| **Mappings**  | The number-to-device mappings behind your [Mac agents](/concepts#numbers-devices-and-the-mac-agent) |
| **Analytics** | Usage, senders and delivery statistics                                                              |
| **Webhooks**  | Inbound and status webhook configuration                                                            |

Every endpoint in the [API reference](/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:

```json
{ "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](/support) with the endpoint and what you expected, and both this documentation and the SDK are regenerated together.