V2 API Overview - Trackly SMS

The v2 API is the current, production-ready version of the Trackly SMS API. It replaces the deprecated v1 API with expanded functionality, consistent field naming, and new resource types.

Base URL

All v2 API requests should be made to:

https://api.tracklysms.com/api/v2

Authentication

Authenticated operations use an API key in the X-Api-Key header:

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", "list_number": "+18005551234", "body": "Hello!"}'

API keys follow the format trk_[32-char-alphanumeric]. See Authentication for details. Enrollment creation is anonymous; enrollment status uses its own limited bearer poll token. These setup operations do not issue an API key or authorize messaging.

SMS for AI agents

Trackly MCP connects compatible assistants to identity, list discovery, preflight, pending sends, key pause, and delivery/reply readback. A person approves the rendered send in Trackly before execution. Follow connection setup and the approved-send walkthrough, or integrate directly with the pending-send endpoints. Use a dedicated sandbox key with confirmation required for initial testing. Sandbox still needs an eligible sending list and may invoke configured webhooks. A preflight success is advisory; accepted live sends must be checked for final delivery.

Set up a blast through the API

Use POST /v2/schedules with send_type: "blast", your audience IDs, inline message text, and send date/time. No saved creative is required. The key must have no daily send cap or send-approval requirement, even for drafts. Keys with list restrictions must specify nonempty, allowed source_lists. Keep status: "draft" to review it first, or set status: "on" to activate the scheduled blast. Link placeholders can map to offers from your account or public HTTPS custom URLs. Optionally set blasts[].save_as_creative: true to also keep a variant’s text and links as an independent creative for later manual sends; the default is false. The response identifies saved assets in saved_creatives and reports optional save failures in creative_save_errors, even when the schedule was successfully created with HTTP 201. The create-schedule reference includes complete request examples, ID retrieval, and retry guidance.

What’s New in V2

Feature	V1	V2
Send messages	Retired (410)	Single, bulk, raw, raw bulk
Contacts	No-op stubs	Full CRUD + bulk + journey enrollment
Lists	Not available	Read-only list management
Number Requests	Not available	Request number provisioning + track status
Business Verification	Not available	Verify and explicitly bind legal businesses within resumable number requests
Creatives	Not available	Full CRUD with segment estimation
Audiences	Not available	Full CRUD with filter DSL + size calculation
Offers	Not available	Full CRUD with metadata
Schedules	Not available	Full CRUD with blast variants
Revenue	Not available	Attribution tracking, single & bulk
Data import	Not available	Import sends, clicks, revenue history
Webhooks	Delivery status only	Delivery, unsubscribe, reply events
Agent identity and key pause	Not available	Account/key policy inspection and self-pause
Human-approved SMS	Not available	Hold, review in Trackly, execute, and read back
Agent-assisted enrollment	Not available	Start setup and poll progress; human verification remains required

Request Format

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

Response Format

All v2 responses use a consistent JSON structure.

Success (2xx)
Error (4xx)

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

{
  "error": "Human-readable error description",
  "code": "machine_readable_error_code"
}

Pagination

Pagination depends on the endpoint. Page-based collections use parameters such as:

Parameter	Default	Max	Description
`page`	1	—	Page number
`per_page`	50	1000 (contacts) / 100 (others)	Items per page

Paginated responses include a pagination object:

{
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 238,
    "total_pages": 5
  }
}

Sending lists support bounded limit and cursor pagination. Pending sends use limit and before. Follow each endpoint’s response and retain known hold IDs for direct reconciliation.

Bulk Operations

Bulk endpoints accept up to 1,000 records per request. Each record is processed individually — partial success is possible. Bulk responses include per-record error details:

{
  "queued_count": 995,
  "error_count": 5,
  "errors": [
    {"index": 3, "to": "+1invalid", "code": "invalid_phone", "error": "Invalid recipient phone number format"}
  ]
}

Available Endpoints

Agent & MCP Guide

Connect an assistant and keep human approval in the send flow

Pending Sends

Hold immutable SMS content, review it, and execute the approved send

Messages

Send single and bulk SMS messages

Raw Messages

Send raw messages with skip options

Contacts

Create, list, and manage contacts

Lists

View sending lists and contact counts

Number Requests

Request number provisioning and track status

Business Verification

Complete verification within number requests

Creatives

Manage message templates with offer links

Audiences

Build dynamic audience segments

Offers

Manage tracking offers and payouts

Schedules

Create and manage scheduled campaigns

Links

Create trackable short links for offers

Revenue

Record revenue attribution

Data Import

Import historical sends, clicks, and revenue

Webhooks

Receive delivery and reply events

Audience Filters

Build complex audience filter queries

Migration from V1

If you’re using the deprecated v1 API, see the Migration Guide for a field-by-field comparison and upgrade path.

​Base URL

​Authentication

​SMS for AI agents

​Set up a blast through the API

​What’s New in V2

​Request Format

​Response Format

​Pagination

​Bulk Operations

​Available Endpoints

Agent & MCP Guide

Pending Sends

Messages

Raw Messages

Contacts

Lists

Number Requests

Business Verification

Creatives

Audiences

Offers

Schedules

Links

Revenue

Data Import

Webhooks

Audience Filters

​Migration from V1

​Next Steps

Send First SMS

Authentication

Base URL

Authentication

SMS for AI agents

Set up a blast through the API

What’s New in V2

Request Format

Response Format

Pagination

Bulk Operations

Available Endpoints

Migration from V1

Next Steps