TextKitDocs

Change, pause or resume a schedule

active: false pauses; active: true resumes from now (nothing that came due while paused is sent).

PATCH/v1/schedules/{id}

Path Parameters

  • idstringrequired

Body Parameters

  • tostringrequired

    Example: +14155550132.

  • fromstring

    One of your numbers. Optional when the account has exactly one number for the key's mode.

  • bodystringrequired

    At most 1600 characters.

  • repeatScheduleRepeatrequired
  • start_datestring (date)

    First local date it may run. Defaults to today. Nullable.

  • end_datestring (date)

    Last local date it may run (inclusive). Nullable.

  • max_occurrencesinteger

    The schedule completes after this many messages have been sent. Minimum 1. Nullable.

  • categorymarketing, transactional, otp

    Optional. It can make each occurrence stricter (marketing), never looser: the sending number's registration and the wording decide (which messages are marketing). Nullable.

  • quiet_hoursblock, defer

    Optional. What to do with a message in the recipient's quiet hours: block refuses it (403 quiet_hours), defer holds it until their next 8:00am. Omitted: an occurrence in quiet hours is held until the recipient's 8:00am and recorded as deferred. Nullable.

Details

Any of to, from, body, repeat (the whole object), start_date, end_date, max_occurrences can be changed in the same call. Scope: messages:send.

Responses

  • 200Schedule

    Updated

  • 400Error

    Invalid request, or the active-schedule limit reached

  • 401Error

    Missing, malformed, or revoked API key

  • 402Error

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 404Error

    Not found

  • 409Error

    Cannot resume: no occurrences left (invalid_state)

  • 429Error

    Rate limit or quota exceeded

Response Fields

  • idstring

    Example: sch_a1B2c3D4e5F6g7H8.

  • objectschedule
  • tostring
  • fromstring
  • bodystring
  • repeatScheduleRepeat
  • start_datestring (date)

    Nullable.

  • end_datestring (date)

    Nullable.

  • max_occurrencesinteger

    Nullable.

  • categorymarketing, transactional, otp, null

    Nullable.

  • quiet_hoursblock, defer, null

    Nullable.

  • activeboolean
  • statusactive, paused, completed
  • paused_reasonmanual, recipient_opted_out, repeated_failures, sender_unavailable, null

    Nullable.

  • next_run_atstring (date-time)

    The next occurrence (UTC). Null unless active. Nullable.

  • last_run_atstring (date-time)

    Nullable.

  • last_statussent, skipped_opted_out, skipped_missed, deferred, failed, null

    Nullable.

  • last_errorstring

    Why the last occurrence was skipped or failed. Nullable.

  • last_message_idstring

    Nullable.

  • countsobject
  • counts.sentinteger
  • counts.skippedinteger
  • counts.failedinteger
  • testboolean

    Made with a test key: only ever sends in the sandbox.

  • created_atstring (date-time)
  • updated_atstring (date-time)
  • recent_occurrencesarray of object

    Only on GET /schedules/{id}: the last 10 occurrences, newest first.

  • recent_occurrences[].datestring (date)

    The local calendar date of the occurrence.

  • recent_occurrences[].due_atstring (date-time)

    Nullable.

  • recent_occurrences[].statussent, skipped_opted_out, skipped_missed, deferred, failed
  • recent_occurrences[].message_idstring

    Nullable.

  • recent_occurrences[].errorstring

    Nullable.

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

  • 400

    Invalid request, or the active-schedule limit reached

  • 401

    Missing, malformed, or revoked API key

  • 402

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 404

    Not found

  • 409

    Cannot resume: no occurrences left (invalid_state)

  • 429

    Rate limit or quota exceeded