Mail and mailboxes

Every address that receives mail has a mailbox. Persona mailboxes and your app’s mailboxes are read the same way.

Addresses in paths are plain, such as /api/mailboxes/dana@harbor.test/folders.

Mailboxes

`GET /api/mailboxes`

Every mailbox in the universe. Mailboxes without a persona come first, then personas’, each sorted by address.

[
  { "address": "app@yourcompany.test", "display_name": "Acme App", "can_login": true, "unread": 1, "total": 3 },
  { "address": "dana@harbor.test", "can_login": false, "unread": 2, "total": 4, "persona_id": "p_3fa2b1c9d0", "persona": "Dana Reyes" }
]

`GET /api/mailboxes/{address}/folders`

Its folders: name, special_use (such as \Sent), total and unread. INBOX, Sent, Drafts, Archive and Trash come first.

`PUT /api/mailboxes/{address}/status`

Forces how the address behaves as a recipient. Body: {"status": "full"}. Status is ok (clears it), unknown, domain, full, disabled or blocked. See recipient rules.

Messages

`GET /api/mailboxes/{address}/messages`

The messages in one folder, newest first. The text of each is cut to its first 240 characters.

Parameter	Default	Meaning
`folder`	`INBOX`	Such as `Sent`, `Junk`, `Archive`.

Each message has:

Field	Meaning
`uid`, `folder`	Where it is. Use them in the paths below.
`flags`	IMAP flags, such as `\Seen`.
`time`, `size`	When it was filed and its size in bytes.
`message_id`, `in_reply_to`, `references`	Threading headers.
`from`, `from_name`, `to`, `cc`, `subject`, `date`	The usual headers.
`text`, `html`	The bodies.
`format`	What the sender’s client produced: `text`, `html` or `both`.
`attachments`	Each with `filename`, `content_type`, `size`, and `content_id` and `inline` for inline images.
`headers`	`X-Simmail-*` headers. Mail written by simmail carries `x-simmail-simulated`.

`GET /api/mailboxes/{address}/messages/{folder}/{uid}`

One message in full:

{
  "message": { "uid": 3, "folder": "INBOX", "subject": "Re: Your house on Clark Street", "text": "…", "…": "…" },
  "safe": { "html": "<div>…</div>", "remote_blocked": 2 },
  "case": { "id": "deal-1701", "how": "matched on sender and content" }
}

Field	Meaning
`message`	As above, with the full text. For HTML mail, `html` is left empty here: use `safe`, or `/raw` for the original.
`safe`	The HTML made safe to display (`html`): scripts, forms and frames removed, remote images blocked. `remote_blocked` counts the blocked images.
`case`	For a persona’s mailbox: the case simmail linked the thread to, and how.

Parameter	Meaning
`remote=1`	Allow remote images in `safe`.
`theme=light`	Do not adapt `safe` for dark mode.

`GET /api/mailboxes/{address}/messages/{folder}/{uid}/raw`

The original message as message/rfc822.

`GET /api/mailboxes/{address}/messages/{folder}/{uid}/attachments/{n}`

Attachment number n, counting from 0 in the order of attachments, with its content type and filename.

`PATCH /api/mailboxes/{address}/messages/{folder}/{uid}`

What a mail client does to a message: mark it read or unread, move it.

{ "seen": true, "move_to": "Archive" }

Both fields are optional.

`GET /api/threads?address={address}`

The mailbox’s INBOX, Sent and Archive grouped into conversations, most recent first. Each thread has root, subject, last and its messages, oldest first.

Sending

`POST /api/send`

Sends a message exactly as SMTP would: a copy in the sender’s Sent folder, one in each recipient’s INBOX, and people plan their replies. Faults do not apply.

curl -s -X POST https://c1.simmail.dev/api/send \
  -H "Authorization: Bearer smk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "app@yourcompany.test",
    "to": ["dana@harbor.test"],
    "subject": "Contract attached",
    "text": "Hi Dana, the contract is attached.",
    "attachments": [{ "filename": "contract.pdf", "content_type": "application/pdf", "data": "JVBERi0xLjQK…" }]
  }'

Field	Required	Meaning
`from`	yes	The sending address.
`to`	yes	Recipients (a list).
`cc`		Copies.
`subject`		The subject.
`text`		Plain-text body. Made from the HTML when left out.
`html`		HTML body. Images given as `data:` URLs become inline attachments.
`attachments`		Each with `filename`, `content_type` and `data` (base64).
`in_reply_to`		A Message-ID: threads this as a reply.
`references`		Message-IDs for the `References` header.
`forward`		`{"address", "folder", "uid"}`: carries that message’s attachments along.

Answer: {"status": "sent", "message_id": "<…>"}.

`POST /api/inject`

Files a message straight into a mailbox, skipping SMTP. Nobody is told and nobody replies: use it to set up a mailbox’s history.

{ "to": "dana@harbor.test", "folder": "INBOX", "from": "old-agent@brooks-realty.test", "subject": "Listing paperwork", "text": "Here are the forms." }

Send either raw (a whole RFC 5322 message) or from, subject and text. folder defaults to INBOX.

Signatures

Call	What it does
`GET /api/accounts/{address}/signature`	`{"signature": "…"}` for that address.
`PUT /api/accounts/{address}/signature`	Sets it. Body `{"signature": "Sam\nAcme Realty"}`. Admin role.

Waiting

Call	What it does
`GET /api/wait`	The next email to an address.
`GET /api/wait/reply`	The next email a persona sends.
`POST /api/extract`	Codes and links from any text.

See the wait API for parameters and answers.