Skip to content

Content

This document explains the structure and content format for novem e-mails.

AI-assisted, human-approvednovem uses AI to review and keep our documentation up to date.

Structure

An e-mail's body is stored in /v1/vis/mails/<id>/content as Novem Markdown. Recipients, subject, and other settings are stored separately; see the e-mail API reference.

Blocks

Novem Markdown blocks embed visuals and format content. See the block syntax reference for common parameters.

Supported blocks include:

  • Preview — preview text for inbox list views
  • Paragraph — styled text blocks with font size, style, alignment
  • Visualisation — embed novem plots and grids
  • Callout — info, warning, error and success callout boxes
  • Author — author information blocks

Preview text

The preview block provides a short preview text that will only be visible in the list view of e-mail clients. It will not render in the e-mail body.

{{ preview }}
A short preview text that will show up in the list view.
{{ /preview }}

Embedding visualisations

Novem plots and grids can be embedded directly in your e-mail using the vis block.

{{ vis
  ref: /u/novem_demo/p/state_pop
  width: 100%
  align: center
  title: false
  caption: true
}}

See the visualisation block for full details on reference formats and options.

Embedding images

Static images (logos, diagrams, photos) are embedded with the image block. The image itself is uploaded as an asset on the mail first:

curl -X POST -H "Authorization: Bearer $NOVEM_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @logo.png \
  https://api.novem.io/v1/vis/mails/daily_email_summary/assets/logo.png

and then referenced by name in the content:

{{ img ref: logo.png }}

Assets accept image types (png, jpeg, gif, svg, webp) and web fonts. See Size limits for upload limits. Images are included in the outgoing e-mail rather than loaded from a remote URL when the recipient opens it.

Sending an e-mail

POST sent to the status endpoint to queue delivery to valid recipients in the recipients folder (To, Cc, and Bcc). For test sends, rate limits and how to follow a send's progress, see sending.

Examples

Weekly summary

Save this fictional task summary as email.md:

{{ preview }}
Example project: 20 of 25 tasks completed this week.
{{ /preview }}

# Example weekly summary

The fictional project completed 20 tasks this week. The remaining 5 tasks
are scheduled for next week.

{{ table }}
| Status | Tasks |
|---|--:|
| Complete | 20 |
| Scheduled | 5 |
{{ /table }}

Create the e-mail, upload the content, and send a test to yourself:

novem -m example_report -C
novem -m example_report --subject "Example weekly summary"
novem -m example_report -w content @email.md
novem -m example_report -T

The e-mail quick start also shows how to embed a plot, set recipients, and send the completed e-mail.

File attachments

Use an attachment block to send an exported visual or an uploaded image as a file. For example, attach a document from your own account:

{{ attachment ref: /d/example_report, format: pdf }}

Documents support PDF and PPTX; plots and grids also support PNG. For an uploaded image, use its filename and omit format. The sender must have access to each source. A failed required export prevents the send.

Next
Recipients