Cancel a scheduled transactional messageMenu

Cancel a scheduled transactional message

POST/v1/transactional/messages/{id}/cancel

Requires an API key with the transactional:send scope. About keys and scopes

Works with integration and partner keys, not agent keys.

Safe to retry: a repeat returns the current state, or 409 once it has moved on from it. About idempotency

Stops a message sent with sendAt before it goes: it becomes skipped with skip.reason cancelled, its email or push goes back to the plan allowance, and message.skipped is published. Cancelling an email also cancels its cc and bcc copies. Cancelling it again answers 200 with the message as it is. Once a worker has started sending it, or it went at once, the response is 409 CONFLICT. Agent keys are refused with 403.

Path parameters

idstringrequired

The message's id.

uuid

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Idempotency-Keystringoptional

Makes a retry safe: a repeat with the same key and body within 24 hours gets the first response again, with Idempotency-Replay: true. The same key with another request is 409 IDEMPOTENCY_KEY_REUSED; while the first is still running, 409 IDEMPOTENCY_KEY_IN_USE; after an unsafe first request failed or never returned, 409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN. Use a new key, such as a UUID, for each new request.

8–255 characters

Returns

Returns 200 OK with an OutboundMessage in data. It can also return 409 Conflict; see the statuses below. Otherwise returns an error; Errors lists every code and which to retry.

200 OKThe message, cancelled.
409 ConflictThe request conflicts with current state — a duplicate unique value, or a resource whose status does not allow this operation.

idstringrequired

uuid

messageTypestringrequired

marketing (from campaign or journey) or transactional (neither).

one of marketing, transactional

channelstringrequired

one of email, push

statusstringrequired

one of queued, sending, skipped, sent, failed, delivered, bounced, complained

campaignobject | nullrequired

The campaign it came from; null for any other message.

2 child attributes

idstringrequired: uuid
namestringrequired: The campaign's current name.

journeyobject | nullrequired

The journey it came from, deleted or not; null for any other message.

5 child attributes

idstring | nullrequired

Null once the journey is deleted.

uuid

namestring | nullrequired

The journey's current name; null once it is deleted.

deletedbooleanrequired

The journey was deleted after sending this. Its messages and their counts stay; nothing names the journey any more.

enrollmentIdstringrequired

The enrollment that sent it.

uuid

stepIdstringrequired

The id of the step that sent it.

templateobject | nullrequired

The stored template and published version it was sent from; null for inline content.

2 child attributes

idstringrequired: uuid
versionintegerrequired: min > 0

copyobject | nullrequired

Set on a cc or bcc copy; null on the message itself.

2 child attributes

kindstringrequired

one of cc, bcc

ofstringrequired

The message it is a copy of.

uuid

contactobject | nullrequired

Who it was for; null when the contact was deleted, or the message passed the retention period: it no longer names anyone.

5 child attributes

idstringrequired: uuid
externalIdstring | nullrequired
emailstring | nullrequired: The contact's email now, which may differ from recipientEmail.
firstNamestring | nullrequired: The contact's first name now.
lastNamestring | nullrequired: The contact's last name now.

recipientEmailstring | nullrequired

The email address the message went to, frozen at the first attempt; null until then, and for push.

simulatedbooleanrequired

Sent to a reserved test address (example.com and the like): it passed every check a real send does but was never handed to the provider. Any outcome was simulated from the address, as [email protected] simulates a bounce.

correlationIdstring | nullrequired

The reference a transactional send carried; null otherwise.

sendAtstring | nullrequired

When a timed transactional send is due; null for one sent at once.

date-time

sentAtstring | nullrequired

When it was handed to the provider.

date-time

deliveredAtstring | nullrequired

When the provider confirmed delivery.

date-time

openedAtstring | nullrequired

First open, when tracked: a person's first open or click, or a machine's open while only a machine has opened it.

date-time

openedByMachinebooleanrequired

Only a machine has opened it so far: a mail app fetched its images with no reader (Apple Mail Privacy Protection, Gmail's prefetch on delivery) or a mail security scanner checked it. A click or a later open by a person clears it.

clickedAtstring | nullrequired

A person's first click, when tracked.

date-time

clickedByMachinebooleanrequired

A machine followed one of its links: a mail security scanner checking it on delivery, a link preview. Such a click sets no clickedAt and sends no webhook.

complainedAtstring | nullrequired

When the recipient marked it as spam (the first complaint); null for a simulated one.

date-time

bounceobject | nullrequired

The hard bounce: set when status is bounced; null otherwise. A soft bounce is a failure with reason transient_bounce.

3 child attributes

occurredAtstringrequired

When it happened.

date-time

typestringrequired

Why: mailbox_not_found, mailbox_full, suppressed (the provider refuses the address), or general for any other reason.

one of mailbox_not_found, mailbox_full, suppressed, general

detailstring | nullrequired

The receiving server's reply, such as smtp; 550 5.1.1 user unknown; null for a simulated bounce.

failureobject | nullrequired

Set when status is failed; null otherwise.

2 child attributes

occurredAtstringrequired

When it happened.

date-time

reasonstringrequired

Why sending broke, such as provider_rejected (the provider refused the content) or transient_bounce. not_sent: a problem on Kirora's side stopped it; nothing in your content, audience or setup caused it, and Kirora is alerted. In rare cases the provider may have delivered it before the problem.

skipobject | nullrequired

Set when status is skipped; null otherwise.

3 child attributes

occurredAtstringrequired

When it happened.

date-time

reasonstringrequired

Which guard stopped it before sending, such as suppressed, consent_missing or cancelled; fallback_not_needed: a transactional fallbackOrder fallback whose first channel arrived; plan_limit_reached: a fallback the plan had no room for when it was due; sending_review_required: email from a sending domain Kirora has not approved yet.

suppressionReasonstring | nullrequired

With suppressed: why the address is blocked: unsubscribed, bounced, complained, complained_transactional, manual or imported. Null otherwise.

one of manual, imported, unsubscribed, bounced, complained, complained_transactional

createdAtstringrequired

date-time

Headers on `200 OK`

Idempotency-Replaystringoptional

true when this is the stored response to an earlier request with the same key.

one of true

curl -X POST https://api.kirora.io/v1/transactional/messages/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/cancel \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/transactional/messages/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/transactional/messages/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/transactional/messages/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/cancel", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.kirora.io/v1/transactional/messages/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/cancel");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 200

{
  "data": {
    "copy": null,
    "id": "0192f3b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "messageType": "transactional",
    "channel": "email",
    "status": "skipped",
    "campaign": null,
    "journey": null,
    "template": null,
    "contact": {
      "id": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
      "externalId": "customer-4821",
      "email": "[email protected]",
      "firstName": "Amaka",
      "lastName": "Obi"
    },
    "recipientEmail": null,
    "simulated": false,
    "correlationId": "class-3315",
    "sendAt": "2026-10-01T10:00:00.000Z",
    "sentAt": null,
    "deliveredAt": null,
    "openedAt": null,
    "openedByMachine": false,
    "clickedAt": null,
    "clickedByMachine": false,
    "complainedAt": null,
    "bounce": null,
    "failure": null,
    "skip": {
      "occurredAt": "2026-10-01T09:45:00.000Z",
      "reason": "cancelled",
      "suppressionReason": null
    },
    "createdAt": "2026-10-01T09:30:00.000Z"
  }
}

Cancel a scheduled transactional message

Path parameters

Header parameters

Returns

Headers on 200 OK

Headers on `200 OK`