Import event history

Use explicit backfill mode to import historical server events. Backfill updates history without triggering lifecycle email. This guide covers event history; importing an email design is a separate management action.

Prerequisites

Read the event contract. The integration key needs events:write and history:write. An owner grants the management history:write scope before an agent can create a key with that capability.

Use the installed skill's references/emit.ts as the canonical emitter. Its configuration reads a private integration key from your server environment. Do not expose it in browser code.

Mark history explicitly

In the server integration that already defines emit with createBaruaEmitter, send your validated historical records with:

const result = await emit(historicalEvents, { mode: 'backfill' });
if (!result.ok) {
  throw new Error(`History request failed: HTTP ${result.status}`);
}
const receiptId = (result.body as { receipt_id: string }).receipt_id;

The emitter resolves failures as ok: false; it does not throw. Check the result and save receiptId with your import job before continuing. The default mode is live. Omitting the backfill option changes the meaning of an import. Preserve each event's original occurred_at and stable event_id; do not generate fresh IDs for retries.

Send signed_up first for each person and wait for its receipt to apply before submitting dependent events. The event schema and limits define the required identity and properties. Backfill batches accept at most 1,000 events and 2 MiB.

Wait for application

HTTP 202 means the batch was accepted for processing. Save its receipt_id, then read GET /api/integrations/v1/receipts/{receipt_id} with the same integration key until the result is settled. Follow Send events for the receipt response and error handling.

Report rejected or deferred rows separately. A receipt is stronger evidence than a count of attempted requests, and an accepted receipt is not yet proof that all records were applied.

Verify safely

Use people and profiles to inspect the imported data and workspace diagnostics to examine event outcomes.

Historical events never count as fresh launch proof. Do not replay them in live mode to pass setup checks. A separate authorized fresh event is required for setup verification.