Campaigns

Send a campaign to the people you list

POST/v1/campaigns/{id}/trigger

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

Takes an Idempotency-Key header: a retry with the same key returns the first result instead of acting twice. Derive the key from what you are sending, and reuse it on every retry. About idempotency

Sends a draft now to the contacts recipients names, by contactId, externalId or email, instead of its saved audience; it needs none. Each person may carry their own data, read in the content as {{ data.<key> }} over the shared data: "the item in your basket is now cheaper", to each their item. Up to 5,000 recipients, the request up to 10 MB. A recipient that names no contact is not sent and comes back in notFound; one contact listed twice is refused with 400. Each message is checked as any campaign send is (consent, suppression, topic, limits), and a message whose content reads a value its recipient lacks is skipped with missing_merge_tag. Data is kept on a message only until it is sent. A campaign whose content reads data can go out only this way. A campaign is sent at most once. An Idempotency-Key header is required: a retry with the same key and request returns the first answer, notFound included, with Idempotency-Replay: true; the same key with a different request is 409 IDEMPOTENCY_KEY_REUSED, and any other trigger of a campaign already sent is 409 CONFLICT: to send again, duplicate it. Agent keys are refused with 403, and a campaign an agent wrote or edited answers 409 AGENT_CONFIRMATION_REQUIRED until a person confirms it in the dashboard.

Path parameters

idstringrequired: uuid

Header parameters

Idempotency-Keystringrequired: 8–255 characters

Request body

dataobjectoptional

Values every recipient shares.

recipientsobject[]required

The people to send to, each named by one identifier.

at least 1 item · at most 5000 items

One of 3 shapes

Recipient by contact ID

2 child attributes

contactIdstringrequired

Kirora's id for the contact.

uuid

dataobjectoptional

This person's values; each key overrides the trigger's shared data.

Recipient by external ID

2 child attributes

externalIdstringrequired

Your own id for the contact, as set with identify.

1–255 characters

dataobjectoptional

This person's values; each key overrides the trigger's shared data.

Recipient by email

2 child attributes

emailstringrequired: The contact's email address, matched trimmed and without case.
dataobjectoptional: This person's values; each key overrides the trigger's shared data.

Returns

Returns 202 Accepted with a TriggeredCampaign in data. Otherwise returns an error; Errors lists every code and which to retry.

campaignCampaignrequired

17 child attributes

idstringrequired

uuid

namestringrequired

channelsstring[]required

The channels it sends on.

groupIdstring | nullrequired

The group it goes to, if any.

uuid

segmentIdstring | nullrequired

The segment it goes to, if any.

uuid

audienceRulesobject | nullrequired

Inline rules choosing the audience, if any. At most one audience is set.

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 | nullrequired

Sends only to contacts the topic reaches; null sends to everyone with consent.

uuid

messageLimitsMessageLimitUserequired

2 child attributes

applybooleanrequired
retryHoursintegeroptional: min 0 · max 48

utmobject | nullrequired

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

contentCampaignContentrequired

4 child attributes

emailobjectoptional

The email fields; any may be missing on a draft.

6 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

htmlstringoptional

The HTML body. Rendered from the design when one is set.

1–512000 characters

textstringoptional

The plain-text alternative.

1–512000 characters

fromstringoptional

The sender address, on a verified sending domain.

1–320 characters

replyTostringoptional

Where replies go.

pushProjectIdstringoptional

The push app the notification goes out through.

uuid

pushobjectoptional

The notification content.

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.
androidobjectoptional: Replaces shared fields on Android.
webobjectoptional: Replaces shared fields on web.

templateSnapshotobjectoptional

The email design, copied into the campaign so later template edits do not change it.

4 child attributes

schemaVersionintegerrequired

min > 0 · max 1000

blocksEmailBlock[]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

styleEmailBlockStyleoptional

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

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.

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

themeEmailThemerequired

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 512000 characters

statusstringrequired

Where the campaign is in its lifecycle.

one of draft, scheduled, sending, sent, cancelled

sendAtstring | nullrequired

When it is scheduled to send, if at all.

date-time

localSendAtstring | nullrequired

Set for a local-time send: the wall-clock time each contact receives it at.

archivedAtstring | nullrequired

When it was archived; archived campaigns are left out of the list by default.

date-time

revisionintegerrequired

Raised by every edit. Send it back as expectedRevision on the update so a change made since you read it is refused instead of overwritten.

