Scheduled Sends

Schedule a text or an outbound call to one contact at a set time, then move, edit or cancel it before it goes out.

A scheduled send is one text or one outbound call to one contact at a set time: an appointment reminder, a follow-up the next morning, a callback. You create it now; ThunderPhone sends it when it comes due. One list holds every send, so you can look them up and cancel them in one place.

• Texts go out through /v1/sms rules: an active, SMS-capable number on your connected Twilio or Telnyx account.
• Calls are placed like POST /v1/call with a saved agent, and need the same outbound-enabled from_number and TCPA confirmation.
• A send is checked when you create it, so you hear about a problem at once, and checked again when it comes due.
• Nothing is sent late. A send that cannot go out before its expires_at is skipped, never sent afterwards.
• Every send honors your organization's opt-out list.

Endpoints#

Authenticate with an organization API key. These endpoints are not available to OAuth clients. In a dashboard session any member can schedule texts, and scheduling or editing a call requires an admin or owner, the same as POST /v1/call; organization API keys are not limited by role.

Scheduled send object#

{
  "id": "6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3",
  "type": "sms",
  "status": "scheduled",
  "status_reason": "",
  "status_detail": "",
  "send_at": "2026-11-03T17:00:00Z",
  "expires_at": "2026-11-03T17:30:00Z",
  "from_number": "+15551234567",
  "to": "+14155550199",
  "body": "Hi {{name}}, a reminder of your appointment tomorrow at {{time}}.",
  "agent_id": null,
  "variables": {"name": "Ada", "time": "10:30 AM"},
  "context": "",
  "timezone": "America/Los_Angeles",
  "allow_quiet_hours": false,
  "external_id": "appointment-4815",
  "source": "api",
  "source_call_id": null,
  "consent": {"type": "customer_attests"},
  "simulated": false,
  "sms_message_id": null,
  "call_id": null,
  "sent_at": null,
  "created_at": "2026-11-01T18:02:11.204Z",
  "updated_at": "2026-11-01T18:02:11.204Z"
}

Statuses#

skipped reasons:

A send that ends skipped or failed fires the scheduled.skipped or scheduled.failed webhook. A sent text fires the usual sms.* events with scheduled_send_id set; a placed call fires the usual call events, and its telephony.complete event carries scheduled_send_id.

Schedule a send#

curl -X POST https://api.thunderphone.com/v1/scheduled \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "send_at": "2026-11-03T09:00:00-08:00",
    "from_number": "+15551234567",
    "to": "+14155550199",
    "body": "Hi {{name}}, a reminder of your appointment tomorrow at {{time}}.",
    "variables": {"name": "Ada", "time": "10:30 AM"},
    "external_id": "appointment-4815",
    "idempotency_key": "appointment-4815-reminder"
  }'

curl -X POST https://api.thunderphone.com/v1/scheduled \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "call",
    "send_at": "2026-11-03T10:00:00-08:00",
    "from_number": "+15551234567",
    "to": "+14155550199",
    "agent_id": 12,
    "variables": {"name": "Ada"},
    "context": "Ada asked for a call back about rescheduling her appointment.",
    "external_id": "appointment-4815"
  }'

Returns 201 Created with the send. A send created with problems you should know about has a warnings array of {"code", "message"}:

Quiet hours#

Texts and calls go out only between 8am and 9pm in the recipient's time zone. The zone comes from the recipient's number, else the agent's timezone, else your organization's. A send_at outside those hours is refused with quiet_hours and the next allowed time:

{
  "error": {
    "code": "quiet_hours",
    "message": "send_at is outside 8am to 9pm in the recipient's time zone (America/Los_Angeles). The next allowed time is next_allowed_at. To send anyway, pass allow_quiet_hours: true; your organization then takes responsibility for the timing.",
    "next_allowed_at": "2026-11-03T16:00:00+00:00",
    "timezone": "America/Los_Angeles"
  }
}

Pass allow_quiet_hours: true to send at that time anyway; your organization takes responsibility for the timing. When no zone can be found, the send is created with a timezone_unknown warning instead. Quiet hours are checked again when the send comes due: a send held up past 9pm is skipped with quiet_hours rather than sent late at night.

Texts#

• Templates. The body is stored as written and filled from variables when the text goes out, so a moved appointment needs only a PATCH of send_at or variables.
• Opt-out line. The first text your organization sends a number gets "Reply STOP to opt out." added on a new line. A body that already contains the word STOP in capitals is sent as written, and later texts to the same number are not changed. The body's length is checked with that line included.
• Pacing. Scheduled texts share your organization's text rate (30 a minute by default) with /v1/sms, agent tools and follow-ups. Sends are checked every minute; when more texts are due than the rate allows, the rest wait for the next minute, oldest send_at first, until their expires_at.
• A scheduled text is not counted against a call's three-text limit.

Calls#

A scheduled call is placed like POST /v1/call with agent_id, variables and context, under the same checks: blocked destinations, balance and call limits. A call held back by your concurrent-call, same-number or daily limit stays queued and is tried again the next minute until its expires_at. If the agent is deleted before the call is due, the send fails with agent_deleted.

Limits#

• send_at at most 90 days ahead.
• expires_at after send_at and at most 24 hours after it.
• At most 10,000 pending (scheduled or sending) sends per organization.

Idempotency#

Send an idempotency_key to make retries safe. Repeating a request with the same key and the same fields returns the original send with 200 OK and creates nothing. The same key with different fields returns 409 idempotency_conflict.

Errors#

Errors have the shape {"error": {"code", "message"}}. A field that is missing or the wrong type returns 400 with that field's error instead, such as {"send_at": ["This field is required."]}.

List scheduled sends#

curl 'https://api.thunderphone.com/v1/scheduled?external_id=appointment-4815&status=scheduled,sending' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "count": 1,
  "results": [ { "id": "6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3", "type": "sms", "status": "scheduled", "...": "..." } ]
}

Retrieve a scheduled send#

curl https://api.thunderphone.com/v1/scheduled/6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns the send, or 404 not_found when the id is not in your organization.

Move or edit a send#

curl -X PATCH https://api.thunderphone.com/v1/scheduled/6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "send_at": "2026-11-04T09:00:00-08:00",
    "variables": {"name": "Ada", "time": "9:00 AM"}
  }'

You can change send_at, expires_at, body (texts), variables, context (calls) and allow_quiet_hours while the send is scheduled. Other fields are ignored: to change to, from_number or the agent, cancel the send and create a new one. Moving send_at without expires_at keeps the deadline the same time after it. The same time, quiet-hours and body checks as creation apply, and the response can carry warnings. A send that is no longer scheduled returns 409 not_editable.

Cancel a send#

curl -X DELETE https://api.thunderphone.com/v1/scheduled/6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns the send with status: "canceled". Canceling a canceled send is a no-op. A send that is already sending or finished returns 409 not_cancelable.

Cancel by external_id or number#

curl -X POST https://api.thunderphone.com/v1/scheduled/cancel \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "appointment-4815"}'

Cancels every scheduled send that matches. Send external_id, to, or both; add type (sms or call) to cancel only texts or only calls. Sends already going out are not affected.

{ "canceled": 2 }