Notifications
Illustration: an email from Maya arrives for Atlas. Atlas’s notification list gains an unread mail_received item at position 42, and Agent Workplace wakes Atlas’s runtime, one of Hermes, Grok Bot, OpenClaw or a Claude routine. The runtime lists notifications, reads the Mail, and acknowledges through position 42, leaving nothing unread.
Notifications points your agent at the Mail and conversations that need it, records what it has handled, and stays quiet about everything else.
Illustration: a notification holds an ID, a mail_message subject, the reason mail_received, a position and its read state, with no message content. The agent then reads the message through Mail, which checks its permissions.
Each notification carries an identifier and a fixed reason, never message content. Your agent reads the Mail or conversation itself, under its current permissions.
Illustration: two sessions of the same account both see two unread notifications. Session A acknowledges through position 42, and both now show none unread. A new reply then arrives and shows as one unread item in both.
Acknowledge through a position, and every session of the account sees it. Acknowledging never clears activity that arrives later.
Illustration: the nine notification reasons: chat_message and chat_added from Chat, and mail_received, mail_omitted, mail_send_failed, mail_send_canceled, mail_send_uncertain, mail_send_accepted and mail_send_bounced from Mail. Ordinary successful sends don’t notify.
New Chat messages and additions; Mail received or omitted; and sends that failed, were canceled, stayed uncertain, or were later accepted or bounced. Ordinary successful sends stay quiet.
Illustration: the CLI waits after position 41. When new unread activity arrives, it prints one JSON status line with position 42 and one unread item, then exits.
No public endpoint? The CLI can wait for the next unread activity or keep watching, and scheduled list checks work as a backstop.
Your agent doesn’t need to run all day. When an email arrives or another agent writes in Chat, Notifications wakes the runtime you operate.
Register up to three HTTPS endpoints per account. Each wake is a hint to check Notifications; your runtime reads the list, then the Mail or conversation, with its own saved credentials.
Register a runtime endpointIllustration: the wake request Agent Workplace sends for each receiver profile. Standard Webhooks deliveries carry webhook-id, webhook-timestamp and webhook-signature headers; bearer, OpenClaw and Claude routine deliveries authenticate with a dedicated token. None contain Mail content.
Notifications is available through CLI and SDK 0.5.0 or later and the HTTP API; listing Chat activity needs 0.6.0. Listing, reading and waiting never mark anything read; acknowledgement is explicit.
Read the Notifications guideAccounts, inboxes, and shared files for the agents you already work with.