Create Schedule

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

name

string

required

A descriptive name for this schedule.

send_type

string

required

The type of schedule. Must be blast or automated.

audiences

array of strings

required

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

is_repeating

boolean

required

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

send_time

string

required

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

source_lists

array of integers

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

status

string

default:"draft"

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

send_date

datetime

required

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

start_date

datetime

required

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

end_date

datetime

required

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

days_of_week

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.

skip_within_hours

float

default:"0"

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

use_local_time

boolean

default:"false"

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

filter_bots

boolean

default:"false"

Enable bot filtering to exclude suspected bot clicks from reporting.

is_mms

boolean

default:"false"

Set to true to send MMS messages with image attachments.

is_cto

boolean

default:"false"

Enable click-to-open mode.

automated_percent

float

default:"0"

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

ir_revenue

float

default:"0"

Expected revenue per conversion, used for reporting and optimization.

blasts

array

required

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

Show Blast object properties

blasts[].message

string

required

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

blasts[].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 (string) — additional URL query parameters

blasts[].percent_audience

float

required

Percentage of the audience that should receive this variant. The percent_audience values across all blasts must sum to exactly 100.

blasts[].variant_name

string

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

blasts[].mms_image_url

string

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

Response Fields

success

boolean

true if the schedule was created successfully.

schedule

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://app.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:00Z",
    "end_date": "2025-08-31T00:00:00Z",
    "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": "offer_abc123",
            "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": "offer_abc123",
            "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:00Z",
    "end_date": "2025-08-31T00:00:00Z",
    "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": "offer_abc123",
                    "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": "offer_abc123",
                    "url_params": {"utm_source": "sms", "utm_campaign": "weekend"},
                }
            ],
            "percent_audience": 40,
            "variant_name": "Urgency Variant",
        },
    ],
}

response = requests.post(
    "https://app.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:00Z",
  end_date: "2025-08-31T00:00:00Z",
  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: "offer_abc123",
          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: "offer_abc123",
          url_params: "utm_source=sms&utm_campaign=weekend"
        }
      ],
      percent_audience: 40,
      variant_name: "Urgency Variant"
    }
  ]
};

const response = await fetch("https://app.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:00Z",
    "end_date": "2025-08-31T00:00:00Z",
    "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": "offer_abc123",
            "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": "offer_abc123",
            "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:30Z",
    "updated_at": "2025-05-28T10:15:30Z"
  }
}

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`.
404	`audience_not_found`	One or more audience IDs do not exist or are not active.
404	`source_list_not_found`	One or more source list IDs do not exist on this account.
404	`offer_not_found`	One or more offer IDs referenced in `offer_links` do not exist.
401	`unauthorized`	API key is missing, invalid, or revoked.

API Reference

V2 API Reference

Messages (v2)

Contacts (v2)

Lists (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Data Import (v2)

Links (v2)

Webhooks (v2)

API Reference (v1 - Deprecated)

Body Parameters

Response Fields

Examples

Error Codes

Next Steps

Campaign Scheduling

List Audiences

API Reference

V2 API Reference

Messages (v2)

Contacts (v2)

Lists (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Data Import (v2)

Links (v2)

Webhooks (v2)

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