min > 0 · max 2147483647

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

notFoundobject[]required

Recipients that name no contact in the workspace, as listed; not sent.

One of 3 shapes

Contact ID

1 child attribute

contactIdstringrequired

Kirora's id for the contact.

uuid

External ID

1 child attribute

externalIdstringrequired

Your own id for the contact, as set with identify.

1–255 characters

1 child attribute

emailstringrequired

The contact's email address, matched trimmed and without case.

email · up to 320 characters

curl -X POST https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/trigger \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Idempotency-Key: price-drop-2030-03-14" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "store": "Juniper Kitchen"
    },
    "recipients": [
      {
        "externalId": "customer-4821",
        "data": {
          "item": "Cast iron skillet",
          "price": "$39.00"
        }
      },
      {
        "email": "sam@example.com",
        "data": {
          "item": "Chef knife",
          "price": "$54.00"
        }
      },
      {
        "externalId": "customer-9999",
        "data": {
          "item": "Dutch oven",
          "price": "$89.00"
        }
      }
    ]
  }'

const response = await fetch('https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/trigger', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Idempotency-Key': "price-drop-2030-03-14",
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "data": {
      "store": "Juniper Kitchen"
    },
    "recipients": [
      {
        "externalId": "customer-4821",
        "data": {
          "item": "Cast iron skillet",
          "price": "$39.00"
        }
      },
      {
        "email": "sam@example.com",
        "data": {
          "item": "Chef knife",
          "price": "$54.00"
        }
      },
      {
        "externalId": "customer-9999",
        "data": {
          "item": "Dutch oven",
          "price": "$89.00"
        }
      }
    ]
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/trigger",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
        "Idempotency-Key": "price-drop-2030-03-14",
    },
    json={
        "data": {
            "store": "Juniper Kitchen",
        },
        "recipients": [
            {
                "externalId": "customer-4821",
                "data": {
                    "item": "Cast iron skillet",
                    "price": "$39.00",
                },
            },
            {
                "email": "sam@example.com",
                "data": {
                    "item": "Chef knife",
                    "price": "$54.00",
                },
            },
            {
                "externalId": "customer-9999",
                "data": {
                    "item": "Dutch oven",
                    "price": "$89.00",
                },
            },
        ],
    },
)
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "data": {
	    "store": "Juniper Kitchen"
	  },
	  "recipients": [
	    {
	      "externalId": "customer-4821",
	      "data": {
	        "item": "Cast iron skillet",
	        "price": "$39.00"
	      }
	    },
	    {
	      "email": "sam@example.com",
	      "data": {
	        "item": "Chef knife",
	        "price": "$54.00"
	      }
	    },
	    {
	      "externalId": "customer-9999",
	      "data": {
	        "item": "Dutch oven",
	        "price": "$89.00"
	      }
	    }
	  ]
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/trigger", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Idempotency-Key", "price-drop-2030-03-14")
	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": {
    "campaign": {
      "id": "0192f3d0-4c5d-7e6f-8a90-1b2c3d4e5f60",
      "name": "Price drop on saved items",
      "channels": [
        "email"
      ],
      "status": "sent",
      "groupId": null,
      "segmentId": null,
      "audienceRules": null,
      "topicId": null,
      "content": {
        "email": {
          "subject": "Now cheaper: {{ data.item }}",
          "from": "Juniper Kitchen <hello@juniperkitchen.com>"
        },
        "templateSnapshot": {
          "schemaVersion": 1,
          "blocks": [
            {
              "id": "heading",
              "type": "heading",
              "text": "Now cheaper: {{ data.item }}"
            },
            {
              "id": "body",
              "type": "text",
              "text": "It is {{ data.price }} today at {{ data.store }}."
            },
            {
              "id": "footer",
              "type": "footer",
              "text": "1 Example Street, London",
              "locked": true
            }
          ],
          "theme": {}
        }
      },
      "messageLimits": {
        "apply": false,
        "retryHours": 0
      },
      "utm": null,
      "sendAt": "2030-03-14T09:30:00.000Z",
      "localSendAt": null,
      "archivedAt": null,
      "revision": 3,
      "createdAt": "2030-03-14T09:00:00.000Z",
      "updatedAt": "2030-03-14T09:30:00.000Z"
    },
    "notFound": [
      {
        "externalId": "customer-9999"
      }
    ]
  }
}