CastBricks Docs

Node.js Quickstart

Send your first SMS with CastBrick in Node.js — under 5 minutes

Node.js Quickstart

Get your first SMS out in under 5 minutes using Node.js 18+ and the official @castbrick/js SDK.

1. Install the SDK

npm install @castbrick/js

2. Get your API key

Go to CastBrick Dashboard → API Keys and create a key. Store it in a .env file:

CASTBRICK_API_KEY=cb_live_xxxxxxxxxxxx

3. Send your first SMS

Create a file send-sms.mjs:

import 'dotenv/config';
import { CastBrick } from '@castbrick/js';

const cb = new CastBrick({ apiKey: process.env.CASTBRICK_API_KEY });

const result = await cb.sms.send({
  recipients: ['+244923000000'],
  content: 'Hello from CastBrick!',
  senderId: 'MyApp',
});

console.log(`Sent! Message ID: ${result.messageId}`);

Run it:

node send-sms.mjs

Using with Express

A common pattern is to trigger SMS from an API route — for example, sending an OTP on sign-up:

import express from 'express';
import { CastBrick, CastBrickApiError } from '@castbrick/js';

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

const cb = new CastBrick({ apiKey: process.env.CASTBRICK_API_KEY });

app.post('/auth/send-otp', async (req, res) => {
  const { phone } = req.body;
  const code = Math.floor(100000 + Math.random() * 900000);

  try {
    await cb.sms.send({
      recipients: [phone],
      content: `Your verification code is ${code}. It expires in 10 minutes.`,
      senderId: 'MyApp',
    });
    res.json({ ok: true });
  } catch (err) {
    if (err instanceof CastBrickApiError) {
      res.status(err.status).json({ error: err.message });
    } else {
      res.status(500).json({ error: 'Internal error' });
    }
  }
});

app.listen(3000);

Environment variables

VariableDescription
CASTBRICK_API_KEYYour API key (starts with cb_live_ for production)

Use cb_test_... keys in development — messages are intercepted in the Sandbox and never reach real phones.


Next steps