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

# Create Schedule

> Create a new schedule for sending messages to an audience.

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

<ParamField body="name" type="string" required>
  A descriptive name for this schedule.
</ParamField>

<ParamField body="send_type" type="string" required>
  The type of schedule. Must be `blast` or `automated`.
</ParamField>

<ParamField body="audiences" type="array of strings" required>
  Array of audience IDs to target. Each audience must exist and be active on your account.
</ParamField>

<ParamField body="is_repeating" type="boolean" required>
  Set to `true` for a recurring schedule that runs on selected days of the week, or `false` for a one-time send.
</ParamField>

<ParamField body="send_time" type="string" required>
  Time of day to send, in `HH:MM` format (24-hour clock). For example, `"14:30"` for 2:30 PM.
</ParamField>

<ParamField body="source_lists" type="array of integers" optional>
  IDs of source sending lists. Each list must exist on your account.
</ParamField>

<ParamField body="status" type="string" optional default="draft">
  Initial status. Allowed values: `draft`, `off`, `on`. Defaults to `draft`.
</ParamField>

<ParamField body="send_date" type="datetime" required="Required if is_repeating is false">
  The date to send for a one-time schedule. Required when `is_repeating` is `false`.
</ParamField>

<ParamField body="start_date" type="datetime" required="Required if is_repeating is true">
  The first date the repeating schedule should run. Required when `is_repeating` is `true`.
</ParamField>

<ParamField body="end_date" type="datetime" required="Required if is_repeating is true">
  The last date the repeating schedule should run. Required when `is_repeating` is `true`.
</ParamField>

<ParamField body="days_of_week" type="object" required="Required if is_repeating is true">
  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`.
</ParamField>

<ParamField body="skip_within_hours" type="float" optional default="0">
  Skip sending to a contact if they were already sent to within this many hours. Set to `0` to disable.
</ParamField>

<ParamField body="use_local_time" type="boolean" optional default="false">
  When `true`, `send_time` is interpreted in each recipient's local timezone rather than the account timezone.
</ParamField>

<ParamField body="filter_bots" type="boolean" optional default="false">
  Enable bot filtering to display an interstitial page for suspected bots instead of the message.
</ParamField>

<ParamField body="is_mms" type="boolean" optional default="false">
  Set to `true` to send MMS messages with image attachments.
</ParamField>

<ParamField body="is_cto" type="boolean" optional default="false">
  Enable click-to-open mode.
</ParamField>

<ParamField body="automated_percent" type="float" optional default="0">
  Percentage of the audience to allocate to automated (ML-powered) creative selection. Value between `0` and `100`.
</ParamField>

<ParamField body="ir_revenue" type="float" optional default="0">
  Expected or target revenue from this send, used for reporting and optimization.
</ParamField>

<ParamField body="blasts" type="array" required="Required for blast send_type">
  Array of blast variant objects. Required when `send_type` is `blast`.

  <Expandable title="Blast object properties">
    <ParamField body="blasts[].message" type="string" required>
      The message body. Use `{{link1}}`, `{{link2}}`, etc. as placeholders for offer links.
    </ParamField>

    <ParamField body="blasts[].offer_links" type="array" optional>
      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
    </ParamField>

    <ParamField body="blasts[].percent_audience" type="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.
    </ParamField>

    <ParamField body="blasts[].variant_name" type="string" optional>
      A label for this variant (e.g. "Control", "Variant A").
    </ParamField>

    <ParamField body="blasts[].mms_image_url" type="string" optional>
      URL of an image to attach as MMS. Only used when `is_mms` is `true`.
    </ParamField>
  </Expandable>
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
  `true` if the schedule was created successfully.
</ResponseField>

<ResponseField name="schedule" type="object">
  The full schedule object, including all fields and the generated `id`. See [List Schedules](/api-reference/v2/schedules/list-schedules) for the complete schedule object schema.
</ResponseField>

## Examples

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

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

<ResponseExample>
  ```json 201 — Created theme={null}
  {
    "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"
    }
  }
  ```

  ```json 400 — Validation Error theme={null}
  {
    "error": "blasts is required for blast send type",
    "code": "missing_blasts"
  }
  ```

  ```json 401 — Unauthorized theme={null}
  {
    "error": "Invalid credentials",
    "code": "invalid_credentials"
  }
  ```

  ```json 400 — Audience Not Found theme={null}
  {
    "error": "Audience not found: 665fa1b2c3d4e5f6a7b8c901",
    "code": "audience_not_found"
  }
  ```
</ResponseExample>

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Campaign Scheduling" icon="calendar" href="/guides/campaigns/scheduling">
    Learn scheduling best practices
  </Card>

  <Card title="List Audiences" icon="users" href="/api-reference/v2/audiences/list-audiences">
    Find audiences for your campaign
  </Card>
</CardGroup>