How to Send iMessages from Node.js (TypeScript SDK Guide)

The Sendblue TypeScript SDK lets you send and receive iMessages from any Node.js application. This guide covers everything from installation to a complete two-way messaging setup with Express webhooks.

Install the SDK

Install the Sendblue package from npm:

npm install sendblue
# or
yarn add sendblue

The package includes TypeScript types out of the box — no additional @types package needed.

Send Your First iMessage

import Sendblue from 'sendblue';

const sendblue = new Sendblue(
  process.env.SENDBLUE_API_KEY!,
  process.env.SENDBLUE_API_SECRET!
);

async function main() {
  const response = await sendblue.sendMessage({
    number: '+15551234567',
    content: 'Hello from Node.js!',
    sendStyle: 'celebration',
  });

  console.log('Message sent:', response);
}

main();

Messages are sent as iMessage when the recipient has an iPhone. Sendblue automatically falls back to RCS → SMS for Android users.

Receive Messages with Express

Set up an Express server to handle incoming messages via webhooks:

import express from 'express';
import Sendblue from 'sendblue';

const app = express();
app.use(express.json());

const sendblue = new Sendblue(
  process.env.SENDBLUE_API_KEY!,
  process.env.SENDBLUE_API_SECRET!
);

app.post('/webhook/receive', async (req, res) => {
  const { from_number, content, media_url } = req.body;

  console.log(`Message from ${from_number}: ${content}`);

  // Auto-reply
  await sendblue.sendMessage({
    number: from_number,
    content: 'Thanks! We received your message.',
  });

  res.status(200).json({ status: 'ok' });
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Set your webhook URL in the Sendblue dashboard. Use ngrok http 3000 for local development.

Send Media and Contact Cards

// Send an image
await sendblue.sendMessage({
  number: '+15551234567',
  content: 'Check this out!',
  mediaUrl: 'https://example.com/photo.jpg',
});

// Send a contact card (vCard)
await sendblue.sendMessage({
  number: '+15551234567',
  mediaUrl: 'https://example.com/contact.vcf',
});

Sendblue supports all file types. Send .vcf files to deliver contact cards, .caf files for inline voice notes, and any image or video format for rich media.

iMessage Detection

const result = await sendblue.evaluateService('+15551234567');
console.log(result.is_imessage); // true or false

Use this to build smart routing: send blue bubble iMessages to iPhone users and fall back to SMS for everyone else. This is especially useful for sales outreach where blue bubbles get 3x higher response rates.

Next Steps

You're set up with iMessage in Node.js. Continue with:

Build an AI agent — Connect any LLM to iMessage for intelligent conversations
Webhook integration guide — Handle all webhook types including delivery receipts and typing indicators
AI agent use cases — See how businesses use iMessage AI agents
API documentation — Full reference for all endpoints

Node.js

TypeScript

iMessage API

Tutorial

Ready to send your first iMessage?

Get API access in minutes. Free sandbox, no credit card required.

Get API Access