API Overview - Trackly SMS

The Trackly SMS API allows you to send SMS messages programmatically. Use it to integrate SMS into your applications, automate sends from your systems, or build custom integrations.

Base URL

All API requests should be made to:

https://api.tracklysms.com/api

API Versions

The v1 API is retired for message sending (POST /v1/messages returns 410 Gone); remaining v1 endpoints are no-ops or deprecated. Use v2. Deprecation headers are added to all v1 responses.

Version	Status	Notes
v1	Deprecated	Message send retired (`410 Gone`); contacts endpoints are no-ops. All responses include deprecation headers
v2	Current	Production API with enhanced endpoints and features

Authentication

Authenticated SMS API operations use an API key in the X-Api-Key header. The enrollment exceptions are starting new-customer setup, which requires no API key, and polling setup status, which requires its limited Authorization: Bearer <poll_token> capability. Neither enrollment operation grants messaging access.

curl -X POST https://api.tracklysms.com/api/v2/send \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155551234", "body": "Hello!", "list_number": "+18005551234"}'

The v2 API uses to for the recipient phone number and list_number for the sending phone number (E.164 format).

See Authentication for details on obtaining and managing API keys.

AI assistants and human approval

Use Trackly MCP to connect an AI assistant, or call the same v2 endpoints from your own application. The flow checks account identity and message eligibility, holds immutable content for dashboard review, executes only after approval, and reads back the result. Keep the key in private client settings and enable Require send approval.

Connect an AI assistant

Configure a private key, sandbox mode, and a verified MCP connection.

Send with approval

Follow the tool workflow and handle uncertain execution without duplicate sends.

This reference describes the SMS API at api.tracklysms.com/api. The dashboard’s separate Developers → API Reference describes its Public API v1 surface and should not be used as the authentication or endpoint contract for these SMS examples.

V2 API (Current)

The v2 API is the current, recommended version with full support for contacts, audiences, creatives, schedules, revenue tracking, and more. View V2 API Reference

V2 API Overview

Full v2 API reference with all endpoints

Send Messages

Send single and bulk SMS messages

Contacts

Create, list, and manage contacts

Audiences

Build dynamic audience segments

Schedules

Schedule and automate campaigns

Migration Guide

Upgrade from v1 to v2

V1 API (Deprecated)

Messages (v1)

Retired — returns 410

Contacts (v1)

Contact stubs (no-op)

Webhooks

Delivery status webhooks

Error Codes

V1 error reference

Request Format

All requests must include Content-Type: application/json
Phone numbers should be in E.164 format (e.g., +14155551234)
Request bodies must be valid JSON

Response Format

All responses are JSON with a consistent structure:

Success — V2 (2xx)
V1 Contacts & Phone Validation (2xx)
V1 Send (410 Gone)
Error (4xx/5xx)

{
  "success": true,
  "message_id": "AbC12345",
  "status": "queued"
}

Contacts (no-op stub)

{
  "success": true,
  "deprecated": true,
  "message": "This endpoint is deprecated and performs no operation."
}

Phone validation

{
  "phone": "+14155551234",
  "valid": true,
  "line_type": "mobile",
  "carrier": "Verizon",
  "ported": false,
  "country": "US",
  "on_dnc": false,
  "disposition": "ok",
  "cost": 0.003,
  "cached": false
}

{
  "error": "The v1 message-send endpoints are retired. Migrate to the v2 messages API.",
  "code": "endpoint_retired"
}

{
  "error": "Error description",
  "code": "error_code"
}

Deprecation Headers

All v1 API responses include these headers:

Header	Value
`X-API-Deprecated`	`v1 is deprecated`
`Deprecation`	`true`

API Limits

Trackly SMS does not apply one platform-wide rate limit; limits are enforced per endpoint, mostly per account. Use bulk endpoints (up to 1,000 messages per request) to scale your sending. See API Limits & Best Practices for the full rate-limit, payload-size, and batch guidance.

SDKs & Libraries

Currently, we recommend using standard HTTP libraries in your preferred language:

curl -X POST https://api.tracklysms.com/api/v2/send \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "body": "Hello from Trackly!",
    "list_number": "+18005551234"
  }'

import requests

response = requests.post(
    "https://api.tracklysms.com/api/v2/send",
    headers={
        "X-Api-Key": "trk_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "to": "+14155551234",
        "body": "Hello from Trackly!",
        "list_number": "+18005551234"
    }
)
print(response.json())

const response = await fetch("https://api.tracklysms.com/api/v2/send", {
  method: "POST",
  headers: {
    "X-Api-Key": "trk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+14155551234",
    body: "Hello from Trackly!",
    list_number: "+18005551234",
  }),
});
console.log(await response.json());

​Base URL

​API Versions

​Authentication

​AI assistants and human approval

Connect an AI assistant

Send with approval

​V2 API (Current)

V2 API Overview

Send Messages

Contacts

Audiences

Schedules

Migration Guide

​V1 API (Deprecated)

Messages (v1)

Contacts (v1)

Webhooks

Error Codes

​Request Format

​Response Format

​Deprecation Headers

​API Limits

​SDKs & Libraries

​Next Steps

Send First SMS

V2 API Overview

Base URL

API Versions

Authentication

AI assistants and human approval

V2 API (Current)

V1 API (Deprecated)

Request Format

Response Format

Deprecation Headers

API Limits

SDKs & Libraries

Next Steps