Retrieve a campaign's email results by domain, device or countryMenu

Retrieve a campaign's email results by domain, device or country

GET/v1/campaigns/{id}/breakdown

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

Works with integration, agent and partner keys.

Splits a campaign's email results into rows by the recipient's email domain (gmail.com), the device they first opened or clicked on (desktop, mobile, tablet), or the contact's country (GB), counted the same way as the campaign's metrics. Use it to find where a problem sits: bounces concentrated on one domain point at that mailbox provider, not at the whole list.

Rows are ordered by messages sent, largest first. The 50 largest are listed, and everything past them is summed in other (null when there are none). A row's key is null when the value is unknown: a device is known only once a person opens with images on or clicks (machine opens, such as Apple Mail Privacy Protection's and Gmail's prefetch, and Gmail's image proxy name no device, and other image proxies may read as desktop); a country only when the contact has one; a domain only while the message still names someone (not after the contact is deleted).

Push results are not included: a push campaign's per-device outcomes are in its metrics, under push.devices.

Path parameters

idstringrequired

The campaign's id.

uuid

Query parameters

groupBystringrequired

domain: the recipient's email domain. device: the kind of device a person first opened or clicked on. country: the contact's country (ISO 3166-1 alpha-2).

one of domain, device, country

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Returns

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

campaignIdstringrequired

uuid

groupBystringrequired

domain: the recipient's email domain. device: the kind of device a person first opened or clicked on. country: the contact's country (ISO 3166-1 alpha-2).

one of domain, device, country

rowsobject[]required

The largest rows by messages sent, largest first.

at most 50 items

10 child attributes

sentintegerrequired

min 0

deliveredintegerrequired

min 0

openedintegerrequired

Including machine opens, as in the campaign's metrics.

min 0

openedByMachineintegerrequired

min 0

clickedintegerrequired

min 0

clickedByMachineintegerrequired

min 0

bouncedintegerrequired

min 0

complainedintegerrequired

min 0

unsubscribedintegerrequired

min 0

keystring | nullrequired

The domain, desktop / mobile / tablet, or a country code; null when unknown.

otherobject | nullrequired

Every row past the largest 50, summed; null when there are 50 or fewer.

9 child attributes

sentintegerrequired

min 0

deliveredintegerrequired

min 0

openedintegerrequired

Including machine opens, as in the campaign's metrics.

min 0

openedByMachineintegerrequired

min 0

clickedintegerrequired

min 0

clickedByMachineintegerrequired

min 0

bouncedintegerrequired

min 0

complainedintegerrequired

min 0

unsubscribedintegerrequired

min 0

curl 'https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/breakdown?groupBy=domain' \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/breakdown?groupBy=domain', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/breakdown?groupBy=domain",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/breakdown?groupBy=domain", 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()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/breakdown?groupBy=domain");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 200

{
  "data": {
    "campaignId": "0192f3d3-5e6f-7071-8c83-9e0f1a2b3c4d",
    "groupBy": "domain",
    "rows": [
      {
        "key": "gmail.com",
        "sent": 1320,
        "delivered": 1302,
        "opened": 540,
        "openedByMachine": 0,
        "clicked": 151,
        "clickedByMachine": 12,
        "bounced": 18,
        "complained": 1,
        "unsubscribed": 2
      },
      {
        "key": "icloud.com",
        "sent": 410,
        "delivered": 405,
        "opened": 371,
        "openedByMachine": 322,
        "clicked": 38,
        "clickedByMachine": 2,
        "bounced": 5,
        "complained": 0,
        "unsubscribed": 1
      }
    ],
    "other": null
  }
}