API Limits & Best Practices

Trackly SMS is built for high-volume sending. Throughput scales with bulk requests, since one request can carry up to 1,000 messages — batch aggressively to reach high send rates.

Rate Limits

The core sending endpoints (/v2/send, /v2/send/bulk, and related SMS/email endpoints) do not enforce a fixed per-IP request-rate cap. In practice, throughput is bound by request latency and payload size, so bulk endpoints are how you scale: a single POST /v2/send/bulk carries up to 1,000 messages. Some specialized endpoints (for example OTP and phone validation) enforce their own limits, and an API key can carry a daily send cap (dailySendCap, see Who Am I) that bounds its live sends per UTC day. When one is exceeded, the response is 429 Too Many Requests with a rate_limited code, or daily_cap_exceeded for a send cap:

429 - Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": "rate_limited"
}

When you receive a 429, pause and retry with exponential backoff after the window resets. Prefer bulk requests over many single requests for efficiency and reliability. The per-key daily cap applies to the four SMS send endpoints. Capped keys cannot create or edit schedules because scheduled execution does not carry the key’s cap accounting. Those requests return 403 schedule_not_allowed_for_capped_key; exact status-only off or archive updates remain subject to normal execution locks. Sandbox and OTP requests do not consume this counter.

Payload Limits

Limit	Value	Response
Maximum request payload	5 MB	`413 Payload Too Large`
Individual contact payload	4,000 bytes	`400 payload_too_large`

Batch Limits

Bulk endpoints accept up to 1,000 records per request. Each record is processed individually — partial success is possible.

Operation	Single Endpoint	Bulk Endpoint	Max per Request
Send messages	`POST /v2/send`	`POST /v2/send/bulk`	1,000
Create contacts	`POST /v2/contacts`	`POST /v2/contacts/bulk`	1,000
Record revenue	`POST /v2/revenue`	`POST /v2/revenue/bulk`	1,000
Import history	—	`POST /v2/history/import`	1,000

To process more than 1,000 items, split your data into batches and send multiple requests.

Best Practices

Use Bulk Endpoints

Buffer messages locally and send in bulk batches. Sending 1,000 messages in a single bulk request is more efficient than 1,000 individual requests — fewer round trips, lower latency, and less overhead on both sides.

import requests

# Send up to 1,000 messages in one request
messages = [
    {"to": f"+1415555{i:04d}", "body": "Flash sale! 50% off today."}
    for i in range(1000)
]

response = requests.post(
    "https://api.tracklysms.com/api/v2/send/bulk",
    headers={"X-Api-Key": "trk_your_api_key_here"},
    json={"list_number": "+18005551234", "messages": messages}
)

data = response.json()
print(f"Queued: {data['queued_count']}, Errors: {data['error_count']}")

const messages = Array.from({ length: 1000 }, (_, i) => ({
  to: `+1415555${String(i).padStart(4, "0")}`,
  body: "Flash sale! 50% off today.",
}));

const response = await fetch("https://api.tracklysms.com/api/v2/send/bulk", {
  method: "POST",
  headers: {
    "X-Api-Key": "trk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ list_number: "+18005551234", messages }),
});

const data = await response.json();
console.log(`Queued: ${data.queued_count}, Errors: ${data.error_count}`);

curl -X POST https://api.tracklysms.com/api/v2/send/bulk \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "list_number": "+18005551234",
    "messages": [
      {"to": "+14155551234", "body": "Flash sale! 50% off today."},
      {"to": "+14155555678", "body": "Flash sale! 50% off today."}
    ]
  }'

Handle Transient Errors

Use exponential backoff with jitter for failed read requests. A send timeout or publication error can occur after submission, so check message status before deciding whether to send again. Such publication attempts retain daily quota. Known construction or storage failures before publication attempt to refund a confirmed reservation. If that refund fails or cannot be confirmed, allowance may remain used for the original UTC day even though the message was not published; check Who Am I for current usage before retrying a capped send. If the quota reservation itself cannot be confirmed, the send is refused but the reservation may remain charged. Live sends recheck the key’s current policy before admission, including keys without a daily cap. A policy change during a request or an unavailable policy check can return 503 send_cap_unavailable; retry with backoff so the next request uses the current limits.

import time
import random
import requests

def get_with_retry(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code < 500:
            return response

        wait = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(wait)

    raise Exception("Max retries exceeded")

Handle Partial Failures

Bulk responses include per-record errors. Retry corrected items only when their error establishes that submission did not occur. Publication errors and timeouts require reconciliation using the message ID when available; do not automatically resend those items or the entire batch.

{
  "queued_count": 998,
  "error_count": 2,
  "errors": [
    {"index": 42, "to": "+1invalid", "code": "invalid_phone", "error": "Invalid recipient phone number format"},
    {"index": 501, "to": "+14155559999", "code": "doi_expired", "error": "Contact never confirmed their double opt-in (window expired)"}
  ]
}

Parallelize Across Batches

You can send multiple bulk requests concurrently. Split large sends into 1,000-message batches and dispatch them in parallel; very high concurrency is bound by request latency, so batch aggressively with bulk endpoints.

API Reference

V2 API Reference

Agent Account Setup (v2)

Agent Number Registration (v2)

Pending Sends (v2)

Partner Accounts (v2)

Messages (v2)

Contacts (v2)

Lists (v2)

Number Requests (v2)

Business Verification (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Usage & Billing (v2)

Data Import (v2)

Links (v2)

Clicks (v2)

Webhooks (v2)

Phone Validation (v1)

Voice Calls (v1)

API Reference (v1 - Deprecated)

API Limits & Best Practices

API Limits & Best Practices

Rate Limits

Payload Limits

Batch Limits

Best Practices

Use Bulk Endpoints

Handle Transient Errors

Handle Partial Failures

Parallelize Across Batches

Next Steps

Error Codes

Send Bulk

​API Limits & Best Practices

​Rate Limits

​Payload Limits

​Batch Limits

​Best Practices

​Use Bulk Endpoints

​Handle Transient Errors

​Handle Partial Failures

​Parallelize Across Batches

​Next Steps

Error Codes

Send Bulk

API Limits & Best Practices

Rate Limits

Payload Limits

Batch Limits

Best Practices

Use Bulk Endpoints

Handle Transient Errors

Handle Partial Failures

Parallelize Across Batches

Next Steps