Personas

See People for what each field does.

GET /api/personas

Every persona in the universe, sorted by name.

POST /api/personas

Creates a persona. addresses needs at least one address, and an address can belong to only one persona. Anything you leave out gets a default: a temperament drawn at random, knows: "some", a mail client drawn at random.

curl -s -X POST https://c1.simmail.dev/api/personas \
  -H "Authorization: Bearer smk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dana Reyes",
    "addresses": ["dana@harbor.test"],
    "role": "homeowner",
    "org": "",
    "who": "Retired teacher selling the family home on Clark Street",
    "wants": "a fair price and a quick, simple sale",
    "temperament": "skeptical",
    "style": { "length": "short", "formality": "neutral", "signature": "Dana", "client": "iphone", "links": "wary" },
    "timing": {
      "reply_rate": 0.9,
      "delay": { "median": "2h", "spread": 1.8 },
      "hours": { "tz": "America/Chicago", "days": "mon-fri", "from": "09:00", "to": "17:00" },
      "ooo": [{ "from": "2026-12-20", "to": "2027-01-02", "message": "Away for the holidays." }]
    },
    "behaviors": { "double_reply": 0.1, "keep_promises": 0.5 },
    "external_ids": { "crm": "c-1042" }
  }'

The answer is the saved persona, with its new id (such as p_3fa2b1c9d0), provider (api) and created. Creating one also makes its mailbox.

All fields

Field	Type
name, role, org, who, wants, character	text
addresses	list of addresses; the first is the one they write from
knows	all, some, little
temperament	responsive, busy, procedural, skeptical, flaky, difficult, ghost
case_ids	cases they are on
style.length	short, medium, long
style.formality	casual, neutral, formal
style.typos	0 to 1
style.signature	text
style.client	gmail, outlook, apple, iphone, android, plain
style.links	usual, curious, wary, never
style.filter	strict, normal, lenient, none
style.access	screen_reader, low_vision
timing.reply_rate	0 to 1
timing.delay.median	duration, such as "45m"
timing.delay.spread	1 or more
timing.hours.tz, .days, .from, .to	"Europe/Paris", "mon-fri", "08:30", "17:30"
timing.ooo	list of {from, to, message}
behaviors.double_reply, .bounce, .cc_someone	0 to 1
behaviors.forward_to	persona id or address
behaviors.keep_promises	0 to 1
external_ids	your ids, {"system": "id"}
paused	true turns their AI off
id, provider, created	set by simmail

provider says where a persona came from: api, case, stranger, world, mail or config (a YAML file).

GET /api/personas/{id}

One persona. 404 if there is none.

PATCH /api/personas/{id}

Changes only the fields you send. PUT does the same.

curl -s -X PATCH https://c1.simmail.dev/api/personas/p_3fa2b1c9d0 \
  -H "Authorization: Bearer smk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"paused": true}'

A nested object you send replaces that whole object: sending {"style": {"links": "never"}} clears the person’s other style settings. Read the persona first and send the whole style, timing or behaviors object.

Personas from YAML files cannot be changed through the API (409).

DELETE /api/personas/{id}

Deletes the persona with its memory, relations and pending jobs. Its mailbox and mail are kept.

POST /api/personas/from-mail

Learns a persona from an address’s mail in this universe. See Learning a person from mail.

{ "address": "sam@yourcompany.test", "paused": false }

Answer: {"persona": {…}, "by": "ai", "people": 4}, where people is how many correspondents they already know. Counts toward your plan’s monthly “learned from mail” allowance.

GET /api/temperaments

The temperaments, with name, weight (odds when drawn), reply_rate, median_delay and text.

Memory

Call	What it does
GET /api/personas/{id}/memory	Their memory, by case id. The key "" is everything outside a case.
POST /api/personas/{id}/memory	Adds a note. Body: text (required), case_id, source. With a source, the note is stored as (source) text.
DELETE /api/personas/{id}/memory	Clears all of it, or only one case’s memory with ?case_id=….
POST /api/memory/by-external	Adds a note to the persona with your id for them. Body: system, id, text (all required), case_id, source (defaults to system).

curl -s -X POST https://c1.simmail.dev/api/memory/by-external \
  -H "Authorization: Bearer smk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"system": "crm", "id": "c-1042", "text": "Called the office to ask about closing costs."}'

Relations

Call	What it does
GET /api/personas/{id}/relations	{"relations": […], "stances": […]}: what they hold about each correspondent. See relationships.
DELETE /api/personas/{id}/relations?address=…	Forgets one correspondent. Without address, forgets everyone.