The World module

Real companies do not only send mail; the world writes to them too. The World module gives a universe a company profile and inbound streams: mail that arrives on its own, at a set rate, on the simulated clock.

The company

Field	Meaning
name, domain	For example Acme Realty, acme-realty.test.
website, industry, offer, location	Who it is and what it sells or does. Senders are invented to fit.
tz	The company’s time zone, for business hours, such as America/Chicago.
mailboxes	Its addresses, each with an address, a role (sales, support, owner, billing, info …) and an optional name.

Inbound streams

A stream is one kind of mail the world sends.

Field	Meaning
id	Set by simmail when you leave it out.
name	Your label.
kind	lead, support, vendor, partner, customer, newsletter, spam, phishing or custom.
to	Which company mailboxes it goes to (one is picked at random each time).
per_day	How many a simulated day, on average (up to 500). Arrivals are random, like real mail.
business_hours	Only Monday to Friday, 08:00 to 18:00, in the company’s time zone.
brief	What these emails are about, in plain words.
new_people	Share (0 to 1) from people never heard from before. The rest come back from people this stream brought before.
enabled	Whether it runs. An enabled stream needs a rate above 0 and at least one mailbox.
sent, next	Read only: emails sent so far, and when the next one is due (simulated time).

How each kind behaves:

• lead, support, vendor, partner, customer, custom come from people. A new sender is invented to fit the company and the brief, and becomes an ordinary persona. When your app answers, they reply, remember, promise and follow up like anyone else.
• newsletter, spam, phishing come from senders who never answer. They are filed straight into the mailbox. Newsletters carry a List-Unsubscribe header.

Setting it up

In the dashboard, go to World. With the API, PUT /api/world replaces the whole world (admin role):

curl -s -X PUT https://c1.simmail.dev/api/world \
  -H "Authorization: Bearer smk_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "company": {
      "name": "Acme Realty",
      "domain": "acme-realty.test",
      "industry": "real estate",
      "offer": "helps families buy and sell homes in Chicago",
      "tz": "America/Chicago",
      "mailboxes": [
        { "address": "sales@acme-realty.test", "role": "sales" },
        { "address": "help@acme-realty.test", "role": "support" }
      ]
    },
    "streams": [
      { "name": "Website leads", "kind": "lead", "to": ["sales@acme-realty.test"], "per_day": 6,
        "business_hours": true, "brief": "asking about homes for sale", "new_people": 0.8, "enabled": true },
      { "name": "Spam", "kind": "spam", "to": ["sales@acme-realty.test", "help@acme-realty.test"], "per_day": 3, "enabled": true }
    ]
  }'

To try a stream at once, without changing its schedule:

curl -s -X POST https://c1.simmail.dev/api/world/streams/s_9a8b7c6d5e/send \
  -H "Authorization: Bearer smk_your_admin_key"

Plan limits

Your plan caps how many streams can be enabled at once and how many inbound emails arrive a day (UTC). Inbound mail also uses AI actions: one to write each email, and one more to invent each new sender.

Insights counts inbound emails in its inbound total. Each one is also a world.mail event.