TextPreflight API v1 · Beta

Developer documentation

Preflight SMS before it becomes an invoice.

TextPreflight is a provider-neutral JSON API for GSM-7/UCS-2 detection, exact segment counting, safe typography optimization, template simulation and campaign forecasting.

Private betaThis local build has no production hostname or paid checkout yet. Replace the example origin after Cloudflare deployment.

Quick start

curl -X POST https://textpreflight.kadircoteli.workers.dev/api/v1/sms/analyze \
  -H "Content-Type: application/json" \
  -d '{"text":"Your order is ready.","recipients":1000,"unitPrice":0.0075}'

Every successful API response wraps its result in data and includes a versioned meta object. Errors use a stable error.code.

Authentication

The private beta endpoint is protected by edge rate limiting but does not yet require an API key. Before paid launch, direct customers will use an Authorization credential and RapidAPI requests will be validated at the gateway boundary.

Do not treat the current public rate limit as paid-plan authorization. Authentication and entitlement storage belong to the launch phase.
POST

/api/v1/sms/analyze

Analyze encoding, units, segment boundaries, non-GSM characters, Unicode risks and optional estimated cost.

Request

textstring · required

Message text, up to 10,000 UTF-16 code units.

profilestring

standard or twilio-tollfree-us-ca.

recipientsinteger

Recipient count, 1 to 100,000,000. Defaults to 1.

unitPricenumber

Your provider's price per billable segment.

Example response

{
  "data": {
    "encoding": "GSM-7",
    "length": { "codePoints": 20, "utf16CodeUnits": 20, "encodingUnits": 20 },
    "segments": { "count": 1, "remainingInFinalPart": 140, "billable": 1000 },
    "characters": { "nonGsmCount": 0, "extendedCount": 0 },
    "unicode": { "riskLevel": "none", "findingCount": 0 },
    "estimatedCost": { "currency": "USD", "total": 7.5 }
  }
}
POST

/api/v1/sms/optimize

Apply a conservative, inspectable set of typography replacements. It does not paraphrase or rewrite message meaning.

textstring · required

Message to inspect and optimize.

removeInvisibleboolean

Explicitly remove selected controls and invisible characters. Defaults to false; ZWJ and ZWNJ are never removed.

{
  "text": "Your delivery is “ready” — collect now.",
  "recipients": 10000,
  "unitPrice": 0.0075,
  "removeInvisible": false
}
POST

/api/v1/template/simulate

Render every supplied {{variable}} combination, capped at 250 cases, and report the min/average/max segment outcomes.

{
  "template": "Hi {{name}}, your code is {{code}}.",
  "variables": {
    "name": ["Ada", "Aleksandra", "Zoë"],
    "code": [1234, 987654]
  },
  "recipients": 5000,
  "unitPrice": 0.0075
}
POST

/api/v1/campaign/estimate

Aggregate up to 500 message variants and their recipient counts into a billable-segment forecast.

{
  "messages": [
    { "text": "Delivery today.", "recipients": 8500 },
    { "text": "Delivery tomorrow.", "recipients": 1500 }
  ],
  "unitPrice": 0.0075,
  "currency": "USD"
}

Errors & limits

400invalid_jsonMalformed JSON body
405method_not_allowedUnsupported HTTP method
413payload_too_largeBody exceeds 64 KB
415unsupported_media_typeExpected application/json
422validation_errorInvalid or missing input
429rate_limitedPublic beta limit exceeded

The current public beta limit is 60 requests per minute per client and endpoint. A Retry-After: 60 header accompanies rate-limit responses.

Provider profiles

standardGSM 160 / 153UCS-2 70 / 67
twilio-tollfree-us-caGSM 160 / 152UCS-2 70 / 66

Actual billing may vary by provider, route, country and message technology. Supply the relevant profile and validate your provider's current rules.

Data handling

Message bodies are processed in Worker memory and are not written to application storage or logs. Operational errors record the endpoint, method, status and request ID—not request payloads. See the privacy notice.