Create Schedule

{
  "success": true,
  "schedule": {
    "id": "6651a3f2e4b0a1c2d3e4f567",
    "name": "Weekend Promo",
    "status": "draft",
    "send_type": "blast",
    "source_lists": [],
    "audiences": ["665fa1b2c3d4e5f6a7b8c901"],
    "is_repeating": true,
    "send_time": "14:30",
    "send_date": null,
    "start_date": "2025-06-01T00:00:00",
    "end_date": "2025-08-31T00:00:00",
    "days_of_week": {
      "monday": false,
      "tuesday": false,
      "wednesday": false,
      "thursday": false,
      "friday": true,
      "saturday": true,
      "sunday": true
    },
    "skip_within_hours": 24,
    "use_local_time": true,
    "filter_bots": true,
    "is_mms": false,
    "is_cto": false,
    "automated_percent": 0,
    "ir_revenue": 0,
    "blasts": [
      {
        "message": "Flash sale this weekend! Shop now: {{link1}}",
        "offer_links": [
          {
            "key": "link1",
            "offer_id": "665fa1b2c3d4e5f6a7b8c902",
            "custom_url": null,
            "url_params": {"utm_source": "sms", "utm_campaign": "weekend"}
          }
        ],
        "percent_audience": 60,
        "variant_name": "Control",
        "mms_image_url": null
      },
      {
        "message": "20% off everything — this weekend only: {{link1}}",
        "offer_links": [
          {
            "key": "link1",
            "offer_id": "665fa1b2c3d4e5f6a7b8c902",
            "custom_url": null,
            "url_params": {"utm_source": "sms", "utm_campaign": "weekend"}
          }
        ],
        "percent_audience": 40,
        "variant_name": "Urgency Variant",
        "mms_image_url": null
      }
    ],
    "created_at": "2025-05-28T10:15:30",
    "updated_at": "2025-05-28T10:15:30"
  }
}

{
  "error": "blasts is required for blast send type",
  "code": "missing_blasts"
}

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

{
  "error": "Audience not found: 665fa1b2c3d4e5f6a7b8c901",
  "code": "audience_not_found"
}

POST

schedules

{
  "success": true,
  "schedule": {
    "id": "6651a3f2e4b0a1c2d3e4f567",
    "name": "Weekend Promo",
    "status": "draft",
    "send_type": "blast",
    "source_lists": [],
    "audiences": ["665fa1b2c3d4e5f6a7b8c901"],
    "is_repeating": true,
    "send_time": "14:30",
    "send_date": null,
    "start_date": "2025-06-01T00:00:00",
    "end_date": "2025-08-31T00:00:00",
    "days_of_week": {
      "monday": false,
      "tuesday": false,
      "wednesday": false,
      "thursday": false,
      "friday": true,
      "saturday": true,
      "sunday": true
    },
    "skip_within_hours": 24,
    "use_local_time": true,
    "filter_bots": true,
    "is_mms": false,
    "is_cto": false,
    "automated_percent": 0,
    "ir_revenue": 0,
    "blasts": [
      {
        "message": "Flash sale this weekend! Shop now: {{link1}}",
        "offer_links": [
          {
            "key": "link1",
            "offer_id": "665fa1b2c3d4e5f6a7b8c902",
            "custom_url": null,
            "url_params": {"utm_source": "sms", "utm_campaign": "weekend"}
          }
        ],
        "percent_audience": 60,
        "variant_name": "Control",
        "mms_image_url": null
      },
      {
        "message": "20% off everything — this weekend only: {{link1}}",
        "offer_links": [
          {
            "key": "link1",
            "offer_id": "665fa1b2c3d4e5f6a7b8c902",
            "custom_url": null,
            "url_params": {"utm_source": "sms", "utm_campaign": "weekend"}
          }
        ],
        "percent_audience": 40,
        "variant_name": "Urgency Variant",
        "mms_image_url": null
      }
    ],
    "created_at": "2025-05-28T10:15:30",
    "updated_at": "2025-05-28T10:15:30"
  }
}

