Clock and jobs

See The simulated clock for how time works.

Clock

Each call answers with the clock’s state, {now, speed, frozen, real}, except advance.

Call	Body	What it does
GET /api/clock		Reads the clock.
POST /api/clock/speed	{"factor": 60}	Runs time at that multiple of real time. 0 freezes it. Must be 0 or more.
POST /api/clock/freeze		Stops time.
POST /api/clock/advance	{"duration": "2h"}	Moves time forward and runs everything due on the way.
POST /api/clock/live		Back to real time, at 1×.

advance answers with {"clock": {…}, "jobs_run": 4}. duration is a string more than zero, such as "90m", "2h" or "3d".

curl -s -X POST https://c1.simmail.dev/api/clock/advance \
  -H "Authorization: Bearer smk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"duration": "3d"}'

Jobs

A job is something planned for later: a reply, a follow-up, an out-of-office answer, a bounce notice, a promised email, a nudge, a new thread, or the next email from an inbound stream. In the dashboard, they are under Activity.

GET /api/jobs

Parameter	Default	Meaning
state	all	pending, done, skipped or failed.
limit	200	How many.

{
  "now": "2026-10-10T14:00:00Z",
  "jobs": [
    {
      "id": 128,
      "state": "pending",
      "due": "2026-10-10T15:12:00Z",
      "created": "2026-10-10T14:00:00Z",
      "kind": "reply",
      "persona_id": "p_3fa2b1c9d0",
      "persona": "Dana Reyes",
      "case_id": "deal-1701",
      "to": ["app@yourcompany.test"],
      "plan": "skeptical, reply reply after ~1h12m0s",
      "inbound": { "subject": "Your house on Clark Street", "from": "app@yourcompany.test", "text": "…" }
    }
  ]
}

Field	Meaning
kind	reply, followup, correction, ooo, bounce, dsn (a bounce notice), initiate, deliver (a kept promise), nudge or world.
plan	Why it was planned, in words.
note	After it ran: what happened, such as “sent reply to app@yourcompany.test (ai)” or “decided not to reply (ai)”.
inbound	The email it answers, with its text cut short.
due, ran	When it is due and when it ran, in simulated time.

Acting on a pending job

Call	What it does
POST /api/jobs/{id}/run-now	Runs it now.
POST /api/jobs/{id}/skip	Skips it.
POST /api/jobs/{id}/bounce	Turns a planned reply into a bounce and runs it now.
PATCH /api/jobs/{id}	Reschedules it: {"due": "2026-10-11T09:00:00Z"} or {"in": "10m"} from now.

A job that is not pending answers 400 “job 128 is done”.