People (personas)

A persona is a simulated person behind one or more addresses. When your app emails them, they decide whether to answer, when, and what to say, in character.

What a persona is made of

Field	Meaning
name, addresses	Who they are and where they get mail. The first address is the one they write from. At least one address is required.
role, org	For example homeowner, Harbor Realty.
who, wants	A sentence about them and what they want. The AI writes from these.
character	Free-form personality notes.
knows	How much of a case story they know: all, some (default) or little.
temperament	Their default behaviour (below). Drawn at random if you leave it out.
style	How they write and read mail (below).
timing	Reply rate, delay, working hours and out-of-office (below).
behaviors	Habits such as double replies or looping someone in (below).
paused	true turns their AI off (below).
external_ids	Your own ids for them, such as {"crm": "c-1042"}.

See the Personas API for creating and editing them.

Temperaments

A temperament sets a person’s default reply rate and how long they usually take. When simmail invents a person and nobody chose, it draws a temperament with these odds, so most correspondents are busy, as in life.

Temperament	Odds	Reply rate	Typical delay	How they write
responsive	15%	95%	12 min	Prompt and full; answers every question.
busy	25%	85%	1 h 15 min	Late and brief, often only part of the question.
procedural	15%	90%	45 min	Polite, wants the right forms or reference numbers first.
skeptical	15%	80%	1 h	Questions the premise and wants proof.
flaky	15%	60%	3 h	Agrees, then forgets; needs reminding.
difficult	10%	75%	1 h 30 min	Pushes back, negotiates hard, escalates.
ghost	5%	15%	24 h	Rarely replies; one line, days later.

An unknown temperament name behaves as busy. GET /api/temperaments returns this table.

Whether they reply

When mail from your app reaches a persona, simmail decides:

1. Reply rate. For a first, cold email, the chance is timing.reply_rate if set, else the temperament’s rate.
2. Ongoing conversations. Someone who has already written in the thread answers at least 97% of the time.
3. Follow-ups. Each extra unanswered email from the same sender in the thread makes an answer more likely.
4. How they feel about you. A person who feels warm answers at least 90% of the time; wary cuts the chance a little, annoyed more, and done almost to nothing (8%). See Memory, relationships and promises.
5. A pile of mail. If they already plan to reply to you, a new email from you is answered in that same reply.

When they decide not to answer, the Activity log says why. Even when simmail plans a reply, the AI may still decide, in character, not to send one.

When they reply

• Delay. A delay is drawn around the temperament’s typical delay (or timing.delay.median), with some people much faster or slower than usual. timing.delay.spread widens or narrows that (1 or more). No reply comes sooner than 20 seconds.
• Working hours. Replies move into the person’s working hours: timing.hours with tz, days (mon-fri, mon,wed,fri or all), from and to. The default is Monday to Friday, 08:30 to 17:30. A reply that falls outside them goes out a little after the next opening.
• Out of office. In a timing.ooo window (from, to and an optional message), they send an automatic reply within a minute and their real reply after they are back. Dates are 2026-05-01 (whole days) or RFC 3339 times.
• Pace. The universe’s pace setting scales every delay and can ignore working hours. See Behaviour settings.

All of this runs on the universe’s simulated clock. In a test you rarely wait: GET /api/wait/reply?fast=true has the person write their due reply at once.

Style

Field	Values	Effect
style.length	short, medium, long	Reply length.
style.formality	casual, neutral, formal	Tone.
style.typos	0 to 1	How many typos they make.
style.signature	text	How they sign off.
style.client	gmail, outlook, apple, iphone, android, plain	How their mail looks: HTML or plain text, how they quote, what their phone appends. Drawn at random if unset.
style.links	usual, curious, wary, never	Whether they click links. See Links and sender look-up.
style.filter	strict, normal, lenient, none	Their mail provider’s spam filter. See Junk and spam.
style.access	screen_reader, low_vision	How they take in mail. A screen-reader user responds to what the screen reader read out; a low-vision reader notices text that is too small or faint.

Behaviours

Field	Meaning
behaviors.double_reply	Chance (0 to 1) they send a second email a few minutes after the first, correcting or adding something.
behaviors.bounce	Chance (0 to 1) their mailbox bounces your email instead.
behaviors.cc_someone	Chance (0 to 1) they copy another person on the case into their reply.
behaviors.forward_to	A persona id or address they always copy on replies.
behaviors.keep_promises	How reliably (0 to 1) they do what they promised. Unset, it follows their temperament.

AI or templates

People write with AI. Each reply, each case story, each inbound email from the World and each file read is one AI action, counted by your plan. See what uses AI actions.

People set to AI model: better write with a stronger model, using the plan’s premium actions; when those run out they use the standard model.

When AI is not available, templates stand in: short replies in the temperament’s voice. This happens when your plan’s AI actions for the month are used up, when the AI fails. The by field of a persona.sent event says which wrote the reply: ai, template, or template (AI failed: …). Template replies always answer; they do not read links, notice attachments’ contents or make promises.

Strangers

When your app writes to an address that nobody plays and that has no login, simmail can put someone behind it on the spot. This stranger gets a name from the address (jordan.hale@ becomes Jordan Hale), a temperament drawn by the odds above, and then answers like any persona. In ai mode, who they plausibly are is decided in the same AI call as their first reply, so a stranger who never answers costs no AI action. Until then the dashboard shows them as a sketch.

Who is behind a never-seen address is part of the universe’s recipient rules: off, basic or ai. Each stranger counts toward your plan’s people limit.

Tip

In automated tests that sign up thousands of throwaway users, turn strangers off for your test domain so they do not use up people and AI actions. See the CI guide.

Mail between people

Mail one persona sends another is filed, but it never sets the other off. Two simulated people cannot get into a loop. People only answer mail from operators: your app and you.

AI off: writing as a person yourself

Set paused: true (in the dashboard, the AI on / AI off switch). While paused, a person answers nothing, and mail you send as them counts as yours, so you can write as Dana yourself, then hand her back to the AI.

Learning a person from mail

Any address that has sent and received mail in the universe can become a persona. simmail reads everything that address wrote and received and builds a persona who writes like them, wants what they were after, and already knows the people they deal with. Use Make an AI from their mail in the dashboard, or POST /api/personas/from-mail. Each one counts toward your plan’s monthly “learned from mail” allowance.