Content

This document gives a basic introduction to the structure and design of the novem api.

Structure

E-mails (or mails for short), like most other novem visuals follows the same hierarchical folder structure that you’re used to seeing. Mails are mostly similar to Documents in that it has a primary file content where most of the information for the mail is stored.

In addition to the content file, there are also supporting files and folders containing information such as recipients, attachments, configuration etc.

Below is an illustrative exmaple of an overall e-mail structure.

daily_email_summary      => E-mail ID
...
├── content              => Content of e-mail
...

Content file

The content file /v1/vis/mails/<id>/content expects information to be supplied in novem markdown.

Sections

Like documents, novem e-mails use the novem markdown section extensions.

Similarly to how sections can be used to create new pages or heading in novem documents, sections can be used to embed visuals and control layout in novem mail as well.

  • Top section, controls subject and preview
  • Heading sections, control document layout by adding whitespace, headings etc
  • Special sections, add information such as pictures, blurbs etc
    • Authors @novem user + @novem user description @novem user picture
    • Callouts - warnings/info/error
    • Quotes
    • Code w/syntax highlight

Subject and preview text

At the very beginning of an e-mail there should be a top level section containing optional subject and preview instructions.

  • The subject instruction provides the subject of an e-mail (truncated after 100 charracters, so keep it simple)
  • The preview instruction provides a short preview text that will only be visilble in the list view of e-mail clients.

Example of subject and preview:

---
  subject: This is the subject of the e-mail
  preivew: A short preivew text that will show up in the list view.
---

Callouts 

---
  type: callout_start
  kind: warn/info/err
  pre: optional small gray pre header
  border: dashed bold
---

Callout body follows here

 * Add bullets and other information here
 * Add another bullets and other information here

### even header support

---
  type: callout_end
---

Novem visuals

Sending an e-mail

Sending an e-mail is fairly straight forward, simply POST sent to the status endpoint in the mail structure and all valid recipients in the recipients folder (to, cc, bcc) will recieve an e-mail.

Examples

A daily e-mail of webpage visitors 

---
  subject: Daily e-mail summary
  preview: Small summary that shows in preveiw but not in the body of the e-mail
---

Good morning User,

yesterday there were 4,323 unique users who visited your webpage.

=== plot
  name: /u/novem_demo/p/example_visits
  align: center
  width: 100%
===

---
  type: section
  title: Section title
---



# create a new novem e-mail
novem -m mail_name -C

# add test@novem.no to the "to" recipient list
novem -m mail_name -w recipients/to example@novem.no

# write the content of the draft.md to the mail
cat draft1.md | novem -m mail_name

# send the e-mail
novem -m mail_name -w status sent


# shorthands
cat draft.md | novem -m mail_name --to example@novem.no -S
← Recipients
Overview →