What do you need?
- A webhook endpoint or an event-feed consumer
- An inbox the agent sends from
Steps
-
1. Arm the timer when sending
Pass thread_metadata with the send, or set it after.
Send and arm const sent = await nf.messages.send(inbox.id, { to: ["carrier@example.com"], subject: "Lane CHIāATL, 2 pallets", text, thread_metadata: { stage: "quote_requested", follow_up_at: in48h() }, }); -
2. Disarm on reply
On message.received for the thread, record the new stage and clear follow_up_at (null deletes a key).
On a reply await nf.threads.setMetadata(threadId, { stage: "quote_received", follow_up_at: null }); -
3. Act on thread.due
Subscribe to thread.due. The event carries thread_id, inbox_id, due_at and the thread's metadata.
On thread.due if (event.type === "thread.due") { const { thread_id, metadata } = event.data; if (metadata.stage === "quote_requested") { const thread = await nf.threads.get(thread_id); const last = thread.messages.at(-1)!; await nf.messages.reply(last.id, { text: "Following up on the quote request below." }); await nf.threads.setMetadata(thread_id, { follow_up_at: in48h(), nudges: (metadata.nudges ?? 0) + 1 }); } }
Frequently asked questions
How do I send a follow-up email if there is no reply in three days?
Set follow_up_at to three days out when you send, clear it when a reply arrives, and handle thread.due: it fires only if the time passes with the key still set.
What happens if I change follow_up_at?
The timer moves with it. Setting it to null cancels it.
Do I need a cron job or a queue?
No. The timer lives with the thread in nofeb, and the event arrives through the same webhooks and feed as every other event.
Status of everything on this page
Every capability named above, with its status as reconciled against the engine.
| Capability | What it does | Status |
|---|---|---|
| Follow-up timers | Set follow_up_at on a thread and, when that time passes, a thread.due event carrying the thread's metadata goes to your webhooks and the event feed, so agents need no scheduler of their own. | Shipped |
| Typed metadata on messages, threads and inboxes | Merge-patch keys onto a message, a thread or an inbox, and declare a key's type so every write to it is validated. | Shipped |
| Signed webhooks with required scope | Standard Webhooks signatures, retries and a delivery log. Scope (organization, pod or inbox) is required, so a subscription never silently widens to everything. | Shipped |
| Durable event feed | A pull feed of every event, oldest first after a cursor, for consumers that cannot receive webhooks. | Shipped |
| Send, reply, reply-all and forward | Threading headers are set for you, replies default to the original sender, and forwards carry the original attachments. | Shipped |