Campaigns

Check who a campaign would reach before saving it

POST/v1/campaigns/eligibility

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

Takes the body POST /campaigns takes and answers as GET /campaigns/{id}/eligibility would for that draft, with campaignId: null, so the composer can show the audience while it is edited. Nothing is saved.

Request body

namestringrequired

1–255 characters

channelsstring[]optional

The channels to send on; each needs its own content. Defaults to email.

at least 1 item

groupIdstringoptional

Send to this group. Choose at most one audience.

uuid

segmentIdstringoptional

Send to this segment. Choose at most one audience.

uuid

audienceRulesobjectoptional

Send to contacts matching these rules. Choose at most one audience.

One of 2 shapes

Match all

1 child attribute

allobject[]required

Every rule or nested group must match.

at least 1 item · at most 20 items

Match any

1 child attribute

anyobject[]required

At least one rule or nested group must match.

at least 1 item · at most 20 items

topicIdstring | nulloptional

Send only to contacts the topic reaches. Omit to reach everyone with consent.

uuid

messageLimitsMessageLimitUseInputoptional

2 child attributes

applybooleanrequired
retryHoursintegeroptional: min 0 · max 48

utmobject | nulloptional

UTM parameters added to the links in the email.

6 child attributes

enabledbooleanrequired
sourcestringoptional: 1–100 characters
mediumstringoptional: 1–100 characters
campaignstringoptional: 1–100 characters
contentstringoptional: 1–100 characters
termstringoptional: 1–100 characters

contentobjectoptional

The content for each selected channel. A draft may leave parts out.

default {}

4 child attributes

emailobjectoptional

Subject, preview text and sender. Needed to send once channels has email.

4 child attributes

subjectstringoptional

The subject line. Merge tags are allowed.

1–998 characters

previewTextstringoptional

Shown by inboxes after the subject. Merge tags are allowed; keep it near 100 characters.

1–255 characters

fromstringoptional

The sender address, on a verified sending domain.

1–320 characters

replyTostringoptional

Where replies go.

templateSnapshotTemplateSnapshotInputoptional

The email design. Needed to send once channels has email.

4 child attributes

schemaVersionintegerrequired

The block format version; use the current one, 1.

min > 0 · max 1000

blocksEmailBlockInput[]required

At most 200 blocks across the entire tree and five levels including the root. Footer blocks must remain at root. Known child fields are validated recursively.

at least 1 item · at most 200 items

7 child attributes

idstringrequired

Identifies the block within the template; unique among its blocks.

1–128 characters

typestringrequired

The block type: header, heading, text, image, button, divider, spacer, columns, columns3, imagetext, imagegroup, boxed, quote, list, product, video, social, menu, html, section, footer, repeat, shared. Each type reads its own fields next to type; an unknown type is kept but not validated.

1–64 characters

styleEmailBlockStyleInputoptional

Visual overrides for this block, such as colours, font and spacing.

17 child attributes

backgroundColorstringoptional

Fill behind the block.

fontFamilystringoptional

A font every client has (Arial, Verdana, Georgia, Tahoma, Times New Roman, Courier New), or a web font, which shows where the client loads it and falls back to a safe font elsewhere.

one of Arial, Verdana, Georgia, Tahoma, Times New Roman, Courier New, Inter, Roboto, Open Sans, Lato, Montserrat, Poppins, DM Sans, Nunito, Work Sans, Oswald, Playfair Display, Merriweather, Lora, Libre Baskerville, EB Garamond

fontSizeintegeroptional

Text size in px, 12 to 72.

min 12 · max 72

mobileFontSizeintegeroptional

Text size in px on phones (screens up to 620px), 12 to 72.

min 12 · max 72

paddingobjectoptional

Space inside the block in px, 0 to 100 per side; omitted sides keep their default.

borderWidthintegeroptional

Border thickness in px; 0 for none.

min 0 · max 10

borderStylestringoptional

Border line style.

one of solid, dashed, dotted

borderColorstringoptional

Border colour.

borderRadiusintegeroptional

Corner rounding in px, 0 to 100.

min 0 · max 100

textColorstringoptional

