List outbound messagesMenu

List outbound messages

GET/v1/messages

Requires an API key with the messages:read scope. About keys and scopes

Works with integration, agent and partner keys.

Lists the workspace message log: one row per outbound message from campaigns, journeys and transactional sends, newest first, whether it was sent, is still queued, or was skipped or failed. campaign and journey say where a row came from (neither, for a transactional send), and bounce, failure or skip what became of it.

Filters. recipient matches the address a message was sent to, and also email messages not yet given one (queued, or skipped before sending) whose contact's current email is that address. Messages past the retention period name no one and match no recipient. query is a search: part of the recipient's address or name, matched against the contact each message went to. campaignId and journeyId narrow to one source, and stepId with journeyId to one step of the journey, in every version of its steps. templateId and correlationId narrow to transactional sends, from one stored template or carrying your own reference. opened and clicked split by engagement. createdAfter is inclusive and createdBefore exclusive. No total is returned.

Query parameters

limitintegeroptional

How many items a page holds: 1 to 100, 20 by default.

min > 0 · max 100 · default 20

cursorstringoptional

Where the page starts: the previous page's meta.pagination.nextCursor. Omit it for the first page, and send the same filters with it.

1–2,048 characters

statusstringoptional

Only messages in this status.

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

channelstringoptional

Only messages on this channel.

one of email, push

recipientstringoptional

The exact address the message went to.

querystringoptional

Part of the recipient's email address or name, matched against the contact the message went to.

1–100 characters

messageTypestringoptional

Only messages of this type: marketing or transactional.

one of marketing, transactional

campaignIdstringoptional

Only messages from this campaign.

uuid

journeyIdstringoptional

Only messages from this journey.

uuid

stepIdstringoptional

With journeyId, only messages from the journey's step with this id, in every version of its steps.

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

templateIdstringoptional

Only transactional sends from this stored template; no other message records one.

uuid

correlationIdstringoptional

Only the transactional sends that carried this correlationId.

1–255 characters

sentstringoptional

true: handed to the provider, whatever happened after; false: never sent (queued, failed before sending or skipped).

one of true, false

deliveredstringoptional

true: delivery was confirmed, even if a complaint or bounce came later; false: never confirmed.

one of true, false

bouncedstringoptional

true: a hard bounce was recorded, even if a complaint came later; false: none. A test send's acted-out bounce is no recorded bounce.

one of true, false

complainedstringoptional

true: a complaint was recorded; false: none. A test send's acted-out complaint is no recorded complaint.

one of true, false

openedstringoptional

true: opened (or clicked) at least once; false: never.

one of true, false

clickedstringoptional

true: a link clicked at least once; false: never.

one of true, false

createdAfterstringoptional

Only messages accepted at or after this time (inclusive).

date-time

createdBeforestringoptional

Only messages accepted before this time (exclusive).

date-time

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}$

Returns

Returns 200 OK with a list of OutboundMessage objects in data, and the next page's cursor in meta (see pagination). Otherwise returns an error; Errors lists every code and which to retry.

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

curl https://api.kirora.io/v1/messages \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/messages', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data, meta } = await response.json();
// meta.pagination.nextCursor is the next page's `cursor`, and null on the last page.

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
body = response.json()
data = body["data"]
next_cursor = body["meta"]["pagination"]["nextCursor"]
# next_cursor is the next page's `cursor`, and None on the last page.

package main

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

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/messages", 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"`
		Meta struct {
			Pagination struct {
				NextCursor *string `json:"nextCursor"`
			} `json:"pagination"`
		} `json:"meta"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
	// out.Meta.Pagination.NextCursor is the next page's `cursor`, and nil on the last page.
}

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

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.kirora.io/v1/messages");
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");
var nextCursor = document.RootElement.GetProperty("meta").GetProperty("pagination").GetProperty("nextCursor");
// nextCursor is the next page's `cursor`, and null on the last page.

Response · 200

{
  "data": [
    {
      "id": "0192f3b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "messageType": "marketing",
      "channel": "email",
      "status": "delivered",
      "campaign": {
        "id": "0192f3d3-5e6f-7071-8c83-9e0f1a2b3c4d",
        "name": "October newsletter"
      },
      "journey": null,
      "template": null,
      "copy": null,
      "contact": {
        "id": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
        "externalId": "customer-4821",
        "email": "[email protected]",
        "firstName": "Amaka",
        "lastName": "Obi"
      },
      "recipientEmail": "[email protected]",
      "simulated": false,
      "correlationId": null,
      "sendAt": null,
      "sentAt": "2026-10-01T09:31:00.000Z",
      "deliveredAt": "2026-10-01T09:31:04.000Z",
      "openedAt": "2026-10-01T10:02:00.000Z",
      "openedByMachine": false,
      "clickedAt": null,
      "clickedByMachine": false,
      "complainedAt": null,
      "bounce": null,
      "failure": null,
      "skip": null,
      "createdAt": "2026-10-01T09:30:58.000Z"
    },
    {
      "id": "0192f3b0-4d5e-7f60-8b72-8d9e0f1a2b3c",
      "messageType": "transactional",
      "channel": "email",
      "status": "bounced",
      "campaign": null,
      "journey": null,
      "template": {
        "id": "0192f3f2-3c4d-7e5f-8061-7c8d9e0f1a2b",
        "version": 3
      },
      "copy": null,
      "contact": {
        "id": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
        "externalId": "customer-4821",
        "email": "[email protected]",
        "firstName": "Amaka",
        "lastName": "Obi"
      },
      "recipientEmail": "[email protected]",
      "simulated": false,
      "correlationId": "order-1001",
      "sendAt": null,
      "sentAt": "2026-10-01T09:31:00.000Z",
      "deliveredAt": null,
      "openedAt": null,
      "openedByMachine": false,
      "clickedAt": null,
      "clickedByMachine": false,
      "complainedAt": null,
      "bounce": {
        "occurredAt": "2026-10-01T09:31:05.000Z",
        "type": "mailbox_not_found",
        "detail": "smtp; 550 5.1.1 user unknown"
      },
      "failure": null,
      "skip": null,
      "createdAt": "2026-10-01T09:30:58.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 20,
      "nextCursor": null
    }
  }
}