Docs
kirora.ioGet started
Messages overviewMenu
On this page

API reference

Messages

The message log holds every message Kirora sent or tried to send, from campaigns, journeys and transactional sends, with what became of it. One send to one contact on one channel is one message, so a campaign to 1,000 contacts is 1,000 messages. Export the log as CSV for analysis. See Message log and exports. A contact's messages: GET /v1/contacts/{id}/messages.

Endpoints

EndpointRequest
List outbound messagesGET /v1/messages
Retrieve an outbound messageGET /v1/messages/{id}
Retrieve a message's contentGET /v1/messages/{id}/content
List a push message's deliveriesGET /v1/messages/{id}/deliveries
Export sent messages as CSVPOST /v1/messages/exports
Retrieve a message exportGET /v1/messages/exports/{id}
Download a message exportGET /v1/messages/exports/{id}/download

The OutboundMessage object

OutboundMessage example
{
  "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"
}
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