Text colour.

linkColorstringoptional

Colour of links in the text.

letterSpacingnumberoptional

Space between letters in px, such as 3 for a spaced-out eyebrow line.

min -2 · max 20

textTransformstringoptional

Set to uppercase to capitalise all text.

one of none, uppercase

lineHeightnumberoptional

A multiple of the font size.

min 1 · max 3

fontWeightstringoptional

Text weight.

one of regular, bold

fontStylestringoptional

Text style.

one of normal, italic

insetbooleanoptional

Draw the background and border as a box within the content width, not across the whole row.

visibleIfobjectoptional

Show the block only to contacts these segment rules match, checked as each message is rendered. Omit to show it to everyone. Not allowed on the footer.

One of 2 shapes

Match all
Match any

showOnstringoptional

Show the block only on phones (screens up to 620px) or only on wider screens. Clients that ignore screen size show the desktop version, and so does plain text. Omit to show it everywhere. Not allowed on the footer.

one of mobile, desktop

columnsobject[][]optional

Nested child block arrays: exactly two for columns, three for columns3. Each child follows this block contract. Omit to retain legacy text columns.

at most 3 items

blocksobject[]optional

A section's child blocks, drawn inside its box; or a repeat block's, written out once per item of its list, where {{ item.<field> }} reads that item. Repeats do not nest.

at most 200 items

themeEmailThemeInputrequired

Theme values this email overrides.

11 child attributes

fontstringoptional

Body font stack, such as Inter, sans-serif.

up to 200 characters

hfontstringoptional

Heading font stack.

up to 200 characters

bgstringoptional

Background of the email card, as hex.

canvasstringoptional

Background behind the card, as hex.

textstringoptional

Default text colour, as hex.

accentstringoptional

Brand colour for buttons and highlights, as hex.

linkstringoptional

Link colour, as hex.

widthstringoptional

Width of the email card on wide screens.

one of 560px, 600px, 680px

radiusstringoptional

Corner rounding of the email's card.

one of 0px, 6px, 12px, 16px, 24px, 999px

btnRadiusstringoptional

Button corners; radius rounds the email's card and, when this is unset, buttons.

one of 0px, 6px, 12px, 16px, 24px, 999px

btnstringoptional

Button style.

one of solid, outline

plainTextOverridestring | nulloptional

Plain text sent instead of the version generated from the blocks.

up to 100000 characters

pushProjectIdstringoptional

The push app to send through. Needed to send once channels has push.

uuid

pushobjectoptional

The notification content. Needed to send once channels has push.

13 child attributes

titlestringoptional

The notification title (up to 100 characters).

1–100 characters

bodystringoptional

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

The HTTPS page opened when the notification is tapped.

uri · up to 2048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2048 characters

dataobjectoptional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

2 child attributes

titlestringrequired

The button label.

1–30 characters

urlstringrequired

The HTTPS page the button opens.

uri · up to 2048 characters

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. Unset, a transactional push is high and any other normal.

one of high, normal

overridesobjectoptional

Fields that differ on one platform, each replacing the shared one there (a whole data map, not merged key by key). On iOS and Android actionUrl may be an app link such as myapp://orders; the shared one and the web one must be HTTPS.

3 child attributes

iosobjectoptional

Replaces shared fields on iOS.

14 child attributes

titlestringoptional

The notification title (up to 100 characters).

1–100 characters

bodystringoptional

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

up to 2048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2048 characters

dataobjectoptional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. Unset, a transactional push is high and any other normal.

one of high, normal

interruptionLevelstringoptional

How iOS presents it: passive arrives silently, time-sensitive breaks through Focus and needs the app's Time Sensitive Notifications capability.

one of passive, active, time-sensitive

threadIdstringoptional

Notifications with the same thread are grouped together in Notification Center.

androidobjectoptional

Replaces shared fields on Android.

13 child attributes

titlestringoptional

The notification title (up to 100 characters).

1–100 characters

bodystringoptional

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

up to 2048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2048 characters

dataobjectoptional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. Unset, a transactional push is high and any other normal.

one of high, normal

channelIdstringoptional

