Skip to content
simmailDocs

Universes

A universe is one isolated world. Everything in simmail belongs to exactly one universe:

  • mailboxes and the mail in them
  • logins your apps use for SMTP and IMAP
  • people (personas), their memories and relationships
  • cases
  • the simulated clock
  • the World settings and inbound streams
  • fault rules, webhooks, recipient rules, link rules and retention

Nothing leaks between universes. Dana in your staging universe has never heard of the Dana in your qa universe.

Use one universe per environment or test suite, for example Staging, CI and Demo. A test that skips ahead a week in the CI universe does not move the clock in Staging.

Creating and deleting universes

Section titled “Creating and deleting universes”

Universes belong to an organization. On your account page, go to Universes:

  • New universe creates one. You need the admin role. Your plan sets how many you can have.
  • Rename changes its name. You need admin.
  • Delete removes it with all its mail, people and logins. You need owner. An organization always keeps at least one universe.

Each universe has an id, such as staging-4kq7. The id is fixed; the name can change.

Choosing a universe in a request

Section titled “Choosing a universe in a request”

Your organization’s universes live on one server (a cell), such as c1.simmail.dev. Every API request says which universe it means:

  • With an API key, the key already belongs to one universe. You do not need to name it. If you do name a different one, the request fails with 403 “this API key belongs to another universe”.
  • Signed in as a person (the dashboard, or a browser session), name it with the X-Simmail-Universe header or the ?universe= query parameter. Without either, you get the first universe you can open.
Terminal window
curl -s https://c1.simmail.dev/api/clock \
  -H "Authorization: Bearer smk_your_key" \
  -H "X-Simmail-Universe: staging-4kq7"

To see which universes you can open, and your role in each:

Terminal window
curl -s https://c1.simmail.dev/api/universes \
  -H "Authorization: Bearer smk_your_key"

How mail finds its universe

Section titled “How mail finds its universe”

SMTP and IMAP do not carry a universe id. simmail uses the login: each login name belongs to one universe, so a message sent with app@yourcompany.test’s password lands in that login’s universe.

So a login name can be used once in your organization: creating one that another of your universes already has gives “login name already in use”. Other organizations can have a login with the same name; simmail tells them apart by the password. See SMTP and IMAP.