# Campaigns

URL: https://developers.uidu.org/docs/domains/campaigns

> Marketing campaigns and email campaign analytics.

* **Use it for:** [Server integration](https://developers.uidu.org/docs/paths/server-integration.md)
* **Reads:** Bearer (`apiKey`) — server-side only
* **Writes:** none — read-only today
* **CLI:** `uidu campaigns`
* **Auth:** what each token can do and where it may run — [Authentication](https://developers.uidu.org/docs/foundations/authentication.md)

The workspace's marketing campaigns and how their emails performed. Read-only today, and reads need
the account Bearer (`apiKey`): campaign data runs on your server, never in the browser.

## Mental model

```
Campaign                 name, status, scheduledAt, sentAt, target list
  └─→ campaignable       its channel: an EmailCampaign or a TextMessageCampaign
EmailCampaign            subject, replyTo, delivery metrics
  └─→ campaign           back to its Campaign (id, name, status)
```

* **A `Campaign` is the parent record**: `name` (plus an internal `innerName`), `status`, the
  `scheduledAt` / `sentAt` timestamps, and the `list` it targets. `getCampaign` adds
  `preferences`, a JSON blob with the campaign's settings (segment, channel options).
* **`status`** is `draft`, `scheduled` or `sent` — a campaign starts as a draft. `listCampaigns`
  filters by it, and by **`kind`**, the channel type: `'EmailCampaign'` or
  `'TextMessageCampaign'`.
* **An `EmailCampaign` is the email realization of a campaign**, and it's where the numbers
  are: `sentCount`, `deliveredCount`, `openedCount`, `clickedCount`, `uniqueOpens`,
  `uniqueClicks`, `lastOpenedAt`, `lastClickedAt`. `listEmailCampaigns` reads them for the whole
  workspace, each with its `campaign`; there is no per-campaign call and no CLI noun for it.
  Bounce, complaint and unsubscribe counts exist in uidu but the SDK doesn't fetch them yet.
* **`openRate` and `clickRate` are integer percentages of delivered emails**
  (opened ÷ delivered × 100, clicked ÷ delivered × 100), and `0` when nothing was delivered yet.
  Show them as `42%`, don't multiply again.
* Both lists return one page as a flat array, newest first; page with `first`/`after` or walk
  them with [`paginate`](https://developers.uidu.org/docs/foundations/pagination-and-field-values.md) (`ListCampaignsDocument`,
  `ListEmailCampaignsDocument`). A client with a public token sees none — an empty list is first a
  sign of the wrong token ([Authentication](https://developers.uidu.org/docs/foundations/authentication.md)).

## Use cases

### Email performance dashboard

Goal: an internal page lists the recent email blasts with their delivery and engagement.

```tsx
// app/dashboard/emails/page.tsx — a Server Component
import { listEmailCampaigns } from '@uidu/client';
import { uiduAdmin } from '@/lib/uidu-admin';

export default async function EmailsPage() {
  const emails = await listEmailCampaigns(uiduAdmin, { first: 25 });

  return (
    <table>
      <thead>
        <tr>
          <th>Campaign</th>
          <th>Subject</th>
          <th>Delivered</th>
          <th>Open rate</th>
          <th>Click rate</th>
        </tr>
      </thead>
      <tbody>
        {emails.map((e) => (
          <tr key={e.id}>
            <td>{e.campaign?.name}</td>
            <td>{e.subject}</td>
            <td>
              {e.deliveredCount} / {e.sentCount}
            </td>
            <td>{e.openRate}%</td>
            <td>{e.clickRate}%</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}
```

* `uiduAdmin` is the server client built with `apiKey` — see
  [Server integration](https://developers.uidu.org/docs/paths/server-integration.md). Keep this a Server Component (or a route
  handler): the token must not reach the browser.
* The rates are already percentages of *delivered*: compare them with `deliveredCount`, not
  `sentCount`.

### What's going out next

Goal: a weekly report of the campaigns scheduled to send, and what each one targets.

```ts
import { getCampaign, listCampaigns } from '@uidu/client';
import { uiduAdmin } from '@/lib/uidu-admin';

const scheduled = await listCampaigns(uiduAdmin, {
  first: 50,
  status: 'scheduled',
  kind: 'EmailCampaign', // leave out for every channel
});

const report = await Promise.all(
  scheduled.map(async (c) => {
    const full = await getCampaign(uiduAdmin, { id: c.id });
    return {
      name: c.name,
      at: c.scheduledAt,
      list: full?.list?.name, // the target list — only on getCampaign
    };
  }),
);
```

* A listed campaign has `id`, `name`, `innerName`, `status`, `scheduledAt`, `sentAt` and the
  timestamps; the target `list` and the `preferences` JSON come from `getCampaign`.
* From a terminal: `uidu campaigns list --json` and `uidu campaigns get <id> --json`.

## API at a glance

Every `@uidu/client` function in **Campaigns**, generated from the source — the [full reference](https://developers.uidu.org/docs/reference/client.md#campaigns) has the rest of the SDK.

| Function                                                                                              | Kind | Auth   | CLI              | Description                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------- | ---- | ------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [`getCampaign`](https://github.com/uidu-org/api.js/blob/main/packages/client/src/campaigns.ts)        | read | Bearer | `campaigns get`  | One campaign with its `preferences` and target `list`, or null; a public token sees none.                                                      |
| [`listCampaigns`](https://github.com/uidu-org/api.js/blob/main/packages/client/src/campaigns.ts)      | read | Bearer | `campaigns list` | The workspace's campaigns as a flat array, optionally filtered by `kind` and `status`; page with `first`/`after`.                              |
| [`listEmailCampaigns`](https://github.com/uidu-org/api.js/blob/main/packages/client/src/campaigns.ts) | read | Bearer | —                | The email blasts of the workspace's campaigns with their delivery metrics (sent, opened, clicked), as a flat array; page with `first`/`after`. |

**Types:** `Campaign`

**CLI:**

| Entity      | list | get | create | update | delete |
| ----------- | :--: | :-: | :----: | :----: | :----: |
| `campaigns` |   ✓  |  ✓  |    —   |    —   |    —   |