The Android notification channel to post in, which the app creates; it sets the sound and importance a person can tune, e.g. one for offers and one for orders.

webobjectoptional

Replaces shared fields on web.

12 child attributes

titlestringoptional

The notification title (up to 100 characters).

1–100 characters

bodystringoptional

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

The HTTPS page opened when the notification is tapped.

uri · up to 2048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2048 characters

dataobjectoptional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. Unset, a transactional push is high and any other normal.

one of high, normal

Returns

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

campaignIdstring | nullrequired

null when checked before saving (POST /campaigns/eligibility).

uuid

checkedAtstringrequired

When the check ran.

date-time

audienceCountintegerrequired

Contacts in the audience, before any channel's exclusions.

min 0 · max 9007199254740991

blockersstring[]required

Blockers for the campaign as a whole.

issuesobject[]required

What the draft still lacks, exactly as sending would refuse it (DRAFT_INCOMPLETE).

2 child attributes

pathstringrequired: The field that is incomplete, such as content.email.
messagestringrequired: What is missing, in plain words.

channelsobject[]required

One entry per selected channel.

One of 2 shapes

Email channel

6 child attributes

channel"email"required

eligibleRecipientCountintegerrequired

Contacts reachable on this channel after the exclusions.

min 0 · max 9007199254740991

sendableRecipientCountintegerrequired

eligibleRecipientCount when nothing blocks the campaign anywhere, else 0.

min 0 · max 9007199254740991

blockersstring[]required

What stops the email channel sending.

excludedobjectrequired

Contacts left out of the audience, by reason.

4 child attributes

consentMissingintegerrequired

Contacts without email consent.

min 0 · max 9007199254740991

topicUnsubscribedintegerrequired

Consented, but the campaign's topic does not reach them.

min 0 · max 9007199254740991

suppressedintegerrequired

Contacts whose address is blocked, for example after a bounce.

min 0 · max 9007199254740991

missingEmailintegerrequired

Contacts with no email address.

min 0 · max 9007199254740991

senderVerifiedbooleanrequired

Whether the sender domain is verified.

Push channel

6 child attributes

channel"push"required

eligibleRecipientCountintegerrequired

Contacts reachable on this channel after the exclusions.

min 0 · max 9007199254740991

sendableRecipientCountintegerrequired

eligibleRecipientCount when nothing blocks the campaign anywhere, else 0.

min 0 · max 9007199254740991

blockersstring[]required

What stops the push channel sending.

excludedobjectrequired

Contacts left out of the audience, by reason.

4 child attributes

consentMissingintegerrequired

Contacts without push consent.

min 0 · max 9007199254740991

topicUnsubscribedintegerrequired

Consented, but the campaign's topic does not reach them.

min 0 · max 9007199254740991

suppressedintegerrequired

Contacts blocked from push.

min 0 · max 9007199254740991

missingInstallationintegerrequired

Contacts with no registered device.

min 0 · max 9007199254740991

applicationReadybooleanrequired

Whether the push app is set up to send.

curl -X POST https://api.kirora.io/v1/campaigns/eligibility \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend specials"
  }'

const response = await fetch('https://api.kirora.io/v1/campaigns/eligibility', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Weekend specials"
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/campaigns/eligibility",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "name": "Weekend specials",
    },
)
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "name": "Weekend specials"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/campaigns/eligibility", 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 · 200

{
  "data": {
    "campaignId": "018f2a4e-6b1c-7d3e-9f40-3478765e5a6b",
    "checkedAt": "2030-03-14T09:30:00Z",
    "audienceCount": 0,
    "blockers": [
      "campaign_not_draft"
    ],
    "issues": [
      {
        "path": "path_example",
        "message": "message_example"
      }
    ],
    "channels": [
      {
        "channel": "email",
        "eligibleRecipientCount": 0,
        "sendableRecipientCount": 0,
        "blockers": [
          "missing_email_content"
        ],
        "excluded": {
          "consentMissing": 0,
          "topicUnsubscribed": 0,
          "suppressed": 0,
          "missingEmail": 0
        },
        "senderVerified": true
      }
    ]
  }
}

Example values are generated from the schema.