Mails

Recipients

How novem addresses recipients: the address formats, how the to/cc/bcc lists behave, and the limits that apply per plan.

AI assisted, human approved — novem uses AI to review and keep our documentation up to date.

E-mails (or mails for short), like most other novem visuals follows the same hierarchical folder structure that you're used to seeing. Who receives the e-mail is controlled by three plain-text files in the recipients folder:

daily_email_summary      => E-mail ID
...
├── recipients           => Who should receive the e-mail
│   ├── to               => List of primary recipients
│   ├── cc               => List of cc recipients
│   └── bcc              => List of bcc recipients
...

Each of to, cc, and bcc holds a whitespace-separated list of recipients. One per line, by convention:

# replace the "to" list
novem -m daily_email_summary -w recipients/to "reports@example.com @novem_demo"

# read it back
novem -m daily_email_summary -r recipients/to

# clear it
curl -X DELETE -H "Authorization: Bearer $NOVEM_TOKEN" \
  https://api.novem.io/v1/vis/mails/daily_email_summary/recipients/to

A few things to know:

  • A POST replaces the whole list, not appends to it. Write the full set each time.
  • Writes are atomic: if any line can't be applied (unknown user, over your plan limit, unparsable entry), the request fails with a 400 listing the rejected lines and nothing changes.
  • A DELETE (or a POST with an empty body) clears the list.
  • You must have added and verified your own e-mail address before you can write recipients (424 otherwise).
  • Every change is recorded in the e-mail's /log.

FormatExampleMeaning
E-mail addressreports@example.comAny external address
Novem user@usernameThe user's registered address
Yourselfme, self or @your_usernameYour own registered address — always allowed
Org group+org~groupEvery accepted member of an organisation group
User group@user~groupEvery accepted member of a user's group
Personal group~groupShorthand for @your_username~group

For a novem user to be addable they must exist, have a public profile and a verified e-mail address.

For a group to be addable you must be a superuser, admin or founder of that group; at send time the e-mail goes to every accepted member with a verified address.

How many recipients you can address depends on your subscription. The limits apply per e-mail and per category. External addresses, novem users, and groups count separately:

PlanExternal addressesNovem usersGroups
Free00200
Basic52020 000
Premium2520020 000
Enterprise50020020 000

Regardless of plan you can always send to yourself (me), so free accounts can use novem e-mail for their own reports and alerts. Enterprise limits are negotiated on a per-case basis.

The limits are enforced both when you write the recipient lists and again when an e-mail is sent.

Once the recipients are in place, sending is a single write to the e-mail's status endpoint. A test mode delivers only to your own verified address. See sending for the full lifecycle, checks, and rate limits.

To avoid spamming or the sending of unwanted e-mails, novem always adds an unsubscribe link to the footer of our e-mails. If a recipient unsubscribes from an e-mail then no more e-mails from that particular ID will be sent to that recipient again.

If a new e-mail is created with the same recipient and the recipient unsubscribes from that id as well, then no further e-mails from the sending account will be delivered to that recipient unless the recipient chooses to explicitly whitelist the account.

There are several other anti-spam techniques as well, but those are the most common errors you should expect to see.

Next
Config