> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Programmatically send SMS messages with the Trackly SMS API

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

<Warning>
  The v1 API is **deprecated**. All v1 endpoints will continue to work but include deprecation headers in responses. Please migrate to v2 as soon as possible.
</Warning>

| Version | Status      | Notes                                               |
| ------- | ----------- | --------------------------------------------------- |
| v1      | Deprecated  | Legacy API, includes deprecation headers            |
| v2      | **Current** | Production API with enhanced endpoints and features |

## Authentication

All API requests require authentication using an API key passed in the `X-Api-Key` header.

```bash theme={null}
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"}'
```

<Note>
  The v2 API uses `to` for the recipient phone number and `list_number` for the sending phone number (E.164 format).
</Note>

See [Authentication](/api-reference/authentication) for details on obtaining and managing API keys.

## V2 API (Current)

<Tip>
  The **v2 API** is the current, recommended version with full support for contacts, audiences, creatives, schedules, revenue tracking, and more. [View V2 API Reference](/api-reference/v2/overview)
</Tip>

<CardGroup cols={2}>
  <Card title="V2 API Overview" icon="rocket" href="/api-reference/v2/overview">
    Full v2 API reference with all endpoints
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/api-reference/v2/messages/send-single">
    Send single and bulk SMS messages
  </Card>

  <Card title="Contacts" icon="user" href="/api-reference/v2/contacts/list-contacts">
    Create, list, and manage contacts
  </Card>

  <Card title="Audiences" icon="users" href="/api-reference/v2/audiences/list-audiences">
    Build dynamic audience segments
  </Card>

  <Card title="Schedules" icon="calendar" href="/api-reference/v2/schedules/list-schedules">
    Schedule and automate campaigns
  </Card>

  <Card title="Migration Guide" icon="arrow-right" href="/api-reference/v2/migration-guide">
    Upgrade from v1 to v2
  </Card>
</CardGroup>

## V1 API (Deprecated)

<CardGroup cols={2}>
  <Card title="Messages (v1)" icon="paper-plane" href="/api-reference/messages/send-single">
    Send messages (deprecated)
  </Card>

  <Card title="Contacts (v1)" icon="user" href="/api-reference/contacts/list-contacts">
    Contact stubs (no-op)
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/v2/webhooks/events">
    Delivery status webhooks
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/errors">
    V1 error reference
  </Card>
</CardGroup>

## 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:

<Tabs>
  <Tab title="Success — V2 (2xx)">
    ```json theme={null}
    {
      "success": true,
      "message_id": "AbC12345",
      "status": "queued"
    }
    ```
  </Tab>

  <Tab title="Success — V1 (2xx)">
    ```json theme={null}
    {
      "id": "6789abcd",
      "message_id": "6789abcd",
      "status": "queued",
      "segments": 1,
      "gsm7": true,
      "deprecated": true
    }
    ```
  </Tab>

  <Tab title="Error (4xx/5xx)">
    ```json theme={null}
    {
      "error": "Error description",
      "code": "error_code"
    }
    ```
  </Tab>
</Tabs>

## Deprecation Headers

All v1 API responses include these headers:

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

## API Limits

Trackly SMS rate-limits API requests to **60 per minute per IP address**; use bulk endpoints (up to 1,000 messages per request) to scale within that limit. See [API Limits & Best Practices](/api-reference/v2/rate-limiting) for the full rate-limit, payload-size, and batch guidance.

## SDKs & Libraries

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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());
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Send First SMS" icon="paper-plane" href="/quickstarts/send-first-sms">
    Get started with a quick tutorial
  </Card>

  <Card title="V2 API Overview" icon="book" href="/api-reference/v2/overview">
    Explore the full v2 API
  </Card>
</CardGroup>