The endpoint

Your whole customer backend is one POST request. Every call carries a person and a payload, aimed at an actionyou named in the dashboard. postact merges the person, runs the action's steps — reply with an email, run a script, close it, or leave it open for you — and everything becomes filterable.

POST <your-postact-host>/api/p/<project>/a/<action>
Authorization: Bearer sk_…        (or pk_… from the browser)
Content-Type: application/json

{
  "person": {
    "email": "mara@gmx.at",
    "identifiers": { "session": "s_8841", "id": "u_102" },
    "metadata": { "name": "Mara Kern", "plan": "trial", "affiliateCode": "KURT" }
  },
  "payload": { "source": "landing/b" }
}

The call is validated and queued, then returns immediately with 202 { "ok": true, "job": "<id>" }. A runner picks the job up moments later and does the work, in order: 1. the person is upserted and fully merged. 2.the action's steps run. That's the entire integration surface — signup, support form, page view, password reset, a lead from a landing page: same call, different action name.

The two keys

  • sk_… — the secret key, for your backend. Full power; can call any POST-triggered action. Find it in Settings → Keys (shown once, rotate any time).
  • pk_… — the public key, safe to ship in the browser. Accepted only for actions with a Webhook (Client) trigger, and only from origins you allowlist on that action (localhost always works for testing). The secret key proves who you are; the public key proves where the call came from.

The CLI

Everything on this page is also a command. That is how a coding agent builds a project: it reads the machine-readable guide and creates the templates, actions and views itself, no browser involved.

npm i -g @postact-js/cli
postact login              # device-code login, works headless
postact projects use acme  # pick the project everything else acts on
postact actions ls --json  # --json on everything a machine reads
  • projects · actions · people · events · filters · templates — the daily loop: create an action, watch its runs, work the open queue.
  • emails · keys · vault · domains · collaborators · branding · project — the sent log and everything under Settings.

The full reference is postact.app/docs/cli.md — plain markdown, served verbatim, meant to be curled. It documents every verb, how to build an action from the CLI, the three shapes an action takes (transactional mail, contact mail, analytics) and how to wire up analytics without burying your support queue. Offline, postact help <group> prints the same table and postact help --json prints it as JSON.

People — merged, not synced

There is no sync and no import. A person is the sum of every call that mentioned them. Any matching identifier or email finds the existing person; metadata and identifiers merge fully, latest value per key wins (keys written with the secret key can't be overwritten from the client). Email is the anchor — a known identifier arriving with a different email starts a new person rather than silently rewriting one. And {"person":{"email":null}} soft-deletes: the API that created them removes them.

Metadata is the whole schema — plan, company, cohort: all just keys you chose to send, shown as-is on the person's card. Two keys get special treatment if present: name becomes the card title and last_seen_at (ISO timestamp) powers the activity chip.

Actions — a trigger plus what happens

An action is a name plus two settings: a trigger (when it runs) and ordered steps (what happens).

  • Manual — you run it from the dashboard against a saved filter (a marketing email to everyone on trial, say).
  • Webhook (Server) — sk_… from your backend; the caller decides when.
  • Webhook (Client) — pk_… straight from the browser, origin-locked.
  • Scheduled — runs on a timer for everyone matching a saved filter (daily 09:00 · filter: Trial ending).

Steps: reply email [template], script, mark closed. Every call creates an event; events without a close step sit open in the queue — that's your support inbox. A reply to any email you sent routes back to the same action and reopens the event.

A script is JavaScript that runs when the step is reached, in an isolated QuickJS interpreter with no network, no filesystem and no timers (250ms, 32MB). It gets four things — person, payload, event and env (your vault secrets, readable there and nowhere else) — and it can do two: person.set(key, value) writes back to the person, and whatever it returns fills the socket a step points at (which template to send, which address to send it to) — and it has to fit: an address that is not one, like a template id that names nothing, skips that step rather than sending. A script that fails or runs out of time costs its own step and nothing else; the run carries on, and the queue shows you what it printed.

Emails — templates with holes

Subject: Your reset link

Hi {{person.metadata.name}},
here is your password reset link: {{payload.link}}

{{person.metadata.*}} is what you know about them; {{payload.*}} is what this call brought. Every send leaves from your verified project domain in your branding and lands in the sent log. Mark payload keys like link or otp_code as transienton the action and they're scrubbed to [REDACTED] before the event is stored — used for the email, never kept.

Wiring up a product

// backend — wherever these things happen
await fetch(`${POSTACT}/api/p/surveyor/a/signup`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.POSTACT_SK}`,
             "Content-Type": "application/json" },
  body: JSON.stringify({
    person: { email: user.email, identifiers: { id: user.id },
              metadata: { name: user.name, plan: "trial" } },
    payload: {},
  }),
});

// browser — contact form, public key
await fetch(`${POSTACT}/api/p/surveyor/a/support`, {
  method: "POST",
  headers: { Authorization: "Bearer pk_…", "Content-Type": "application/json" },
  body: JSON.stringify({
    person: { email: form.email },
    payload: { message: form.message },
  }),
});

A new project already resets passwords, acknowledges support and welcomes signups before you've styled anything — the defaults are normal actions and templates: rename, edit, delete.

Read/write API

The /a/<action> path is one endpoint; alongside it, people and actions have a plain REST API for reading and managing them. Server key only (sk_…) — these aren't for the browser.

# people
GET    /api/p/<project>/people?limit=50&offset=0&email=…
POST   /api/p/<project>/people           { email, identifiers?, metadata? }
GET    /api/p/<project>/people/<id>       → { person, identifiers }
PATCH  /api/p/<project>/people/<id>       { email?, metadata?, removeKeys? }
DELETE /api/p/<project>/people/<id>       (soft — frees identifiers, keeps history)

# actions (recipes)
GET    /api/p/<project>/actions
POST   /api/p/<project>/actions          { name, slug, trigger, steps, … }
GET    /api/p/<project>/actions/<id>
PATCH  /api/p/<project>/actions/<id>      (full replace)
DELETE /api/p/<project>/actions/<id>

POST to /people follows the same merge rules as a signal — same email or identifier means the same person, never a duplicate.