RebelText API

Send SMS and MMS, track delivery, and get status updates pushed to your server.

Base URL

https://rebeltext.docoitest.com

Every request is authenticated with your API key, and every request and response body is JSON: send Content-Type: application/json whenever a request has a body.

AI agents and LLM tools can read this guide as Markdown, which /docs also returns to any request that sends Accept: text/markdown.

Quick start

1. Send a message.

   curl -X POST https://rebeltext.docoitest.com/v1/messages \
     -H "Authorization: Bearer $REBELTEXT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"to_number": "5125550199", "message": "Your order has shipped."}'
   

   The response includes a reference_id, such as msg_01HQ3F5X8K2M9N4P6R7S8T9V0W. That's the message's ID.

2. Check whether it was delivered.

   curl https://rebeltext.docoitest.com/v1/messages/msg_01HQ3F5X8K2M9N4P6R7S8T9V0W \
     -H "Authorization: Bearer $REBELTEXT_API_KEY"
   

3. Stop polling. Register an endpoint and we'll tell your server the moment a message's status changes.

Authentication

Send your API key as a bearer token on every request:

Authorization: Bearer rt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

There are two kinds of key:

Treat your key like a password: keep it out of client-side code and out of source control.

You need a subscription to send

A new key works straight away for reading, but sending needs an active plan. Without one, every endpoint that sends a message, registers a brand or campaign, or buys a number answers 402:

{
  "status": false,
  "message": "This account has no active subscription. Choose a plan to start sending.",
  "code": "subscription_required"
}

You can still read: GET /v1/account, GET /v1/plans, GET /v1/messages and your invoices all keep working, so you can see where you stand. Pick a plan in the console and your key can send on its very next request. There's no waiting period and nothing to restart.

Don't confuse this with insufficient_balance. subscription_required means there's no plan; insufficient_balance means there is a plan, but your balance has run out.

Authentication errors

Responses and errors

Every response has the same envelope, so one piece of code can handle them all.

Success

{
  "status": true,
  "message": "Success",
  "data": { }
}

Error

{
  "status": false,
  "message": "The to_number is not a valid North American number.",
  "code": "invalid_request",
  "errors": {
    "to_number": ["The to_number is not a valid North American number."]
  }
}

Unknown fields in a request body are rejected rather than silently ignored. A typo such as toNumber gets a 422 that names the field.

Request IDs

Every response carries an X-Request-Id header. You can send your own X-Request-Id and we'll use it instead. Quote it when you contact support and we can find the exact request. Recent requests are also listed in the console under API keys › Request log.

Rate limits

Your plan sets how many messages a second you can send. Go over it and you get 429 rate_limited with a Retry-After header: the number of seconds to wait. A rate-limited request isn't charged. Wait at least that long, then retry.

Pagination

The message lists return one page at a time, newest first. Every page says where it sits in the list:

All four are always present. When has_more is true the next page is never empty, so keep requesting until it's false.

A message list covers the last 30 days unless you set since and until (RFC 3339 times).

Media (MMS)

Add media to a send and the message becomes an MMS. message is then optional.

• A message carries one attachment.
• It must be an image or audio file: JPEG, PNG, GIF, WebP, BMP, TIFF, HEIC/HEIF, AVIF, MP3, M4A, AAC, WAV, Ogg, Opus, AMR, FLAC, AIFF or MIDI. SVG isn't accepted.
• An MMS costs a flat price per message, however long its text. See Pricing and segments.
• In the response, sms_type is "mms" and media_url is the attachment's URL.

Attach a file by URL

Send a public http or https URL that the carrier can fetch. A URL ending in one of the file extensions above, such as .png or .mp3, is accepted as is. Any other URL is fetched briefly when you send, and must turn out to be an image or audio file. URLs on private or local network addresses are refused.

curl -X POST https://rebeltext.docoitest.com/v1/messages \
  -H "Authorization: Bearer $REBELTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "5125550199",
    "message": "Here is your ticket.",
    "media": "https://cdn.example.com/tickets/4471.png"
  }'

Upload a file

