The words these guides and the API reference use, each with its exact meaning in Kirora. Where two terms are easily confused, they are explained together.
Workspace
One Kirora account’s data: its contacts, events, templates, campaigns, journeys, keys and settings. Every credential acts in exactly one workspace, the one its authentication selects, and a resource in another workspace returns 404. Some sending protections apply across workspaces under the same owner or partner; see Suppression. A login can belong to several workspaces. See Authentication.
Contact
One person you message, identified by Kirora’s id and at least one of your
externalId, an email address or a phone number. A contact holds profile fields,
custom attributes, dates, consent on each channel, topic choices and list memberships.
See IDs and identity.
Contact id and external id
The contact id (id) is the UUID Kirora assigns to a contact. The external id
(externalId) is your own id for the same contact, set by you, unique in the workspace.
Contact routes take either: the external id with ?idType=externalId. See
IDs and identity.
List, segment and tag
- A list is a fixed set of contacts you add and remove explicitly. Its membership changes only when you change it.
- A segment is an audience described by rules, such as “ordered twice in 90 days”. It is evaluated when used, so it changes as contacts and their events change. See Objects and rules.
- A tag is a label on campaigns, journeys, segments and templates, for organising and filtering them. It is not an audience.
Neither a list nor a segment is consent: being in one does not mean a contact agreed to marketing.
Consent and topic choice
- Consent is a contact’s agreement to marketing on one channel:
consent.emailandconsent.push. Marketing goes only to contacts with consent on its channel. Granting it needs a statement of how the contact agreed. - A topic is a kind of marketing a contact can choose, such as product updates. A
topic choice is their choice for one topic, on every channel or on one. An
opt_outtopic reaches everyone with consent who has not left it; anopt_intopic only those who joined it.
A campaign or journey step sent on a topic needs both: consent on the channel, and the topic reaching the contact. Transactional email needs neither. Transactional push still needs the contact’s push consent and an eligible device, but no topic.
Suppression
A block on an email address, held whether or not a contact has it. A bounce, a spam
complaint, an unsubscribe, or an address you add or import is suppressed, and the reason
decides what it stops: a bounce or a complaint on a transactional message stops all
email to the address; the others stop marketing only. A bounce or complaint also blocks
the address in sister workspaces (the same owner or partner), which do not list it among
their own suppressions; a contact’s emailSuppression gives the effective answer, with
reason other_workspace. Suppressions are evidence, so bounces, complaints and
unsubscribes cannot be deleted through the API; manual and imported ones can, with
deleteSuppressions. listSuppressions describes what each reason blocks.
Event and webhook event
- An event is something a contact did, recorded in Kirora:
Order Completed, with its properties. You send events withtrackEvent, and Kirora records a few of its own (contact.added_to_list). Segments and journeys read them. See Events. - A webhook event is a notification Kirora sends to your endpoint about something
that happened in Kirora:
message.delivered,contact.unsubscribed. See Webhooks.
Message
One send to one contact on one channel. A campaign to 1,000 contacts by email is 1,000
messages; a transactional send to email and push is two. Each message has a status
and appears in the message log. See Message log and exports.
Accepted, sent and delivered
- Accepted: the request passed its checks and the message was stored, with status
queued. A send returns 202 at this point. - Sent: the message was handed to the email provider or the push service.
- Delivered: email only. The recipient’s mail server accepted the message. It does not show whether it reached the inbox or the spam folder.
A message can also end skipped (a check stopped it before sending), failed,
bounced or complained.
Campaign and journey
- A campaign is one marketing send to an audience, now or at a set time. It sends at most once.
- A journey is an automation: a contact enters when an event happens or a date arrives, then runs through steps such as waits, sends and branches, each at their own pace.
Template
A reusable email design: a tree of blocks and a theme. The template itself is the draft; transactional sends use its published version. A campaign or journey copies the design when it is chosen. See Objects and rules.
Credentials
| Credential | Held by | Acts |
|---|---|---|
| Integration key | Your servers | On /v1, with exactly the scopes it holds |
| Agent key | An AI assistant, over MCP or /v1 |
Reads and drafts, but cannot send, activate or change contacts and consent. A person confirms what it drafted |
| Partner key | A partner’s servers | In the partner workspace, and in its child workspaces through the Kirora-Workspace header |
| Client key | Your web pages, for the web SDK | Only with a user token your server signed, for that one user |
| Embed session | Kirora’s builders in a partner’s page | For 15 minutes, in one child workspace, reading what the builders need |
See Choose an integration and Authentication.
Test address and staging workspace
- A test address is a reserved address, such as
[email protected]or anything at a.testdomain. A message to it passes every check, then is skipped withtest_emailand never reaches the provider.[email protected],[email protected]and[email protected]act out that outcome instead, markedsimulated, and suppress nothing. Use them in any workspace. See Test addresses. - A staging workspace is a second workspace for your staging environment. It sends for real, to real addresses, and keeps its data apart from live. There is no test mode or test key. See Staging.