Messages

Export sent messages as CSV

POST/v1/messages/exports

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

Queues a CSV of the send log. The body takes the filters of GET /v1/messages/deliveries (status, channel, recipient, messageType, createdAfter, createdBefore) and applies them the same way; send {} for every message. A filter matching no message is refused with NOTHING_TO_EXPORT. The file is generated in the background: poll the export until status is ready, then download it. Any key of the workspace with messages:read can read the export.

Request body

statusstringoptional

Only messages in this status.

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

channelstringoptional

Only messages on this channel.

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 202 Accepted with a MessageExport in data. Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired

uuid

statusstringrequired

queued, generating, then ready or failed; expired once the file is deleted.

one of queued, generating, ready, failed, expired

rowCountinteger | nullrequired

Rows in the file, once it is ready.

min -9007199254740991 · max 9007199254740991

filtersMessageExportFiltersrequired

The filters the export was created with.

7 child attributes

statusstringoptional

Only messages in this status.

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

channelstringoptional

Only messages on this channel.

one of email, push

recipientstringoptional

The exact address the message went to.

email · up to 320 characters

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

createdAtstringrequired

date-time

completedAtstring | nullrequired

date-time

expiresAtstring | nullrequired

When the file is deleted; the export then reads expired.

date-time

failureCodestring | nullrequired

EXPORT_TOO_LARGE or GENERATION_FAILED when status is failed.

curl -X POST https://api.kirora.io/v1/messages/exports \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "queued",
    "channel": "email",
    "recipient": "recipient_example",
    "q": "q_example",
    "messageType": "marketing",
    "createdAfter": "2030-03-14T09:30:00Z",
    "createdBefore": "2030-03-14T09:30:00Z"
  }'

const response = await fetch('https://api.kirora.io/v1/messages/exports', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "queued",
    "channel": "email",
    "recipient": "recipient_example",
    "q": "q_example",
    "messageType": "marketing",
    "createdAfter": "2030-03-14T09:30:00Z",
    "createdBefore": "2030-03-14T09:30:00Z"
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/messages/exports",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "status": "queued",
        "channel": "email",
        "recipient": "recipient_example",
        "q": "q_example",
        "messageType": "marketing",
        "createdAfter": "2030-03-14T09:30:00Z",
        "createdBefore": "2030-03-14T09:30:00Z",
    },
)
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "status": "queued",
	  "channel": "email",
	  "recipient": "recipient_example",
	  "q": "q_example",
	  "messageType": "marketing",
	  "createdAfter": "2030-03-14T09:30:00Z",
	  "createdBefore": "2030-03-14T09:30:00Z"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/messages/exports", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	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 · 202

{
  "data": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "status": "queued",
    "rowCount": -9007199254740991,
    "filters": {},
    "createdAt": "2030-03-14T09:30:00Z",
    "completedAt": "2030-03-14T09:30:00Z",
    "expiresAt": "2030-03-14T09:30:00Z",
    "failureCode": "failureCode_example"
  }
}

Example values are generated from the schema.