Send the request as multipart/form-data, with the file in a part named media, up to 5 MiB. We work out the file type from its contents, not its name, and host the file for the carrier to fetch.

curl -X POST https://rebeltext.docoitest.com/v1/messages \
  -H "Authorization: Bearer $REBELTEXT_API_KEY" \
  -F to_number=5125550199 \
  -F message="Here is your ticket." \
  -F media=@ticket.png

When media is refused

A media value that isn't a supported file, can't be fetched, is over 5 MiB, or is sent as both a URL and a file gets 422 invalid_request, with a media entry in errors.

Phone numbers

• A number without a leading + gets country_code added (default +1), so 5125550199 and 15125550199 are the same US recipient.
• A number starting with + is used as is, and country_code is ignored.
• US and Canadian (+1) numbers must be valid 10-digit North American numbers.

Pricing and segments

Your account holds a balance in US dollars. You add to it by topping up, and your plan may add to it each billing period. Every message is paid for from that balance:

cost in a response is what that message costs, and currency is always "usd". A 200-character GSM message, for example, is 2 segments: at $0.0095 a segment it has "segments": 2 and "cost": "0.019", and your balance goes down by that much.

Amounts are strings

cost, balance and every other amount are decimal strings of US dollars, with up to 4 decimal places and never fewer than 2: "0.01", "0.019", "0.0095", "48.21". They're strings so they never pass through floating point. If you do arithmetic on them, parse them with a decimal type, not a float.

How many segments a message takes

{ } [ ] ~ ^ \ | and € each count as two GSM characters.

Safe retries

A network error can leave you unsure whether a send went through, and simply retrying can send the message twice. Send an Idempotency-Key header to make retries safe.

If you retry with the same key, from the same API key, within 24 hours:

• no second message is sent, and you're not charged again
• the response is 202 with the original reference_id and "duplicate": true
• created_at and updated_at are null; read the message for its current state

{
  "status": true,
  "message": "Message accepted",
  "data": {
    "reference_id": "msg_01HQ3F5X8K2M9N4P6R7S8T9V0W",
    "status": "accepted",
    "created_at": null,
    "updated_at": null,
    "balance": "48.21",
    "duplicate": true
  }
}

(Shortened: the full message object is returned.)

Pick a key that identifies the send itself, such as your order ID plus the event (order-4471-shipped), not a random value generated for each attempt.

How webhooks work

A webhook sends an HTTP POST to your server when something happens to your messages, so you don't have to poll.

1. Register an endpoint with your server's URL, in the console under Webhooks or with the API, and save the secret it returns.
2. Receive events on that URL and answer each with a 2xx.
3. Verify each event's signature before you trust it.

There are two event types. An endpoint subscribes to one or both, and to sms.status alone if you don't say.

Receiving events

Each event arrives as a POST with a JSON body and these headers:

The body is a message object, the same one GET /v1/messages/{reference_id} returns, so one parser handles both.

How to respond

• Return any 2xx as soon as the event arrives. Anything else, or no answer within 10 seconds, counts as a failure and is retried.
• Redirects aren't followed, so a 3xx is a failure too. Register the final URL.
• Return 410 Gone to refuse an event for good. We stop retrying it straight away.
• Do slow work, such as database updates or sending emails, after you respond, for example in a background job.
• Events can arrive more than once and out of order. Skip any X-RebelText-Delivery-Id you've already processed, and order a message's events by updated_at, not by when they arrived.

sms.status body

{
  "reference_id": "msg_01HQ3F5X8K2M9N4P6R7S8T9V0W",
  "sender": "+15125550100",
  "receiver": "+15125550199",
  "sms_type": "sms",
  "message": "Your order #4471 has shipped.",
  "media_url": null,
  "status": "delivered",
  "remarks": "The message was delivered to the recipient.",
  "error_code": null,
  "carrier_error_code": null,
  "carrier_error_message": null,
  "segments": 1,
  "cost": "0.0095",
  "currency": "usd",
  "attempts": 1,
  "metadata": { "order_id": "4471" },
  "api_key_id": "key_01HQ2Z8Y7X6W5V4T3S2R1Q0P9N",
  "scheduled_at": null,
  "sent_at": "2026-09-17T10:04:11.881000Z",
  "received_at": null,
  "delivered_at": "2026-09-17T10:04:14.019000Z",
  "created_at": "2026-09-17T10:04:11.204000Z",
  "updated_at": "2026-09-17T10:04:14.019000Z"
}