{
  "error": "blasts is required for blast send type",
  "code": "missing_blasts"
}

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

{
  "error": "Audience not found: 665fa1b2c3d4e5f6a7b8c901",
  "code": "audience_not_found"
}

Create a new schedule to send SMS or MMS messages to one or more audiences. Schedules can be one-time or repeating, and support multiple blast variants for A/B testing.

Body Parameters

string

required

A descriptive name for this schedule.

string

required

The type of schedule. Must be blast or automated.

array of strings

required

Array of audience IDs to target. Each audience must exist and be active on your account.

boolean

required

Set to true for a recurring schedule that runs on selected days of the week, or false for a one-time send.

string

required

Time of day to send, in HH:MM format (24-hour clock). For example, "14:30" for 2:30 PM.

array of integers

IDs of source sending lists. Each list must exist on your account.

string

default:"draft"

Initial status. Allowed values: draft, off, on. Defaults to draft.

datetime

required

The date to send for a one-time schedule. Required when is_repeating is false.

datetime

required

The first date the repeating schedule should run. Required when is_repeating is true.

datetime

required

The last date the repeating schedule should run. Required when is_repeating is true.

object

required

An object specifying which days the schedule should run. Keys: monday, tuesday, wednesday, thursday, friday, saturday, sunday. Values are booleans. At least one day must be true.

float

default:"0"

Skip sending to a contact if they were already sent to within this many hours. Set to 0 to disable.

boolean

default:"false"

When true, send_time is interpreted in each recipient’s local timezone rather than the account timezone.

boolean

default:"false"

Enable bot filtering to display an interstitial page for suspected bots instead of the message.

boolean

default:"false"

Set to true to send MMS messages with image attachments.

boolean

default:"false"

Enable click-to-open mode.

float

default:"0"

Percentage of the audience to allocate to automated (ML-powered) creative selection. Value between 0 and 100.

float

default:"0"

Expected or target revenue from this send, used for reporting and optimization.

array

required

Array of blast variant objects. Required when send_type is blast.

Show Blast object properties

string

required

The message body. Use {{link1}}, {{link2}}, etc. as placeholders for offer links.

array

Array of offer link objects. Each contains:

key (string) — placeholder key, e.g. "link1"
offer_id (string) — ID of the offer
url_params (object) — additional URL query parameters as a key/value object

float

required

Percentage of the audience that should receive this variant. Required on every blast: the percent_audience values across all blasts must sum to exactly 100, and a blast that omits it is treated as 0, which fails that check.

string

A label for this variant (e.g. “Control”, “Variant A”).

string

URL of an image to attach as MMS. Only used when is_mms is true.

Response Fields

boolean

true if the schedule was created successfully.

object

The full schedule object, including all fields and the generated id. See List Schedules for the complete schedule object schema.

Examples

cURL

curl -X POST "https://api.tracklysms.com/api/v2/schedules" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend Promo",
    "send_type": "blast",
    "audiences": ["665fa1b2c3d4e5f6a7b8c901"],
    "is_repeating": true,
    "send_time": "14:30",
    "start_date": "2025-06-01T00:00:00",
    "end_date": "2025-08-31T00:00:00",
    "days_of_week": {
      "monday": false,
      "tuesday": false,
      "wednesday": false,
      "thursday": false,
      "friday": true,
      "saturday": true,
      "sunday": true
    },
    "skip_within_hours": 24,
    "use_local_time": true,
    "filter_bots": true,
    "blasts": [
      {
        "message": "Flash sale this weekend! Shop now: {{link1}}",
        "offer_links": [
          {
            "key": "link1",
            "offer_id": "665fa1b2c3d4e5f6a7b8c902",
            "url_params": {"utm_source": "sms", "utm_campaign": "weekend"}
          }
        ],
        "percent_audience": 60,
        "variant_name": "Control"
      },
      {
        "message": "20% off everything — this weekend only: {{link1}}",
        "offer_links": [
          {
            "key": "link1",
            "offer_id": "665fa1b2c3d4e5f6a7b8c902",
            "url_params": {"utm_source": "sms", "utm_campaign": "weekend"}
          }
        ],
        "percent_audience": 40,
        "variant_name": "Urgency Variant"
      }
    ]
  }'

