Scheduled and recurring sends

Add delay (seconds) or at (epoch seconds, or ISO 8601 with a time zone) and the send waits.

Scheduled sends#

curl https://nowlark.com/v1/notify -H "X-Nowlark-Key: nlk_…" -H 'Content-Type: application/json' \
  -d '{"source":"Standup","title":"Standup in 5","delay":3300}'

• Refused now, not later. A bad field, a feature the account has not unlocked (402), or too many waiting (429 too_many_scheduled, 200 per account) is the response to the call that asked, never a silent failure at the time it was due.
• The id is kept. id in the response is the id the notification has when it arrives, so a receipt can be asked for before it exists.
• Rules in force when it fires. Mute, a per-source priority cap, repeat, the pass and replace_key are decided at delivery. A source muted after scheduling stays muted.
• A retry is safe. A dedupe_key already used by a waiting or delivered notification returns duplicate: true and queues nothing.
• Charged once. The call counts against the key's hourly limit when accepted; the delivery does not.
• Precision. Delivered within one scheduler tick (15 seconds) after its time, never before.
• GET /v1/scheduled lists what is waiting, soonest first. DELETE /v1/scheduled/{id} cancels one that has not fired; once it has been picked up it is on its way and the answer is 404. Both take an API key and see only that key's account.

Recurring sends#

every seconds, ending after count sends or at until, whichever comes first. One of the two is required: a series that never ends is a phone that rings for ever when its owner forgets.

curl https://nowlark.com/v1/notify -H "X-Nowlark-Key: nlk_…" -H 'Content-Type: application/json' \
  -d '{"source":"Standup","title":"Standup in 5","every":86400,"count":5,"delay":3300}'

• The first send is at delay or at if given, else every seconds from now.
• Anchored to the schedule. Each send is every after the one before, however late a tick ran. If the service was down, the sends it missed are skipped, not fired all at once.
• The response id is the first notification's id; later ones are <id>-1, <id>-2, and a receipt can be asked for any of them. A fire retried after a crash is refused as a duplicate.
• 20 series at once per account. dedupe_key cannot be used with every (the second send would be dropped); replace_key can, and makes each send replace the last.
• GET /v1/scheduled shows every, fired and fires_left; DELETE /v1/scheduled/{id} stops the series, even while it is firing (that send is then its last).
• The rules in force at each send decide what it does, as they do for any other scheduled send.