sms.inbound body

For a received message, sender is the person who texted you, receiver is your number, and reference_id starts with inb_.

{
  "reference_id": "inb_01HQ5B7C8D9E0F1G2H3J4K5M6N",
  "sender": "+15125550199",
  "receiver": "+15125550100",
  "sms_type": "sms",
  "message": "Thanks! When will it arrive?",
  "media_url": null,
  "status": "received",
  "remarks": "The message was received from the sender.",
  "error_code": null,
  "carrier_error_code": null,
  "carrier_error_message": null,
  "segments": 1,
  "cost": "0.00",
  "currency": "usd",
  "attempts": 0,
  "metadata": {},
  "api_key_id": null,
  "scheduled_at": null,
  "sent_at": null,
  "received_at": "2026-09-17T10:06:40.512000Z",
  "delivered_at": null,
  "created_at": "2026-09-17T10:06:40.730000Z",
  "updated_at": "2026-09-17T10:06:40.730000Z"
}

Verifying signatures

Always check that an event came from RebelText before you act on it. X-RebelText-Signature is built like this:

base64( hex( HMAC-SHA256(raw_request_body, webhook_secret) ) )

To check it:

1. Compute the HMAC-SHA256 of the raw request body, using your endpoint's full secret (including whsec_) as the key.
2. Write the result as a lowercase hex string.
3. Base64-encode that hex string.
4. Compare the result with X-RebelText-Signature using a constant-time comparison.
5. Reject the event if X-RebelText-Timestamp is more than 5 minutes from your current time, in either direction.

Use the raw body exactly as it arrived. If you parse the JSON and encode it again, the bytes change and the signature won't match.

Node.js (Express)

const crypto = require('crypto');
const express = require('express');

const app = express();
const SECRET = process.env.REBELTEXT_WEBHOOK_SECRET;

app.post('/hooks/rebeltext', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-RebelText-Signature') || '';
  const timestamp = Number(req.get('X-RebelText-Timestamp'));

  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) {
    return res.sendStatus(400);
  }

  const hex = crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const expected = Buffer.from(Buffer.from(hex).toString('base64'));
  const received = Buffer.from(signature);

  if (expected.length !== received.length || !crypto.timingSafeEqual(expected, received)) {
    return res.sendStatus(403);
  }

  const event = JSON.parse(req.body);
  res.sendStatus(200);

  // Process `event` after responding.
});

PHP

<?php
$rawBody   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_REBELTEXT_SIGNATURE'] ?? '';
$timestamp = (int) ($_SERVER['HTTP_X_REBELTEXT_TIMESTAMP'] ?? 0);
$secret    = getenv('REBELTEXT_WEBHOOK_SECRET');

if (abs(time() - $timestamp) > 300) {
    http_response_code(400);
    exit;
}

$expected = base64_encode(hash_hmac('sha256', $rawBody, $secret));

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit;
}

$event = json_decode($rawBody, true);
http_response_code(200);

Python

import base64, hashlib, hmac, time

def verify(secret: str, signature: str, timestamp: str, body: bytes) -> bool:
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False
    except (TypeError, ValueError):
        return False

    digest = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    expected = base64.b64encode(digest.encode()).decode()
    return hmac.compare_digest(expected, signature)

Retries and pausing

Retries. When a delivery fails, we try again on this schedule. Each delay varies by up to ±20%.

If every retry fails, the delivery is marked dead. Once your server is working again you can replay it.

Pausing. After 10 failed deliveries in a row, we pause sending to that endpoint. The first pause lasts 30 seconds; if failures continue, later pauses last 1, 2, 5 and then 15 minutes. When a pause ends we send one delivery first, and the rest once it succeeds. While paused, disabled_until in List endpoints shows when sending resumes. A successful delivery resets both the failure count and the pause length.

Pacing. We send at most 8 deliveries to one endpoint at a time, so a backlog arrives as a steady stream rather than all at once.

