Scheduled

Scheduled sends are emails queued for future delivery, typically created by sequence steps with delays. Use this API to view what emails are pending and when they will be sent.

List scheduled sends

GET /api/scheduled

Returns scheduled sends for the tenant. You must supply either a status or a contactId filter — an unfiltered request returns a VALIDATION_ERROR. Results are returned as an items array with a hasMore boolean (this endpoint does not use a cursor).

Query parameters

Parameter	Type	Default	Description
`status`	string	—	Filter by status: `pending`, `claimed`, `sent`, `cancelled`, `failed`, or `dead`. Required unless `contactId` is given.
`contactId`	string	—	Return scheduled sends for a single contact. Required unless `status` is given.
`limit`	number	20	Number of scheduled sends to return (max 100).
`cancelReason`	string	—	When listing `cancelled` sends, keep only those with this cancel reason.

Response

{
  "items": [
    {
      "scheduledSendId": "01H9...",
      "contactId": "cnt_01H8MZXK...",
      "sequenceId": "onboarding",
      "sequenceVersion": "01H8...",
      "stepId": "getting-started",
      "templateId": "getting-started",
      "scheduledFor": "2025-09-16T14:00:00.000Z",
      "status": "pending",
      "attempts": 0,
      "createdAt": "2025-09-15T14:00:00.000Z"
    }
  ],
  "hasMore": false
}

Response fields

Field	Type	Description
`scheduledSendId`	string	Unique identifier for the scheduled send.
`contactId`	string	The contact who will receive the email.
`sequenceId`	string	The sequence that created this scheduled send.
`sequenceVersion`	string	The sequence version the send was scheduled from.
`stepId`	string	The step within the sequence.
`templateId`	string	The template that will be rendered.
`scheduledFor`	string	ISO 8601 timestamp of when the email will be sent.
`status`	string	`pending`, `claimed`, `sent`, `cancelled`, `failed`, or `dead`.
`attempts`	number	Number of delivery attempts made so far.
`createdAt`	string	When the scheduled send was created.

Cancelled sends also carry a cancelReason; failed and dead sends carry a lastError.

Examples

# By status
curl "https://api.kraiter.com/api/scheduled?status=pending&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# By contact
curl "https://api.kraiter.com/api/scheduled?contactId=cnt_01H8MZXK..." \
  -H "Authorization: Bearer YOUR_API_KEY"

const scheduled = await kraiter.scheduled.list({ status: "pending", limit: 20 });

for (const item of scheduled.items) {
  console.log(
    `${item.contactId} — ${item.templateId} scheduled for ${item.scheduledFor}`
  );
}

Get scheduled send

GET /api/scheduled/:id

Returns the details of a single scheduled send. Because scheduled sends are keyed by their delivery time, you must pass the scheduledFor timestamp as a query parameter.

Path parameters

Parameter	Type	Description
`id`	string	The scheduled send ID (`scheduledSendId`).

Query parameters

Parameter	Type	Required	Description
`scheduledFor`	string	Yes	The ISO 8601 `scheduledFor` timestamp of the send, needed to locate the record.

Response

Returns the full scheduled send object (same fields as the list response).

{
  "scheduledSendId": "01H9...",
  "contactId": "cnt_01H8MZXK...",
  "sequenceId": "onboarding",
  "sequenceVersion": "01H8...",
  "stepId": "getting-started",
  "templateId": "getting-started",
  "scheduledFor": "2025-09-16T14:00:00.000Z",
  "status": "pending",
  "attempts": 0,
  "createdAt": "2025-09-15T14:00:00.000Z"
}

Errors

Code	Description
`VALIDATION_ERROR`	The `scheduledFor` query parameter was not provided.
`SCHEDULED_SEND_NOT_FOUND`	No scheduled send matches this ID and `scheduledFor`.

Examples

curl "https://api.kraiter.com/api/scheduled/01H9...?scheduledFor=2025-09-16T14:00:00.000Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

const item = await kraiter.scheduled.get("01H9...", {
  scheduledFor: "2025-09-16T14:00:00.000Z",
});
console.log(`Scheduled for: ${item.scheduledFor}`);

Lifecycle of a scheduled send

Scheduled sends follow this lifecycle:

Created — A sequence step creates the scheduled send with a future scheduledFor timestamp.
Pending — The send remains in the scheduled queue until its delivery time.
Sent — At the scheduled time, the email is rendered and delivered. The scheduled record is removed and a Send record is created.
Cancelled — If the contact is deleted, unsubscribes, or the sequence is deleted, the scheduled send is removed without sending.

Once a scheduled send has been delivered or cancelled, it no longer appears in the scheduled sends list. To view delivered emails, use the Sends API.

Viewing scheduled sends for a contact

To see what emails are pending for a specific contact, use the contact's scheduled sends endpoint:

curl "https://api.kraiter.com/api/contacts/cnt_01H8MZXK.../scheduled" \
  -H "Authorization: Bearer YOUR_API_KEY"

const scheduled = await kraiter.contacts.listScheduled("cnt_01H8MZXK...");

See Contacts — List scheduled sends for details.

Scheduled

On this page