Skip to content
CaptiFi Connect
Create account

Developer docs

Test keys: build against the SMS API for free

A test key behaves like a live one from your code's point of view, except that nothing leaves us and nothing is charged. Use it to build and test the whole flow, webhooks included.

What a test key does

Create one in the dashboard under Developers, API keys, with the mode set to Test. It starts cc_test_. Requests made with it go through the same checks as live ones: the body is validated, numbers are checked and de-duplicated, opted-out numbers are refused, and you get the same response shapes back. The difference is that every message has test set to true, uses no credit, and never reaches a phone.

POST /messages with a test key
{
  "data": {
    "batch_id": "bat_01J9Z8X7W6V5T4S3R2Q1P0N9M7",
    "messages": [{ "id": "msg_01J9Z8X7W6V5T4S3R2Q1P0N9M8", "status": "queued", "credits": 0, "test": true }],
    "rejected": []
  },
  "meta": { "credits": 0, "replayed": false, "test": true }
}

Test keys work while your account is still waiting to be checked, so you don't have to wait for approval to start building.

The simulated timeline

About a second after you send, each test text moves to sent, and about two seconds after that to delivered. Each step records a timeline entry and fires message.sent and then message.delivered to your webhooks, signed exactly as live events are, so your signature check gets a proper workout.

Test texts show in the dashboard's message history with a test label, which keeps them easy to tell apart from real ones.

Limits

Test texts are free, so they're capped: up to 50 numbers in one request and 300 texts an hour per account. Go over the hourly figure and you get a 429 with a Retry-After header, the same as the live rate limit.

Test keyLive key
Key prefixcc_test_cc_live_
Texts actually sentNoYes
Credits usedNoneOne per SMS part
Works before your account is approvedYesNo (403 account_pending)
Number checks, opt-outs and rejectionsSame as liveYes
WebhooksFired and signed, like liveYes
Recipients per requestUp to 50Up to 1,000 typed numbers, plus contacts and lists
Numbers per hourUp to 300Set by your rate limit and balance
CampaignsDrafts only, cannot be sentYes

What test mode skips

  • Nothing reaches a phone, so you won't see message.received or opt_out.created from a test send. Use the webhook test button (or POST /webhooks/{id}/test) to check your handler for those.
  • Every test text ends up delivered. There's no way to simulate a failed or undelivered text yet, so write those paths against the payloads in the webhooks guide.
  • Campaigns can't be sent or cancelled with a test key; that returns 403 test_mode_not_supported. Test the text itself with POST /messages instead.
  • A test key can't cancel a live scheduled text.

Switching to live

Once your account is approved and has credit, create a live key and swap it in. Test and live Idempotency-Key values are kept apart, so a key you used in testing can't make a live request return an old test answer. The quickstart walks through the whole thing.