Getting Started with the Blue Replies iMessage API in 5 Minutes

Prerequisites

Before you begin, you will need a Blue Replies account and an API key. Sign up at bluereplies.com/signup to get your API key. Your API key will be available in the dashboard immediately after registration.

Step 1: Send Your First Message with cURL

The fastest way to test the API is with a simple cURL command. Open your terminal and run:

curl -X POST https://api.bluereplies.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "body": "Hello from Blue Replies! 🎉"
  }'

You should receive a JSON response with a message ID and status of queued. The message will be delivered within seconds.

Step 2: Integrate with Node.js

For production applications, use our official Node.js SDK. Install it with npm:

npm install @bluereplies/sdk

Then send a message in just a few lines:

import Blue Replies from '@bluereplies/sdk';

const client = new Blue Replies({ apiKey: process.env.BLUEREPLIES_KEY });

const message = await client.messages.send({
  to: '+15551234567',
  body: 'Your order #1234 has shipped! Track it here: https://track.example.com/1234',
});

console.log('Sent:', message.id, message.status);

Step 3: Set Up Webhooks

To receive delivery confirmations and incoming replies, configure a webhook URL in your dashboard. Blue Replies will POST events to your endpoint in real time:

// Express.js webhook handler
app.post('/webhooks/bluereplies', (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'message.delivered':
      console.log('Message delivered:', event.messageId);
      break;
    case 'message.read':
      console.log('Message read at:', event.readAt);
      break;
    case 'message.received':
      console.log('Reply from', event.from, ':', event.body);
      break;
  }

  res.status(200).send('OK');
});

Step 4: Send Rich Media

iMessage supports rich media natively. Send images, videos, or contact cards by adding an attachments array:

const message = await client.messages.send({
  to: '+15551234567',
  body: 'Check out our new collection!',
  attachments: [
    { type: 'image', url: 'https://example.com/product.jpg' }
  ],
});

What is Next?

You are now sending iMessages programmatically. From here, explore the full API documentation to learn about group messaging, typing indicators, scheduled messages, and more. Our SDKs are available for Node.js, Python, Ruby, and Go.