Skip to main content
The Schedule API lets you queue messages to be sent at a specific time in the future. You can schedule messages to individuals, groups, or entire contact lists, giving you precise control over when your customers receive communications.

​
The Scheduled object

​
id
integer
Unique identifier for the scheduled message.
​
execute
string
RFC 3339 timestamp for when the message will be sent.
​
inbox_id
integer
The inbox the message will be sent from.
​
local_id
string
Client-provided unique identifier.
​
meta
object
Metadata about the scheduled send.
​
created
string
ISO 8601 timestamp when the schedule was created.
​
updated
string
ISO 8601 timestamp when the schedule was last updated.

​
ScheduledContent

​
text
string
Message body text.
​
template
object
Template reference to use instead of inline text.
​
to
string
Recipient phone number in E.164 format without the leading +.
​
attachments
object[]
File attachments to include with the message.
​
gallery
object[]
Array of GalleryEntry image objects to include.

​
Create a scheduled message

POST /v1/schedule
​
inbox_id
integer
required
The inbox to send the message from.
​
execute_at
string
required
RFC 3339 timestamp for when to send the message. Must be at least 15 minutes in the future and aligned to a 15-minute interval (e.g., :00, :15, :30, :45).
​
content
object
required
A ScheduledContent object with text, to, template, attachments, and/or gallery.
​
phone_number
string
Recipient phone number in E.164 format without the leading +. Use for individual recipients.
​
targets
object[]
Array of recipient targets for group MMS sends.
​
conversation_id
integer
Send into an existing conversation.
​
list_id
integer
Contact list ID for broadcast scheduling.
​
local_id
string
Client-provided unique identifier for this scheduled send.
​
user_id
integer
ID of the team member to send as. Defaults to the team owner if omitted.
curl --request POST \
  --url https://api.heymarket.com/v1/schedule \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "local_id": "f4bb74f2-7827-4a61-83c1-04164338fb6f",
    "content": {
      "text": "Your appointment is tomorrow at 2pm",
      "to": "14155553434"
    },
    "phone_number": "14155553434",
    "inbox_id": 413,
    "execute_at": "2024-07-24T11:30:00-07:00"
  }'

{
  "id": 88,
  "local_id": "f4bb74f2-7827-4a61-83c1-04164338fb6f"
}
execute_at must be at least 15 minutes in the future and must fall on a 15-minute interval (:00, :15, :30, or :45). Requests that do not meet these constraints will be rejected.

​
Get a scheduled message

GET /v1/schedule/{id}
​
id
integer
required
The ID of the scheduled message to retrieve.
curl --request GET \
  --url https://api.heymarket.com/v1/schedule/88 \
  --header 'Authorization: Bearer YOUR_API_KEY'

​
Update a scheduled message

PUT /v1/schedule/{id} Accepts the same body as the create endpoint. Use this to change the send time or update the message content before it is sent.
​
id
integer
required
The ID of the scheduled message to update.
curl --request PUT \
  --url https://api.heymarket.com/v1/schedule/88 \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "execute_at": "2024-07-24T12:00:00-07:00",
    "content": {
      "text": "Your appointment is tomorrow at 2pm. Reply STOP to opt out.",
      "to": "14155553434"
    },
    "inbox_id": 413
  }'

​
Delete a scheduled message

DELETE /v1/schedule/{id} Cancels and removes the scheduled message.
​
id
integer
required
The ID of the scheduled message to cancel.
curl --request DELETE \
  --url https://api.heymarket.com/v1/schedule/88 \
  --header 'Authorization: Bearer YOUR_API_KEY'

"ok"