# Glossary

Source: https://kirora.io/docs/api/glossary

Look up the exact meaning of the terms these guides use, from workspace and contact to accepted, sent and delivered.

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](#suppression). A login can belong to
several workspaces. See [Authentication](https://kirora.io/docs/api/reference/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](https://kirora.io/docs/api/identifiers).

## 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](https://kirora.io/docs/api/identifiers).

## 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](https://kirora.io/docs/api/models#segment-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.email` and
  `consent.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_out` topic reaches everyone with consent who has not left it; an `opt_in` topic
  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 with `trackEvent`, and Kirora records a few of its own
  (`contact.added_to_list`). Segments and journeys read them. See [Events](https://kirora.io/docs/api/events).
- **A webhook event** is a notification Kirora sends to your endpoint about something
  that happened in Kirora: `message.delivered`, `contact.unsubscribed`. See
  [Webhooks](https://kirora.io/docs/api/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](https://kirora.io/docs/api/messages).

## 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.

See [Campaigns and journeys](https://kirora.io/docs/api/campaigns-and-journeys).

## 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](https://kirora.io/docs/api/models#template-documents).

## 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](https://kirora.io/docs/api/integrations) and [Authentication](https://kirora.io/docs/api/reference/authentication).

## Test address and staging workspace

- **A test address** is a reserved address, such as `ada@example.com` or anything at a
  `.test` domain. A message to it passes every check, then is skipped with `test_email`
  and never reaches the provider. `delivered@example.com`, `bounce@example.com` and
  `complaint@example.com` act out that outcome instead, marked `simulated`, and suppress
  nothing. Use them in any workspace. See
  [Test addresses](https://kirora.io/docs/api/transactional#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](https://kirora.io/docs/api/staging).

## Next steps

- [Choose an integration](https://kirora.io/docs/api/integrations) — which credential your code needs
- [IDs and identity](https://kirora.io/docs/api/identifiers) — how contacts are found and matched
- [Objects and rules](https://kirora.io/docs/api/models) — segments, journeys, templates and webhooks in detail