Python

import requests

payload = {
    "name": "Weekend Promo",
    "send_type": "blast",
    "audiences": ["665fa1b2c3d4e5f6a7b8c901"],
    "is_repeating": True,
    "send_time": "14:30",
    "start_date": "2025-06-01T00:00:00",
    "end_date": "2025-08-31T00:00:00",
    "days_of_week": {
        "monday": False,
        "tuesday": False,
        "wednesday": False,
        "thursday": False,
        "friday": True,
        "saturday": True,
        "sunday": True,
    },
    "skip_within_hours": 24,
    "use_local_time": True,
    "filter_bots": True,
    "blasts": [
        {
            "message": "Flash sale this weekend! Shop now: {{link1}}",
            "offer_links": [
                {
                    "key": "link1",
                    "offer_id": "665fa1b2c3d4e5f6a7b8c902",
                    "url_params": {"utm_source": "sms", "utm_campaign": "weekend"},
                }
            ],
            "percent_audience": 60,
            "variant_name": "Control",
        },
        {
            "message": "20% off everything — this weekend only: {{link1}}",
            "offer_links": [
                {
                    "key": "link1",
                    "offer_id": "665fa1b2c3d4e5f6a7b8c902",
                    "url_params": {"utm_source": "sms", "utm_campaign": "weekend"},
                }
            ],
            "percent_audience": 40,
            "variant_name": "Urgency Variant",
        },
    ],
}

response = requests.post(
    "https://api.tracklysms.com/api/v2/schedules",
    headers={
        "X-Api-Key": "trk_your_api_key_here",
        "Content-Type": "application/json",
    },
    json=payload,
)

data = response.json()
print(f"Created schedule: {data['schedule']['id']}")

Node.js

const payload = {
  name: "Weekend Promo",
  send_type: "blast",
  audiences: ["665fa1b2c3d4e5f6a7b8c901"],
  is_repeating: true,
  send_time: "14:30",
  start_date: "2025-06-01T00:00:00",
  end_date: "2025-08-31T00:00:00",
  days_of_week: {
    monday: false,
    tuesday: false,
    wednesday: false,
    thursday: false,
    friday: true,
    saturday: true,
    sunday: true
  },
  skip_within_hours: 24,
  use_local_time: true,
  filter_bots: true,
  blasts: [
    {
      message: "Flash sale this weekend! Shop now: {{link1}}",
      offer_links: [
        {
          key: "link1",
          offer_id: "665fa1b2c3d4e5f6a7b8c902",
          url_params: { utm_source: "sms", utm_campaign: "weekend" }
        }
      ],
      percent_audience: 60,
      variant_name: "Control"
    },
    {
      message: "20% off everything — this weekend only: {{link1}}",
      offer_links: [
        {
          key: "link1",
          offer_id: "665fa1b2c3d4e5f6a7b8c902",
          url_params: { utm_source: "sms", utm_campaign: "weekend" }
        }
      ],
      percent_audience: 40,
      variant_name: "Urgency Variant"
    }
  ]
};

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

const data = await response.json();
console.log(`Created schedule: ${data.schedule.id}`);

