Verified Numbers

What is restricted mode?

When your account has no approved Sender ID, CastBrick uses its own default sender (CastBrick) to deliver your messages. To prevent abuse of this shared sender, restricted mode applies:

While in restricted mode, you can only send messages to phone numbers you have explicitly verified via OTP.

This protects recipients from unsolicited messages sent through the CastBrick shared sender by an account that hasn't registered their own brand.

When does it apply?

Restricted mode is active when both of the following are true:

Your account has no approved Sender ID
The message is being sent using the CastBrick fallback sender (i.e. no senderId provided, or fallback: true)

Sandbox API keys (cb_test_...) are exempt from this restriction. Sandbox sends never reach real carriers, so the verified-number check is skipped entirely.

When does it lift?

The restriction lifts automatically the moment any of your Sender IDs is approved. Once you have an approved sender, you can reach any number without first verifying it.

To request a Sender ID, go to SMS → Senders in the dashboard and submit a request.

How to verify a number

From the dashboard

Open Settings → Verified Numbers
Click Add number
Enter the phone number (E.164 format, e.g. +244912345678)
Click Send code — a 6-digit OTP is delivered to that number via SMS
Enter the code and click Verify

The number now appears in your verified list and can receive messages sent through the CastBrick fallback sender.

The OTP expires after 10 minutes. If it expires, start the flow again — a new code will be sent.

Via API

Step 1 — Request an OTP

POST /verified-numbers/otp
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "phoneNumber": "+244912345678"
}

Returns 200 OK on success. A 6-digit code is sent to the number.

Step 2 — Confirm the OTP

POST /verified-numbers/verify
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "phoneNumber": "+244912345678",
  "code": "483921"
}

Returns 200 OK on success. The number is added to your verified list.

List verified numbers

GET /verified-numbers
Authorization: Bearer <session_token>

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "phoneNumber": "+244912345678",
    "verifiedAt": "2026-06-09T14:30:00Z"
  }
]

Remove a verified number

DELETE /verified-numbers/{id}
Authorization: Bearer <session_token>

Returns 204 No Content.

These endpoints require a session token (JWT cookie), not an API key. They are dashboard-only operations — your backend integration does not need to call them.

Error when sending to an unverified number

If you attempt to send to a recipient that is not in your verified list while in restricted mode, the API returns:

HTTP 400 Bad Request

{
  "type": "ValidationError",
  "code": "SMS.UnverifiedRecipients",
  "description": "You have no approved sender. 2 recipient(s) must be verified first. Go to Settings → Verified Numbers to add them."
}

The message is not sent to any recipient — the entire request is rejected.

Frequently asked questions

Can I have unlimited verified numbers? Yes, there is no limit.

Does verifying a number cost credits? Yes — sending the OTP consumes one system SMS credit from your balance, the same as any other outbound message.

What happens to my verified list when I get an approved sender? It stays. If you later lose your approved sender (e.g. it gets revoked), your verified list is still there and the restriction resumes using it.

Do I need to re-verify numbers periodically? No. Verified numbers stay verified indefinitely unless you remove them.

Verified Numbers

On this page