Campaigns

List campaign messages

GET/v1/campaigns/{id}/messages

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

Delivery records for one campaign — one per contact per channel — including status and any provider failure reason. Filter with channel to see one channel. Results are cursor-paginated: pass meta.pagination.nextCursor back as cursor until it comes back null. The cursor is opaque — do not construct or parse one.

Path parameters

idstringrequired: uuid

Query parameters

limitintegeroptional

min > 0 · max 100 · default 20

cursorstringoptional

1–2048 characters

channelstringoptional

Only this channel; a multi-channel campaign lists one row per contact per channel.

one of email, push

statusstringoptional

Only messages in this status.

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

emailstringoptional

Part of the recipient's address, case-insensitive.

1–320 characters

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

Returns

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

recipientAddressstring | nullrequired

The email address it went to; null for a push message.

channelstringrequired

one of email, push

statusstringrequired

Where the message is in delivery.

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

failureReasonstring | nullrequired

Why it failed or was skipped, if it did.

sentAtstring | nullrequired

When it was handed to the provider.

date-time

deliveredAtstring | nullrequired

When delivery was confirmed.

date-time

failedAtstring | nullrequired

When it failed.

date-time

openedAtstring | nullrequired

When it was first opened.

date-time

clickedAtstring | nullrequired

When a link was first clicked.

date-time

createdAtstringrequired

date-time

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

const response = await fetch('https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/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/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/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/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/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",
      "recipientAddress": "amaka@juniperkitchen.com",
      "channel": "email",
      "status": "queued",
      "failureReason": "failureReason_example",
      "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"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    }
  }
}

Example values are generated from the schema.