Use with AI agents (MCP)

RebelText speaks the Model Context Protocol, so an AI agent such as Claude, ChatGPT, Claude Code or Cursor can send messages and look up their status for you. It runs on an ordinary API key and behaves exactly like the REST API: the same validation, the same subscription requirement, the same charges, and every call appears in your API log.

Endpoint: https://rebeltext.docoitest.com/mcp (Streamable HTTP).

Sign in from the app

Most AI apps, such as Claude and ChatGPT, need only the endpoint URL. Add it as a connector or custom MCP server and the app sends you to the RebelText console to sign in and approve it. The page names the app and the address it will return you to. Only allow it if that address belongs to the app you are connecting.

Approving issues a live API key named after the app, such as "Claude (connected app)". It counts toward your plan's keys and appears on the API keys page with the others. To disconnect the app, revoke that key. Connecting needs a plan and a free key in your allowance.

Use an API key

Apps that take a header instead can use a key you issue yourself. Claude Code:

claude mcp add --transport http rebeltext https://rebeltext.docoitest.com/mcp \
  --header "Authorization: Bearer $REBELTEXT_API_KEY"

Other clients take the same URL and Authorization header in their MCP server settings.

Tools

send_message is marked as destructive, so well-behaved clients ask you before each send. An agent with your key can still spend your balance, so give it a key you can revoke, and pass idempotency_key so a retried send never goes out twice (Safe retries).

API reference

Every endpoint, grouped by what it acts on. Each one lists its parameters, with a request and a response example beside it. Paths are relative to the base URL, https://rebeltext.docoitest.com, and every request needs your API key.

Messages

Send messages and find out what happened to them. Both endpoints return the message object.

Received messages

Messages people send to your numbers, the console's Received messages. Each one is stored, charged and sent to any endpoint subscribed to sms.inbound (see Receiving events). These endpoints read them back.

• Whose reply it is. A reply to one of your own numbers is yours. A reply to a shared-pool number goes to the account that most recently messaged that person from it in the last 30 days.
• What it costs. A received SMS is charged per segment at the price for received messages, which is free unless your account says otherwise; a received MMS is charged per message. The charge is taken when the message arrives, even if it takes your balance below zero.
• Attachments. A received MMS has its first attachment in media_url and all of them in media_urls. We copy them to our own storage within seconds, because the carrier's copies expire after 30 days.
• Opt-outs. A reply that's just STOP, STOPALL, UNSUBSCRIBE, CANCEL, END or QUIT (in any case) adds the sender to your suppressions, and START removes them again. The reply itself is still stored and delivered. HELP isn't answered for you.

Suppressions

Numbers you won't message. A send to a suppressed number is refused with 422 recipient_suppressed and isn't charged. A recipient who replies STOP is added automatically (see Received messages), and you can add your own, such as a do-not-call list.

Numbers

Account

Webhooks

Manage your endpoints: the URLs we send events to. You can do the same in the console under Webhooks. How events are delivered, verified and retried is covered in How webhooks work.

Delivery log

Every event we send to an endpoint is a delivery. The console shows them under Webhooks › Delivery log. Use these requests to see what was sent, what your server answered, and to send a delivery again.

Objects and errors

The message object

Sending a message, reading one, and every webhook event all return this object. Every field is always present, except media_urls: one that doesn't apply is null, or {} for metadata. All timestamps are UTC, such as 2026-09-17T10:04:14.019000Z.

Message statuses

A sent message usually moves through these statuses:

accepted → queued → sending → sent → delivered
                                   ↘ undelivered

• A message never moves back to an earlier status.
• sent usually becomes delivered or undelivered within seconds, but some carriers never confirm delivery, so sent may be the last status you see.
• Webhooks are sent for scheduled, sending, sent, delivered, undelivered and failed. Not for accepted: you already have that from the send response.

Failure codes

When status is failed, error_code says why. The codes below come from RebelText. Any other value comes from the carrier, and then carrier_error_code and carrier_error_message carry the carrier's own code and wording, so you can tell a carrier's spam block from a problem on the route.

Error codes