CastBricks Docs

SMS API

Endpoints for sending SMS, checking status, and managing scheduled messages

SMS API

Base URL: https://api.castbrick.co

Authenticate with Authorization: Bearer <your_api_key>.


Send SMS

POST /sms/send

Sends an SMS to one or more recipients immediately, or schedules it for later.

Request body

{
  "recipients": ["+244923000000", "+244912000000"],
  "content": "Your verification code is 123456",
  "senderId": "MyApp",
  "scheduledAt": null,
  "contactListId": null,
  "fallback": true
}
FieldTypeRequiredDescription
recipientsstring[]Yes*Phone numbers in E.164 format
contentstringYesMessage text (up to 160 GSM-7 chars / 70 UCS-2)
senderIdstringNoRegistered Sender ID. Omit to use the CastBrick default
scheduledAtISO 8601NoFuture datetime to send. Omit to send immediately
contactListIdUUIDNoSend to all contacts in this list
fallbackboolNoFall back to default sender if senderId is unavailable (default: true)

* Either recipients or contactListId must be provided.

Response 200

{
  "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "queued",
  "recipientCount": 2,
  "timestamp": "2026-05-07T10:23:00Z"
}
FieldDescription
messageIdUnique ID of the message batch
statusqueued or scheduled
recipientCountNumber of recipients the message was dispatched to
timestampServer timestamp of the request

Code samples

curl -X POST https://api.castbrick.co/sms/send \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+244923000000"],
    "content": "Your verification code is 123456",
    "senderId": "MyApp"
  }'
import { CastBrick } from 'castbrick-js';

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

const result = await cb.sms.send({
  recipients: ['+244923000000'],
  content: 'Your verification code is 123456',
  senderId: 'MyApp',
});

console.log(result.messageId, result.status);
from castbrick import CastBrick
import os

cb = CastBrick(api_key=os.environ["CASTBRICK_API_KEY"])

result = cb.sms.send(
    to=["+244923000000"],
    content="Your verification code is 123456",
    sender_id="MyApp",
)

print(result.message_id, result.status)
using CastBrick.SDK;
using CastBrick.SDK.Models.Sms;

var cb = new CastBrickClient(new CastBrickOptions
{
    ApiKey = Environment.GetEnvironmentVariable("CASTBRICK_API_KEY")!
});

var result = await cb.Sms.SendAsync(new SendSmsRequest
{
    Recipients = ["+244923000000"],
    Content    = "Your verification code is 123456",
    SenderId   = "MyApp",
});

Console.WriteLine($"{result.MessageId}{result.Status}");
import 'package:castbrick/castbrick.dart';

final cb = CastBrick(apiKey: Platform.environment['CASTBRICK_API_KEY']!);

final result = await cb.sms.send(
  to: ['+244923000000'],
  content: 'Your verification code is 123456',
  senderId: 'MyApp',
);

print('${result.messageId}${result.status}');

List Messages

GET /sms

Returns a paginated list of SMS messages for the authenticated workspace.

Query parameters

ParameterTypeDefaultDescription
pageNumberint1Page number
pageSizeint20Results per page (max 100)
statusstringFilter by status: pending, sent, delivered, failed, scheduled
phonestringFilter by recipient phone number (partial match)
fromISO 8601Filter messages sent after this datetime
toISO 8601Filter messages sent before this datetime

Response 200

{
  "items": [
    {
      "id": "3fa85f64-...",
      "recipientPhone": "+244923000000",
      "message": "Your code is 123456",
      "status": "delivered",
      "senderId": "MyApp",
      "sentAt": "2026-05-07T10:23:05Z",
      "deliveredAt": "2026-05-07T10:23:08Z"
    }
  ],
  "totalCount": 120,
  "pageNumber": 1,
  "totalPages": 6,
  "hasNextPage": true,
  "hasPreviousPage": false
}

Code samples

# All messages
curl "https://api.castbrick.co/sms?pageNumber=1&pageSize=20" \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

# With filters
curl "https://api.castbrick.co/sms?status=delivered&phone=%2B244923000000" \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"
// Simple
const { items, totalCount } = await cb.sms.list();

// With filters
const { items } = await cb.sms.list({
  page: 1,
  pageSize: 20,
  status: 'delivered',
  phone: '+244923000000',
  from: '2026-01-01T00:00:00Z',
  to: '2026-06-01T00:00:00Z',
});
# Simple
page = cb.sms.list(page=1, page_size=20)

# With filters
page = cb.sms.list(
    page=1,
    page_size=20,
    status="delivered",
    phone="+244923000000",
    from_date="2026-01-01T00:00:00Z",
    to_date="2026-06-01T00:00:00Z",
)
for msg in page.items:
    print(msg.id, msg.status)
// Simple
var page = await cb.Sms.ListAsync();

// With filters
var page = await cb.Sms.ListAsync(
    status: "delivered",
    phone: "+244923000000",
    from: new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc),
    to: new DateTime(2026, 6, 1, 0, 0, 0, DateTimeKind.Utc)
);
// Simple
final page = await cb.sms.list();

// With filters
final page = await cb.sms.list(
  status: 'delivered',
  phone: '+244923000000',
  from: DateTime(2026, 1, 1),
  to: DateTime(2026, 6, 1),
);

Cancel a Scheduled SMS

DELETE /sms/{id}

Cancels a message with status scheduled. Returns 404 if the message is already sent or doesn't exist.

Code samples

curl -X DELETE \
  https://api.castbrick.co/sms/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"
await cb.sms.cancelScheduled('3fa85f64-5717-4562-b3fc-2c963f66afa6');
cb.sms.cancel_scheduled("3fa85f64-5717-4562-b3fc-2c963f66afa6")
await cb.Sms.CancelScheduledAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));
await cb.sms.cancelScheduled('3fa85f64-5717-4562-b3fc-2c963f66afa6');

Message status values

StatusMeaning
pendingAccepted, waiting to enter the queue
queuedIn the dispatch queue
sentDispatched to the carrier
deliveredCarrier confirmed delivery
failedDelivery failed — check errorMessage
scheduledWill be sent at scheduledAt

Error responses

StatusCodeMeaning
400SMS.NoRecipientsNo valid recipients after deduplication
401Invalid or revoked API key
402SMS.InsufficientCreditsNot enough credits — top up your balance
422SMS.ValidationErrorMissing or invalid field
429Rate limit exceeded — see Retry-After header