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
}| Field | Type | Required | Description |
|---|---|---|---|
recipients | string[] | Yes* | Phone numbers in E.164 format |
content | string | Yes | Message text (up to 160 GSM-7 chars / 70 UCS-2) |
senderId | string | No | Registered Sender ID. Omit to use the CastBrick default |
scheduledAt | ISO 8601 | No | Future datetime to send. Omit to send immediately |
contactListId | UUID | No | Send to all contacts in this list |
fallback | bool | No | Fall 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"
}| Field | Description |
|---|---|
messageId | Unique ID of the message batch |
status | queued or scheduled |
recipientCount | Number of recipients the message was dispatched to |
timestamp | Server 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
| Parameter | Type | Default | Description |
|---|---|---|---|
pageNumber | int | 1 | Page number |
pageSize | int | 20 | Results per page (max 100) |
status | string | — | Filter by status: pending, sent, delivered, failed, scheduled |
phone | string | — | Filter by recipient phone number (partial match) |
from | ISO 8601 | — | Filter messages sent after this datetime |
to | ISO 8601 | — | Filter 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
| Status | Meaning |
|---|---|
pending | Accepted, waiting to enter the queue |
queued | In the dispatch queue |
sent | Dispatched to the carrier |
delivered | Carrier confirmed delivery |
failed | Delivery failed — check errorMessage |
scheduled | Will be sent at scheduledAt |
Error responses
| Status | Code | Meaning |
|---|---|---|
400 | SMS.NoRecipients | No valid recipients after deduplication |
401 | — | Invalid or revoked API key |
402 | SMS.InsufficientCredits | Not enough credits — top up your balance |
422 | SMS.ValidationError | Missing or invalid field |
429 | — | Rate limit exceeded — see Retry-After header |