Reports

Retrieve transactional email delivery

GET/v1/reports/transactional

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

Transactional email by the day the API accepted it, so a send that failed or was skipped counts on its day. Email only: transactional push is not counted. Opens and clicks are not counted either: a send is tracked only when it asks (tracking), so a rate across all sends would mislead; read them on each message. Later feedback revises the counts. Bounce and complaint counts are durable first-occurrence facts, not current statuses. Rates are fractions of sent; null means nothing was sent. Days are calendar days in the workspace timezone (timezone); the first and last may be partial. Omitting both dates means the last 30 days ending today.

Query parameters

startDatestringoptional

First day, inclusive, in the workspace timezone. Give with endDate.

date

endDatestringoptional

Last day, inclusive, no later than today. Give with startDate; a window is at most 366 days. Omit both for the last 30 days.

date

Returns

Returns 200 OK with a TransactionalReport in data. Otherwise returns an error; Errors lists every code and which to retry.

generatedAtstringrequired

date-time

timezonestringrequired

The workspace timezone the dates are calendar days in.

startDatestringrequired

First day of the window (inclusive).

date

endDatestringrequired

Last day of the window (inclusive).

date

currentPeriodobjectrequired

The window as UTC instants.

2 child attributes

startstringrequired

Start of the period (inclusive).

date-time

endstringrequired

End of the period (exclusive).

date-time

previousPeriodobjectrequired

The equal-length period just before it.

2 child attributes

startstringrequired

Start of the period (inclusive).

date-time

endstringrequired

End of the period (exclusive).

date-time

currentTransactionalCountsrequired

Counts in the window.

7 child attributes

acceptedintegerrequired

Every send the API accepted, whatever became of it.

min -9007199254740991 · max 9007199254740991

sentintegerrequired

Handed to the provider.

min -9007199254740991 · max 9007199254740991

deliveredintegerrequired

min -9007199254740991 · max 9007199254740991

bouncedintegerrequired

min -9007199254740991 · max 9007199254740991

complainedintegerrequired

min -9007199254740991 · max 9007199254740991

failedintegerrequired

The provider refused it, or every attempt to send it failed.

min -9007199254740991 · max 9007199254740991

skippedintegerrequired

Never sent: the address is suppressed, or the send was refused before it left.

min -9007199254740991 · max 9007199254740991

previousTransactionalCountsrequired

Counts in the previous period.

7 child attributes

acceptedintegerrequired

Every send the API accepted, whatever became of it.

min -9007199254740991 · max 9007199254740991

sentintegerrequired

Handed to the provider.

min -9007199254740991 · max 9007199254740991

deliveredintegerrequired

min -9007199254740991 · max 9007199254740991

bouncedintegerrequired

min -9007199254740991 · max 9007199254740991

complainedintegerrequired

min -9007199254740991 · max 9007199254740991

failedintegerrequired

The provider refused it, or every attempt to send it failed.

min -9007199254740991 · max 9007199254740991

skippedintegerrequired

Never sent: the address is suppressed, or the send was refused before it left.

min -9007199254740991 · max 9007199254740991

deltaTransactionalCountsrequired

current minus previous.

7 child attributes

acceptedintegerrequired

Every send the API accepted, whatever became of it.

min -9007199254740991 · max 9007199254740991

sentintegerrequired

Handed to the provider.

min -9007199254740991 · max 9007199254740991

deliveredintegerrequired

min -9007199254740991 · max 9007199254740991

bouncedintegerrequired

min -9007199254740991 · max 9007199254740991

complainedintegerrequired

min -9007199254740991 · max 9007199254740991

failedintegerrequired

The provider refused it, or every attempt to send it failed.

min -9007199254740991 · max 9007199254740991

skippedintegerrequired

Never sent: the address is suppressed, or the send was refused before it left.

min -9007199254740991 · max 9007199254740991

ratesobjectrequired

Fractions of sent; null when nothing was sent.

3 child attributes

deliverynumber | nullrequired: min 0
bouncenumber | nullrequired: min 0
complaintnumber | nullrequired: min 0

seriesobject[]required

One entry per calendar day in the window.

at most 366 items

8 child attributes

acceptedintegerrequired

Every send the API accepted, whatever became of it.

min -9007199254740991 · max 9007199254740991

sentintegerrequired

Handed to the provider.

min -9007199254740991 · max 9007199254740991

deliveredintegerrequired

min -9007199254740991 · max 9007199254740991

bouncedintegerrequired

min -9007199254740991 · max 9007199254740991

complainedintegerrequired

min -9007199254740991 · max 9007199254740991

failedintegerrequired

The provider refused it, or every attempt to send it failed.

min -9007199254740991 · max 9007199254740991

skippedintegerrequired

Never sent: the address is suppressed, or the send was refused before it left.

min -9007199254740991 · max 9007199254740991

datestringrequired

date

curl https://api.kirora.io/v1/reports/transactional \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/reports/transactional', {
  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/reports/transactional",
    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/reports/transactional", 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": {
    "generatedAt": "2030-03-14T09:30:00Z",
    "timezone": "Europe/London",
    "startDate": "2030-03-14",
    "endDate": "2030-03-14",
    "currentPeriod": {
      "start": "2030-03-14T09:30:00Z",
      "end": "2030-03-14T09:30:00Z"
    },
    "previousPeriod": {
      "start": "2030-03-14T09:30:00Z",
      "end": "2030-03-14T09:30:00Z"
    },
    "current": {
      "accepted": -9007199254740991,
      "sent": -9007199254740991,
      "delivered": -9007199254740991,
      "bounced": -9007199254740991,
      "complained": -9007199254740991,
      "failed": -9007199254740991,
      "skipped": -9007199254740991
    },
    "previous": {
      "accepted": -9007199254740991,
      "sent": -9007199254740991,
      "delivered": -9007199254740991,
      "bounced": -9007199254740991,
      "complained": -9007199254740991,
      "failed": -9007199254740991,
      "skipped": -9007199254740991
    },
    "delta": {
      "accepted": -9007199254740991,
      "sent": -9007199254740991,
      "delivered": -9007199254740991,
      "bounced": -9007199254740991,
      "complained": -9007199254740991,
      "failed": -9007199254740991,
      "skipped": -9007199254740991
    },
    "rates": {
      "delivery": 0,
      "bounce": 0,
      "complaint": 0
    },
    "series": [
      {
        "accepted": -9007199254740991,
        "sent": -9007199254740991,
        "delivered": -9007199254740991,
        "bounced": -9007199254740991,
        "complained": -9007199254740991,
        "failed": -9007199254740991,
        "skipped": -9007199254740991,
        "date": "2030-03-14"
      }
    ]
  }
}

Example values are generated from the schema.