# Retrieve transactional email delivery

`GET /v1/reports/transactional`

Requires an API key with the `reports:read` scope. [About keys and scopes](/docs/api/authentication)

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

- `startDate` (string, optional, date) — First day, inclusive, in the workspace timezone. Give with `endDate`.
- `endDate` (string, optional, date) — Last day, inclusive, no later than today. Give with `startDate`; a window is at most 366 days. Omit both for the last 30 days.

## Returns

Returns `200 OK` with a `TransactionalReport` in `data`. Otherwise returns an error; [Errors](/docs/api/errors) lists every code and which to retry.

- `generatedAt` (string, required, date-time)
- `timezone` (string, required) — The workspace timezone the dates are calendar days in.
- `startDate` (string, required, date) — First day of the window (inclusive).
- `endDate` (string, required, date) — Last day of the window (inclusive).
- `currentPeriod` (object, required) — The window as UTC instants.
  - `start` (string, required, date-time) — Start of the period (inclusive).
  - `end` (string, required, date-time) — End of the period (exclusive).
- `previousPeriod` (object, required) — The equal-length period just before it.
  - `start` (string, required, date-time) — Start of the period (inclusive).
  - `end` (string, required, date-time) — End of the period (exclusive).
- `current` (TransactionalCounts, required) — Counts in the window.
  - `accepted` (integer, required, min -9007199254740991, max 9007199254740991) — Every send the API accepted, whatever became of it.
  - `sent` (integer, required, min -9007199254740991, max 9007199254740991) — Handed to the provider.
  - `delivered` (integer, required, min -9007199254740991, max 9007199254740991)
  - `bounced` (integer, required, min -9007199254740991, max 9007199254740991)
  - `complained` (integer, required, min -9007199254740991, max 9007199254740991)
  - `failed` (integer, required, min -9007199254740991, max 9007199254740991) — The provider refused it, or every attempt to send it failed.
  - `skipped` (integer, required, min -9007199254740991, max 9007199254740991) — Never sent: the address is suppressed, or the send was refused before it left.
- `previous` (TransactionalCounts, required) — Counts in the previous period.
  - `accepted` (integer, required, min -9007199254740991, max 9007199254740991) — Every send the API accepted, whatever became of it.
  - `sent` (integer, required, min -9007199254740991, max 9007199254740991) — Handed to the provider.
  - `delivered` (integer, required, min -9007199254740991, max 9007199254740991)
  - `bounced` (integer, required, min -9007199254740991, max 9007199254740991)
  - `complained` (integer, required, min -9007199254740991, max 9007199254740991)
  - `failed` (integer, required, min -9007199254740991, max 9007199254740991) — The provider refused it, or every attempt to send it failed.
  - `skipped` (integer, required, min -9007199254740991, max 9007199254740991) — Never sent: the address is suppressed, or the send was refused before it left.
- `delta` (TransactionalCounts, required) — `current` minus `previous`.
  - `accepted` (integer, required, min -9007199254740991, max 9007199254740991) — Every send the API accepted, whatever became of it.
  - `sent` (integer, required, min -9007199254740991, max 9007199254740991) — Handed to the provider.
  - `delivered` (integer, required, min -9007199254740991, max 9007199254740991)
  - `bounced` (integer, required, min -9007199254740991, max 9007199254740991)
  - `complained` (integer, required, min -9007199254740991, max 9007199254740991)
  - `failed` (integer, required, min -9007199254740991, max 9007199254740991) — The provider refused it, or every attempt to send it failed.
  - `skipped` (integer, required, min -9007199254740991, max 9007199254740991) — Never sent: the address is suppressed, or the send was refused before it left.
- `rates` (object, required) — Fractions of `sent`; null when nothing was sent.
  - `delivery` (number | null, required, min 0)
  - `bounce` (number | null, required, min 0)
  - `complaint` (number | null, required, min 0)
- `series` (object[], required, at most 366 items) — One entry per calendar day in the window.
  - `accepted` (integer, required, min -9007199254740991, max 9007199254740991) — Every send the API accepted, whatever became of it.
  - `sent` (integer, required, min -9007199254740991, max 9007199254740991) — Handed to the provider.
  - `delivered` (integer, required, min -9007199254740991, max 9007199254740991)
  - `bounced` (integer, required, min -9007199254740991, max 9007199254740991)
  - `complained` (integer, required, min -9007199254740991, max 9007199254740991)
  - `failed` (integer, required, min -9007199254740991, max 9007199254740991) — The provider refused it, or every attempt to send it failed.
  - `skipped` (integer, required, min -9007199254740991, max 9007199254740991) — Never sent: the address is suppressed, or the send was refused before it left.
  - `date` (string, required, date)

## Example

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

Response `200`:

```json
{
  "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"
      }
    ]
  }
}
```