Canceling a Scheduled Message

DELETE /api/v1/emails/{id} or /api/v1/sms/{id}

Flips a scheduled message to canceled so the cron skips it.

Response — 200

{ "id": "msg_...", "status": "canceled" }

Errors

• 404 NOT_FOUND — unknown ID or not owned by caller's org.
• 409 NOT_SCHEDULED — message is already in a terminal or active state. The error message includes the current status so the caller can decide whether to ignore or retry.

  { "error": { "type": "validation_error", "message": "Only scheduled messages can be canceled (current status: sent)", "code": "NOT_SCHEDULED" } }
  

Semantics

• Canceling is safe to call concurrently — the second call returns 409 if the first already ran, or no-op if the cron already picked it up.
• canceled is a terminal status. Does not fire any webhook event.
• Usage is not incremented for canceled messages.
• Idempotency keys from the original schedule request are not reused on cancel.

When to call

• User action in your UI.
• Downstream event invalidates the send (customer unsubscribed between schedule and send).
• Cleanup on a test flow that produced stale schedules.