Contacts

List a contact's messages

GET/v1/contacts/{id}/messages

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

Every message sent or attempted to this contact, from any source, newest first, with its outcome. Filter by status, channel or messageType.

Path parameters

idstringrequired: uuid

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

messageTypestringoptional

Only messages of this type, such as campaign or transactional.

one of marketing, transactional

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/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/messages \
  -H "Authorization: Bearer $KIRORA_API_KEY"

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