Getting started

Quickstart

Send your first iMessage in 5 minutes. All steps use the free sandbox — no credit card, no production approval needed.

1. Sign up + activate your sandbox

Create a free sandbox account. Right after signup, you'll see an activation code (something like SBX-A4F2K9) and a phone number. Text the code from any iPhone — that binds your phone to your account.

→ Create your sandbox account

Why text-to-activate?

Sandbox lets you test the API for free without spamming anyone. After activation, you can only send messages to your own activated phone (and up to 5 verified contacts). Production accounts get a dedicated line with no recipient restrictions.

2. Grab your API key

Activation auto-issues an sk_sandbox_… API key. Find it under Sandbox → API key. Stash it in an environment variable:

export BLUEREPLIES_KEY='sk_sandbox_…your_key…'

Keep your key secret

API keys grant full access to your account. Never commit them to source control, never expose them in client-side code, and rotate immediately if leaked.

3. Install the SDK (optional)

We provide an official Node.js SDK. For any other language, the REST API works directly with the standard HTTP client of your choice.

npm install blueapi

4. Send your first message

Replace +15551234567 with your activated phone number (or use the dropdown in the Playground).

curl -X POST 'https://api.bluereplies.com/v1/messages' \
  -H "x-api-key: $BLUEREPLIES_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+15551234567",
    "body": "Hello from BlueReplies!"
  }'

You'll see the iMessage on your phone within a couple seconds. The API response comes back instantly with status: "queued" — it transitions to sent → delivered → read as Apple confirms each stage.

5. (Optional) Receive replies via webhook

Don't poll. Set up a webhook to get pushed events for every inbound message, status update, reaction, typing indicator, and more. We sign every delivery with HMAC-SHA256 so you can verify it came from us.

curl -X POST 'https://api.bluereplies.com/v1/webhooks' \
  -H "x-api-key: $BLUEREPLIES_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://your-app.com/webhooks/bluereplies",
    "events": ["message.inbound", "message.delivered", "message.read"]
  }'

Then in your webhook handler, verify the signature before acting on the payload:

webhook-handler.js

import crypto from 'node:crypto';

function verify(req) {
  const sig = req.headers['x-bluereplies-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
}

See the full Webhooks guide for the complete event catalogue, retry behavior, and language-specific signature verifiers.

Next steps

Messages API reference — every field, every option (effects, reactions, edit, unsend, scheduled sends)
Webhooks — every event type, retry policy, signature verification in 5 languages
Errors — what each status code means, when to retry
Rate limits + warmup — Apple's hidden caps and our warmup curve
Recipes — full code for OTP, appointment reminders, drip campaigns