Transactional

List transactional messages

GET/v1/transactional/messages

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

Transactional sends, newest first, with their outcome. Narrow to one contact with contactId, to the address a message went to with recipient (or part of the contact's address or name with q), to your own reference with correlationId, or to one stored template with templateId. createdAfter (inclusive) and createdBefore (exclusive) bound when the API accepted the send: with the transactional report's currentPeriod and channel=email, the list is exactly what the report counts.

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

contactIdstringoptional

Only messages to this contact.

uuid

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

correlationIdstringoptional

The correlationId the send carried.

1–255 characters

templateIdstringoptional

Only messages sent from this stored template.

uuid

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/transactional/messages \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/transactional/messages', {
  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/transactional/messages",
    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/transactional/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()

	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.