Insights and shared reports

Insights shows what happened to the mail your app sent over a period: per campaign and in total. A campaign is all the emails sharing a subject; replies and forwards (Re:, Fwd: …) count with the email they answer.

Insights needs the insights feature of your plan. Without it, the API answers 402.

Reading insights

curl -s "https://c1.simmail.dev/api/insights?days=30" \
  -H "Authorization: Bearer smk_your_key"

days is the period, counted back from now on the universe’s simulated clock: 1 to 366, default 30.

{
  "from": "2026-09-10T09:00:00Z",
  "to": "2026-10-10T09:00:00Z",
  "total": { "subject": "All campaigns", "sent": 40, "recipients": 40, "junked": 3, "bounced": 1, "seen": 36,
             "replied": 22, "declined": 9, "clicked": 14, "looked_up": 5, "reply_rate": 0.61 },
  "campaigns": [
    { "subject": "Spring open house", "sent": 30, "recipients": 30, "junked": 3, "bounced": 1, "seen": 26,
      "replied": 15, "declined": 8, "clicked": 12, "looked_up": 4, "reply_rate": 0.58 }
  ],
  "moods": { "warm": 9, "neutral": 18, "wary": 4, "annoyed": 2, "done": 1 },
  "promises": { "made": 7, "slipping": 2, "awaited": 3, "nudges": 1 },
  "inbound": 12
}

Field	Meaning
sent	Emails your app sent.
recipients	People they went to.
junked	Filed as spam by a person’s provider, never seen.
bounced	Bounced by a dead, full or blocking address.
seen	Reached a person’s inbox.
replied	Replies people wrote.
declined	People who saw it and chose not to answer.
clicked	Links people opened.
looked_up	Times people looked up the sender’s website.
reply_rate	replied divided by seen.
moods	How the people your mail reached now feel about your addresses. See relationships.
promises	Promises people made to you (made, of which slipping will not be kept), promises you made that they are waiting on (awaited), and chasers they sent (nudges).
inbound	Emails the World sent on its own.

Campaigns are sorted by emails sent, most first. A campaign appears only if your app sent at least one email in the period.

Sharing a report

You can share a read-only report with anyone, by link, without giving them an account. Each share has a title and a period.

curl -s -X POST https://c1.simmail.dev/api/insights/shares \
  -H "Authorization: Bearer smk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Spring campaign", "days": 30}'

{ "path": "/share/shr_5f1c0e…", "token": "shr_5f1c0e…" }

The report lives on your universe’s server: https://c1.simmail.dev/share/shr_5f1c0e…. Its data is also at the same address with .json added. Both are computed fresh each time they are opened, over the shared period up to now.

Call	What it does
GET /api/insights/shares	Lists the universe’s shares: token, title, days, created.
DELETE /api/insights/shares/{token}	Revokes one. The link stops working at once.

A shared report also stops working if your organization’s plan no longer includes insights.