Messages

List sent messages across every source

GET/v1/messages/deliveries

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

The workspace send log: one row per message from campaigns, journeys, transactional sends and the push API, newest first. campaignId, journeyEnrollmentId and messageType say where a row came from. 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. q is a search: part of the recipient's address or name, matched against the contact each message went to. createdAfter is inclusive and createdBefore exclusive. No total is returned. Each row has its source's name (sourceName), journeyId, and failureReason when it failed or was skipped.

Query parameters

limitintegeroptional

min > 0 · max 100 · default 20

cursorstringoptional

1–2048 characters

statusstringoptional

Only messages in this status.

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

channelstringoptional

one of email, push

recipientstringoptional

The exact address the message went to.

qstringoptional

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, such as campaign or transactional.

one of marketing, transactional

createdAfterstringoptional

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

date-time

createdBeforestringoptional

Only messages accepted before this time (exclusive).

date-time

Returns

Returns 200 OK with a list of SentMessage 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

contactIdstring | nullrequired

Null when the contact was erased, or the message passed the retention period: the message no longer names anyone.

uuid

currentContactEmailstring | nullrequired

The contact's email now, which may differ from recipientAddress.

recipientAddressstring | nullrequired

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

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 bounce@example.com simulates a bounce.

campaignIdstring | nullrequired

The campaign it came from, if any.

uuid

journeyIdstring | nullrequired

The journey it came from, if any.

uuid

journeyEnrollmentIdstring | nullrequired

The journey enrollment it came from, if any.

uuid

journeyStepIndexinteger | nullrequired

Position of the journey step that sent it, if any.

min -9007199254740991 · max 9007199254740991

sourceNamestring | nullrequired

The campaign's or journey's name; null for a transactional send.

messageTypestringrequired

one of marketing, transactional

channelstringrequired

one of email, push

statusstringrequired

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

failureReasonstring | nullrequired

Why it failed, bounced or was skipped, e.g. suppressed, consent_missing.

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

failedAtstring | nullrequired

When it failed, bounced or was skipped (a cancelled send included).

date-time

openedAtstring | nullrequired

First open, when tracked.

date-time

clickedAtstring | nullrequired

First click, when tracked.

date-time

createdAtstringrequired

date-time

templateobject | nullrequired

The stored template and published version it was sent from; null for inline content. Messages sent before template versions carry version: null.

2 child attributes

idstringrequired: uuid
versioninteger | nullrequired: min > 0 · max 9007199254740991

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

const response = await fetch('https://api.kirora.io/v1/messages/deliveries', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/messages/deliveries",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
data = response.json()["data"]

package main

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

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/messages/deliveries", 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()

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

Response · 200

{
  "data": [
    {
      "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
      "contactId": "018f2a4e-6b1c-7d3e-9f40-4db757ce5a6b",
      "currentContactEmail": "currentContactEmail_example",
      "recipientAddress": "recipientAddress_example",
      "simulated": true,
      "campaignId": "018f2a4e-6b1c-7d3e-9f40-3478765e5a6b",
      "journeyId": "018f2a4e-6b1c-7d3e-9f40-7cf2bf7e5a6b",
      "journeyEnrollmentId": "018f2a4e-6b1c-7d3e-9f40-eb556d965a6b",
      "journeyStepIndex": -9007199254740991,
      "sourceName": "sourceName_example",
      "messageType": "marketing",
      "channel": "email",
      "status": "queued",
      "failureReason": "failureReason_example",
      "correlationId": "order-1001",
      "sendAt": "2030-03-14T09:30:00Z",
      "sentAt": "2030-03-14T09:30:00Z",
      "deliveredAt": "2030-03-14T09:30:00Z",
      "failedAt": "2030-03-14T09:30:00Z",
      "openedAt": "2030-03-14T09:30:00Z",
      "clickedAt": "2030-03-14T09:30:00Z",
      "createdAt": "2030-03-14T09:30:00Z",
      "template": {
        "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
        "version": 1
      }
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    }
  }
}

Example values are generated from the schema.