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.io to the "to" recipient list
novem -m mail_name -w recipients/to example@novem.io
# 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.io -S