{
  "success": true,
  "schedule": {
    "id": "6651a3f2e4b0a1c2d3e4f567",
    "name": "Weekend Promo",
    "status": "draft",
    "send_type": "blast",
    "source_lists": [],
    "audiences": ["665fa1b2c3d4e5f6a7b8c901"],
    "is_repeating": true,
    "send_time": "14:30",
    "send_date": null,
    "start_date": "2025-06-01T00:00:00",
    "end_date": "2025-08-31T00:00:00",
    "days_of_week": {
      "monday": false,
      "tuesday": false,
      "wednesday": false,
      "thursday": false,
      "friday": true,
      "saturday": true,
      "sunday": true
    },
    "skip_within_hours": 24,
    "use_local_time": true,
    "filter_bots": true,
    "is_mms": false,
    "is_cto": false,
    "automated_percent": 0,
    "ir_revenue": 0,
    "blasts": [
      {
        "message": "Flash sale this weekend! Shop now: {{link1}}",
        "offer_links": [
          {
            "key": "link1",
            "offer_id": "665fa1b2c3d4e5f6a7b8c902",
            "custom_url": null,
            "url_params": {"utm_source": "sms", "utm_campaign": "weekend"}
          }
        ],
        "percent_audience": 60,
        "variant_name": "Control",
        "mms_image_url": null
      },
      {
        "message": "20% off everything — this weekend only: {{link1}}",
        "offer_links": [
          {
            "key": "link1",
            "offer_id": "665fa1b2c3d4e5f6a7b8c902",
            "custom_url": null,
            "url_params": {"utm_source": "sms", "utm_campaign": "weekend"}
          }
        ],
        "percent_audience": 40,
        "variant_name": "Urgency Variant",
        "mms_image_url": null
      }
    ],
    "created_at": "2025-05-28T10:15:30",
    "updated_at": "2025-05-28T10:15:30"
  }
}

{
  "error": "blasts is required for blast send type",
  "code": "missing_blasts"
}

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

{
  "error": "Audience not found: 665fa1b2c3d4e5f6a7b8c901",
  "code": "audience_not_found"
}

Error Codes

HTTP Status	Error Code	Description
400	`missing_name`	The `name` field is required.
400	`missing_send_type`	The `send_type` field is required.
400	`invalid_send_type`	`send_type` must be `blast` or `automated`.
400	`missing_is_repeating`	The `is_repeating` field is required.
400	`missing_send_time`	The `send_time` field is required.
400	`missing_audiences`	At least one audience ID is required.
400	`invalid_status`	`status` must be `draft`, `off`, or `on`.
400	`missing_send_date`	`send_date` is required for one-time (non-repeating) schedules.
400	`missing_start_date`	`start_date` is required for repeating schedules.
400	`missing_end_date`	`end_date` is required for repeating schedules.
400	`no_days_selected`	At least one day must be `true` in `days_of_week` for repeating schedules.
400	`missing_blasts`	Blast variants are required when `send_type` is `blast`.
400	`invalid_blast_percent`	The `percent_audience` values across all blasts must sum to exactly `100`.
400	`missing_blast_message`	Each blast variant must include a `message`.
400	`invalid_numeric`	`skip_within_hours`, `automated_percent`, or `ir_revenue` is not a number.
400	`invalid_audience_id`	An audience ID is not a valid identifier.
400	`audience_not_found`	One or more audience IDs do not exist or are not active.
400	`source_list_not_found`	One or more source list IDs do not exist on this account.
400	`invalid_offer_id`	An offer ID referenced in `offer_links` is not a valid identifier.
400	`offer_not_found`	One or more offer IDs referenced in `offer_links` do not exist.
401	`invalid_credentials`	API key is missing, invalid, or revoked.
403	`account_suspended`	Your account is suspended. Resolve outstanding billing or contact support.
429	`rate_limited`	Request throttled; retry with exponential backoff after the window resets.

API Reference

V2 API Reference

Partner Accounts (v2)

Messages (v2)

Contacts (v2)

Lists (v2)

Number Requests (v2)

Business Profiles (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)

API Reference (v1 - Deprecated)

Body Parameters

Response Fields

Examples

Error Codes

Next Steps

Campaign Scheduling

List Audiences

​Body Parameters

​Response Fields

​Examples

​Error Codes

​Next Steps

Campaign Scheduling

List Audiences

Body Parameters

Response Fields

Examples

Error Codes

Next Steps