Campaigns

• Use it for: Server integration
• 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

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 (ListCampaignsDocument, ListEmailCampaignsDocument). A client with a public token sees none — an empty list is first a sign of the wrong token (Authentication).

Use cases

Email performance dashboard

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

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

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 has the rest of the SDK.

Types: Campaign

CLI: