Cases

A case is a shared situation several people belong to: a house sale, a support ticket, an insurance claim. Your system pushes what it knows. simmail writes the story, what is actually true, once, and the people on the case stay consistent with it.

Pushing a case

PUT /api/cases/{id} creates or updates a case. The id is yours, for example your deal’s id:

curl -s -X PUT https://c1.simmail.dev/api/cases/deal-1701 \
  -H "Authorization: Bearer smk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sale of 1701 Clark Street",
    "kind": "real estate",
    "facts": { "address": "1701 Clark Street", "asking_price": 175000 },
    "people": [
      { "ref": "seller", "name": "Dana Reyes", "role": "seller", "addresses": ["[email protected]"] },
      { "ref": "agent", "name": "Tom Brooks", "role": "listing agent", "addresses": ["[email protected]"] }
    ],
    "notes": ["The roof was replaced in 2021."]
  }'

Field	Meaning
title, kind	What the matter is.
facts	Things that are true, as key and value.
known	What your system knows or believes, as key and value.
people	The people on the case. ref is your own stable handle for each.
notes	Extra notes. New ones are added; repeats are ignored.
directions	How you want the story to go, in plain words.

The first push writes the story (with AI, or a template). Every person with an address is cast: simmail creates a persona for them, or reuses the one already at that address, and puts them on the case. simmail fills in who they are, what they want and how much they know (who, wants, knows) unless you give them when you first add the person. On later pushes you can still steer temperament and character.

The answer lists the people and their persona ids, but never the story:

{
  "id": "deal-1701",
  "title": "Sale of 1701 Clark Street",
  "people": [
    { "ref": "seller", "name": "Dana Reyes", "persona_id": "p_3fa2b1c9d0", "addresses": ["[email protected]"] },
    { "ref": "agent", "name": "Tom Brooks", "persona_id": "p_8c41d2e7aa", "addresses": ["[email protected]"] }
  ],
  "story_written_by": "ai"
}

Pushing again

Later pushes merge in: facts and known values are updated, people are matched by ref (or by address) and updated, and new people are cast. When facts change, the story is amended, never rewritten, so nobody contradicts what they already said.

The story is the answer key

The story is never sent in any email. Only the dashboard and GET /api/cases/{id} can read it, so your tests can check your app against what is really true. Use GET /api/cases/{id}?redact=story to read a case without it.

Which case an email is about

Nothing in an email names a case. A person works it out the way a real person would: from who sent it and what it says (the title’s words, fact values such as an address or order number, and people’s names). If that is not clear, the AI chooses. A thread keeps the case it was first given.

How much of the story each person knows depends on their knows setting: all, some or little.

Starting a thread from a case

A person on a case can write first:

curl -s -X POST https://c1.simmail.dev/api/cases/deal-1701/initiate \
  -H "Authorization: Bearer smk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"persona": "[email protected]", "to": "[email protected]", "intent": "ask whether the offer is still open", "after": "2h"}'

after is how long to wait on the simulated clock. See the Cases API for every endpoint.

Deleting a case

Deleting a case removes its people’s memory of it and their pending work on it. People who were created for this case alone are deleted too.