Overview
Every part of a novem e-mail is a file or folder under /v1/vis/mails/:mail. This page maps the whole tree: what lives where, which verbs each path accepts, and where the details are documented.
AI assisted, human approved — novem uses AI to review and keep our documentation up to date.
E-mails follow the same hierarchical file structure
as the rest of the novem API. The canonical path for a mail is
/v1/users/:user/vis/mails/:mail; for your own mails the shorter
/v1/vis/mails/:mail alias works everywhere and is what we use below.
| Path | Verbs | Description |
|---|---|---|
/v1/vis/mails | GET | List your e-mails |
/v1/vis/mails/:mail | PUT | Create a new e-mail with this name |
/v1/vis/mails/:mail | GET | List the e-mail's folder structure |
/v1/vis/mails/:mail | PATCH | Rename the e-mail |
/v1/vis/mails/:mail | DELETE | Delete the e-mail |
| Path | Verbs | Description |
|---|---|---|
.../content | GET POST DELETE | The e-mail body in novem markdown — see content |
.../recipients/to | GET POST DELETE | Primary recipients — see recipients |
.../recipients/cc | GET POST DELETE | Carbon-copy recipients |
.../recipients/bcc | GET POST DELETE | Blind-carbon-copy recipients |
Every key under .../config/ is a plain-text file: GET reads it, POST
writes it, DELETE resets it to its default. The keys (subject, size,
theme, type, reply_to, enabled, comments) are documented on the
config page.
| Path | Verbs | Description |
|---|---|---|
.../status | GET POST | Trigger a send (sent / test) and poll its state — see sending |
.../stats/runs | GET | Send history: one row per send with time, duration and status |
.../log | GET | The e-mail's activity log — recipient changes, send attempts, errors |
| Path | Verbs | Description |
|---|---|---|
.../files/ | GET | Rendered outputs: mail.txt, mail.ansi, mail.pdf, mail.png, mail.pptx — see renders |
.../assets/ | GET | List uploaded assets |
.../assets/:asset | GET POST DELETE | Upload, fetch or remove an asset (images and fonts, max 5 MiB each, 25 per e-mail) |
Assets are referenced from the content with the
img section. Uploads accept image/png,
image/jpeg, image/gif, image/svg+xml, image/webp and the
font/woff, font/woff2, font/ttf, font/otf font types. Asset names are
lowercase alphanumeric with - separators and an optional extension
(logo.png, brand-font.woff2), at most 64 characters.
| Path | Verbs | Description |
|---|---|---|
.../name | GET POST DELETE | Display name |
.../description | GET POST DELETE | Longer description |
.../summary | GET POST DELETE | Short summary |
.../shortname | GET | The auto-generated shortname (read-only) |
.../url | GET | The e-mail's web url (read-only) |
.../json/ | GET | Read-only system files: config.json, data.json, meta_data.json |
These work the same on e-mails as on every other novem visual:
| Path | Description |
|---|---|
.../shared/ | Who can view the e-mail on the web — add public, +org~group or @user~group entries with PUT, list with GET, revoke with DELETE |
.../tags/ | Tagging — see tags |
.../vars/ | Attach metadata variables — see vars |
.../threads/ | Comment threads on the e-mail's web page (toggle with config/comments) |
.../notifications | Your personal notification level for this e-mail: ignore, info or important |
Note: entries in shared/ control who can view the e-mail render on the
web. They are unrelated to who receives the e-mail. Recipients live under
recipients/.
Each e-mail is also reachable at /v1/u/:user/m/:mail, a compact, read-only
view of the rendered output that honours the e-mail's sharing settings. See
renders for the full list of
formats.