Sending
An e-mail goes out when you write to its status endpoint. This page covers production and test sends, the checks novem runs before a send is accepted, and how to follow up with status, stats and the log.
AI assisted, human approved — novem uses AI to review and keep our documentation up to date.
Sending is a single write: POST the word sent to the e-mail's status
file and novem queues a delivery to every valid entry in the
recipients folder.
sent
A successful trigger answers 202 Accepted; delivery itself is
asynchronous. Only the owner of an e-mail can send it.
Write test instead and the rendered e-mail goes to exactly one address:
your own registered and verified one. Recipient lists, the config/enabled
switch and the send rate limit are all bypassed, which makes test the safe
way to iterate on content:
# send a test of the current draft to yourself
novem -m weekly_report -w status test
# happy? send it for real
novem -m weekly_report -w status sent
Note: anything written to status that does not start with test is
treated as a production send request. Stick to the two documented values.
Novem validates a send request before queueing it. The full list, in order:
| Check | Failure response |
|---|---|
| You own the e-mail | 404 |
| Your own e-mail address is verified | 403 |
| No send of this e-mail is already in flight | 425 — try again once it completes |
| At most 10 sends of the same content per 30 minutes | 429 with retry_after_seconds in the body |
config/enabled is not set to a falsy value | 403 — see config |
The rate limit is content-based: editing the e-mail (or anything it embeds)
resets the window, so iterating on a report never runs into it. Only
re-sending the identical e-mail does. Test sends are exempt from both the
rate limit and the enabled check.
Recipient lists are resolved at send time, and your plan's recipient limits are applied to the resolved list.
GET on the same endpoint tells you where the e-mail is in its lifecycle:
| Value | Meaning |
|---|---|
ready | No send in progress; the e-mail can be sent |
sending | A production send is being processed |
testing | A test send is being processed |
GET /v1/vis/mails/:mail/stats/runs returns one row per send with the
timestamp, duration in seconds, and final status: plain text by default, JSON
with an Accept: application/json header.
Everything that happens to an e-mail (recipient changes, send triggers, rejected sends and the reason why) is recorded in its log:
novem -m weekly_report -r log
# or
curl -H "Authorization: Bearer $NOVEM_TOKEN" \
https://api.novem.io/v1/vis/mails/weekly_report/log
When a send doesn't behave the way you expect, the log is the first place to look.