# Segments and campaigns

Saved segments select people using recorded data. Campaigns send an approved email to a segment. Start with a scoped `BARUA_MANAGEMENT_KEY` and the [installed skill](/docs/guides/quickstart.md).

## Discover what is allowed

```sh
node "$BARUA_SKILL/scripts/manage.mjs" capabilities
node "$BARUA_SKILL/scripts/manage.mjs" segments
```

Segment and campaign list/detail reads need at least one of `segment:write`, `campaign:write` or `campaign:send`. Recipient reads also need `people:read`. Use the returned capabilities to check your connection.

Success returns the current saved segments. For paginated lists, continue using the returned cursor with `--after`. Use `segment --id` to inspect one segment and `segment-fields` to discover supported fields before building rules.

## Create or change an audience

Read [Send one campaign to a saved segment](/skills/barua-setup/references/management.md#send-one-campaign-to-a-saved-segment) before segment or campaign actions. It defines the action inputs and review sequence. Changes go through `manage.mjs action` with a private JSON input and a stable idempotency key.

Do not guess field names or treat a preview count as a promise to send to every person. Consent and suppression checks still apply at send time.

## Review and send

When the campaign checkpoint applies, the owner reviews the exact revision. Only an explicit owner choice delegates sending without that checkpoint. Use `campaigns` and `campaign --id` to inspect stored content, then follow the reference's send procedure with the required permission and checkpoints.

Immediate mode skips quiet hours and the marketing gap. Obtain explicit authorization for that exception; urgency alone does not authorize it. Consent and duplicate-send protection still apply.

Campaign approval does not enable lifecycle Plays. [Operate Plays](/docs/guides/plays.md) covers those separately.

## Check the result

Use `campaign-job` to inspect job progress and `campaign-recipients` to see recipient outcomes. A queued job is not delivery proof. Use [email history](/docs/guides/emails.md) for recorded message content and [workspace inspection](/docs/guides/inspect-workspace.md) for diagnostics.

If a write times out, retain its idempotency key and read the operation before retrying. [Recovery rules](/docs/guides/troubleshooting.md) explain the safe next step.