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
  scheduled (waiting), sending (going out now; it can no longer be cancelled), sent, cancelled or failed.
- modestringlive | test
  test when a test API key scheduled this message: when it is due it is stored in your Sandbox, never delivered. Otherwise live.
- send_atstring
  When it will be sent, to the minute.
- 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 was sent with. Null until it is sent, and for a cancelled or failed message.
- 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. Set only when status is failed. Suppression and rate limits are checked when the message is sent, not when it was scheduled.
- 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.