Cancel a scheduled message

DELETE/api/v1/messages/scheduled/{scheduled}

Requires anorganization API keywith the scopemessages:send

Stops a message that has not been sent.

Only while its status is scheduled. Once the sweep has claimed it — status sending — the message may already be on the wire, and there is no such thing as unsending. The cancel is then refused with a message naming the state it is actually in and, for one already sent, when it went. A success you could not act on would be worse than a refusal.

The cancel and the sweep are the same conditional update on one row, so exactly one of them can win. You are never told a message was cancelled when it was not.

Parameters

Name	In	Type	Description
`scheduled`required	path	string	The scheduled identifier.

Request

DELETE/api/v1/messages/scheduled/{scheduled}

curl -X DELETE 'https://app.mailyte.com/api/v1/messages/scheduled/01JBT8XQ2M9WYC3K4F6R7S8T9V' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY'

const response = await fetch('https://app.mailyte.com/api/v1/messages/scheduled/01JBT8XQ2M9WYC3K4F6R7S8T9V', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
  },
});
const { data } = await response.json();

import requests
response = requests.delete(
    "https://app.mailyte.com/api/v1/messages/scheduled/01JBT8XQ2M9WYC3K4F6R7S8T9V",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->delete('https://app.mailyte.com/api/v1/messages/scheduled/01JBT8XQ2M9WYC3K4F6R7S8T9V');

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/messages/scheduled/01JBT8XQ2M9WYC3K4F6R7S8T9V")
request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

The key names its own organization, so no X-Organization-ID header is needed.

Response

200 with the `scheduled_message`, now `cancelled`. 422 if it is too late, naming the state it is in. 404 if it is not yours.

dataobject
A message accepted now and submitted at `send_at`. It is not a `message`: a message has left, and this has not. Once it goes, `message_id` names the message it became.
- objectstringscheduled_message
- idstring
  Address this with `GET` and `DELETE /messages/scheduled/{id}`. It identifies the SCHEDULE, not the message — see `message_id`.
- statusstringscheduled | sending | sent | cancelled | failed
  One of: `scheduled` (waiting), `sending` (claimed for submission — the window in which cancelling is no longer possible), `sent`, `cancelled`, `failed`.
- modestringlive | test
  `test` when a test key accepted this message: it runs the whole flow — validation, scheduling, listing, cancelling — and submits nothing when it comes due. Captured when the message is accepted, not when it is sent, because test mode is a property of the KEY and the sweep has no key to read. `live` is the default.
- send_atstring
  When it is due. Honoured to the minute — we refuse a `send_at` less than 60 seconds out rather than promise a precision we do not have.
- fromstring
  The sender, as scheduled.
- toarray<string>
  The recipients, as scheduled. `cc` and `bcc` are held but not published back — a Bcc that reappears in a readable response is a Bcc that leaked.
- subjectstring
  `null` MEANS NONE WAS SET — a message may legitimately have no subject, and a template supplies its own at render time.
- message_idstring
  The Message-ID it got when it left, for following it into the delivery log. `null` MEANS IT HAS NOT LEFT — still scheduled, cancelled, or failed. Never a placeholder.
- sent_atstring
  When it was submitted. `null` MEANS IT HAS NOT BEEN.
- cancelled_atstring
  When it was cancelled. `null` MEANS IT WAS NOT.
- failure_reasonstring
  Why it could not be sent, in words. `null` MEANS NOTHING WENT WRONG — not that the reason is unknown. Only a `failed` row carries one. Suppression and rate limits are evaluated when the message leaves, not when it was accepted, so a message scheduled on Monday for somebody who unsubscribes on Tuesday fails here and says so.
- created_atstring
  When it was accepted.

Returned inside the standard envelope.

Errors

Status	When
`401`	The API key is missing, unknown, revoked or expired. All four answer identically, on purpose: distinguishing them would confirm which keys exist.
`403`	The key is valid but may not do this: it lacks the required scope, its IP allowlist does not include you, or this endpoint does not accept API keys.
`404`	No such resource in this organization.
`422`	The request was understood but the values were not acceptable.
`429`	Too many requests, or the organization has spent its sending allowance. `Retry-After` says how long to wait.

Every status, with what causes it and what to do, is on the error reference.