curl -X POST https://api.tracklysms.com/api/v2/messages/preflight \
-H "X-Api-Key: trk_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "to": "+14155551234", "list_number": "+18005551000", "body": "Hello!" }'
{
"eligible": true,
"checks": {
"sender_ready": true,
"byoc_webhook_ready": true,
"not_suppressed": true,
"within_tcpa_hours": true,
"billing_ok": true,
"byoc_required_ok": true,
"list_allowed_for_key": true,
"daily_send_cap_ok": true
},
"segment_count": 1,
"encoding": "GSM-7",
"estimated_cost": 0.0045,
"currency": "usd",
"cost_basis": "estimated at current cycle position; final unit cost is positional within the pooled period",
"contact_on_list": true
}
{
"eligible": true,
"checks": { "sender_ready": true, "byoc_webhook_ready": true, "not_suppressed": true, "within_tcpa_hours": true, "billing_ok": true, "byoc_required_ok": true, "list_allowed_for_key": true, "daily_send_cap_ok": true },
"segment_count": 1,
"encoding": "GSM-7",
"estimated_cost": null,
"currency": "usd",
"cost_basis": "cost is managed by the parent account (pooled billing)",
"contact_on_list": true
}
Messages (v2)
Preflight a Send
Check sending eligibility, segment count, and estimated cost without submitting a message.
POST
/
v2
/
messages
/
preflight
curl -X POST https://api.tracklysms.com/api/v2/messages/preflight \
-H "X-Api-Key: trk_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "to": "+14155551234", "list_number": "+18005551000", "body": "Hello!" }'
{
"eligible": true,
"checks": {
"sender_ready": true,
"byoc_webhook_ready": true,
"not_suppressed": true,
"within_tcpa_hours": true,
"billing_ok": true,
"byoc_required_ok": true,
"list_allowed_for_key": true,
"daily_send_cap_ok": true
},
"segment_count": 1,
"encoding": "GSM-7",
"estimated_cost": 0.0045,
"currency": "usd",
"cost_basis": "estimated at current cycle position; final unit cost is positional within the pooled period",
"contact_on_list": true
}
{
"eligible": true,
"checks": { "sender_ready": true, "byoc_webhook_ready": true, "not_suppressed": true, "within_tcpa_hours": true, "billing_ok": true, "byoc_required_ok": true, "list_allowed_for_key": true, "daily_send_cap_ok": true },
"segment_count": 1,
"encoding": "GSM-7",
"estimated_cost": null,
"currency": "usd",
"cost_basis": "cost is managed by the parent account (pooled billing)",
"contact_on_list": true
}
Checks current sending eligibility without submitting a message or charging message usage. Billing checks may repair account state or contact the billing provider. Use it to validate a recipient, preview segment count and cost, and inspect blockers. Works with live and sandbox keys; warm-up and later execution checks can still refuse a send.
For a confirmation-required key,
confirmation_required: true makes direct-send eligible false. This is expected: resolve other blockers, then hold the SMS for human approval. Do not disable confirmation to make preflight eligible.
Body Parameters
string
required
Recipient phone number (E.164).
string
required
Sending list phone number (E.164). Must belong to your account.
string
required
Message body text.
Response Fields
boolean
Whether the message would be accepted for sending. Equals the AND of all binding checks:
sender_ready, byoc_webhook_ready, not_suppressed, billing_ok, byoc_required_ok, list_allowed_for_key, and daily_send_cap_ok, and send_policy_available, with confirmation_required false. within_tcpa_hours is advisory only and does not affect eligible.object
Per-gate results.
Show checks
Show checks
boolean
When true, the key requires human approval and
eligible is false for a direct send. Hold the SMS for approval instead.boolean
False when current confirmation policy cannot be verified; direct-send eligibility is false.
boolean
The sending list exists, is active, and belongs to you.
boolean
For BYOC lists, the delivery webhook is verified.
boolean
The recipient is not opted out or blocked.
boolean
Advisory.
true if the current time is within the recipient’s TCPA calling window, false if in quiet hours. Computed only for +1 numbers (defaults true otherwise). The raw API send path does not enforce quiet hours — enforce it yourself if you need to.boolean
The account’s billing is in good standing.
boolean
The account is allowed to send from this list (free-tier accounts must use a BYOC list).
boolean
boolean
The key passes the daily-cap check. Every live key, including an uncapped key, requires an available authoritative policy store; an outage or invalid stored daily cap reports
false. Capped live keys also need room left for today (UTC). Sandbox requests with a valid stored cap pass without reading or consuming quota. A successful preflight does not reserve quota or guarantee a later send will be admitted.integer
Number of SMS segments the body would use.
string
GSM-7 or UCS-2.number
Marginal cost of the send at the account’s current tier and cycle position.
null for a child pooled to its parent’s billing.string
Currency of
estimated_cost (e.g. usd).string
How the estimate was derived — or, for a pooled child, that cost is managed by the parent.
boolean | null
Whether the recipient is an active contact on the list.
false means the recipient is on the list but their membership is inactive; null means the recipient has no membership on that list, or the sending list could not be resolved.Examples
curl -X POST https://api.tracklysms.com/api/v2/messages/preflight \
-H "X-Api-Key: trk_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "to": "+14155551234", "list_number": "+18005551000", "body": "Hello!" }'
{
"eligible": true,
"checks": {
"sender_ready": true,
"byoc_webhook_ready": true,
"not_suppressed": true,
"within_tcpa_hours": true,
"billing_ok": true,
"byoc_required_ok": true,
"list_allowed_for_key": true,
"daily_send_cap_ok": true
},
"segment_count": 1,
"encoding": "GSM-7",
"estimated_cost": 0.0045,
"currency": "usd",
"cost_basis": "estimated at current cycle position; final unit cost is positional within the pooled period",
"contact_on_list": true
}
{
"eligible": true,
"checks": { "sender_ready": true, "byoc_webhook_ready": true, "not_suppressed": true, "within_tcpa_hours": true, "billing_ok": true, "byoc_required_ok": true, "list_allowed_for_key": true, "daily_send_cap_ok": true },
"segment_count": 1,
"encoding": "GSM-7",
"estimated_cost": null,
"currency": "usd",
"cost_basis": "cost is managed by the parent account (pooled billing)",
"contact_on_list": true
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | invalid_payload | The body is not a JSON object. |
| 400 | missing_fields | to, list_number, or body is missing or empty. |
| 400 | invalid_phone | to is not a valid E.164 number. |
| 400 | invalid_list_number | list_number is not a valid E.164 number. |
Warm-up is not evaluated by preflight. A warm-up-gated list may pass preflight but still defer a live send.