Stream events as they happen

curl --request POST \
  --url https://bud.noetive.io/v1/watch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cursor": "<string>",
  "mailbox": "ag_01j9x2v8k3e0080000000000",
  "timeout_s": 123,
  "types": [
    "mail.received",
    "mail.bounced"
  ],
  "agent_part": true
}
'

import requests

url = "https://bud.noetive.io/v1/watch"

payload = {
    "cursor": "<string>",
    "mailbox": "ag_01j9x2v8k3e0080000000000",
    "timeout_s": 123,
    "types": ["mail.received", "mail.bounced"],
    "agent_part": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cursor: '<string>',
    mailbox: 'ag_01j9x2v8k3e0080000000000',
    timeout_s: 123,
    types: ['mail.received', 'mail.bounced'],
    agent_part: true
  })
};

fetch('https://bud.noetive.io/v1/watch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bud.noetive.io/v1/watch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'cursor' => '<string>',
    'mailbox' => 'ag_01j9x2v8k3e0080000000000',
    'timeout_s' => 123,
    'types' => [
        'mail.received',
        'mail.bounced'
    ],
    'agent_part' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://bud.noetive.io/v1/watch"

	payload := strings.NewReader("{\n  \"cursor\": \"<string>\",\n  \"mailbox\": \"ag_01j9x2v8k3e0080000000000\",\n  \"timeout_s\": 123,\n  \"types\": [\n    \"mail.received\",\n    \"mail.bounced\"\n  ],\n  \"agent_part\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://bud.noetive.io/v1/watch")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cursor\": \"<string>\",\n  \"mailbox\": \"ag_01j9x2v8k3e0080000000000\",\n  \"timeout_s\": 123,\n  \"types\": [\n    \"mail.received\",\n    \"mail.bounced\"\n  ],\n  \"agent_part\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://bud.noetive.io/v1/watch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cursor\": \"<string>\",\n  \"mailbox\": \"ag_01j9x2v8k3e0080000000000\",\n  \"timeout_s\": 123,\n  \"types\": [\n    \"mail.received\",\n    \"mail.bounced\"\n  ],\n  \"agent_part\": true\n}"

response = http.request(request)
puts response.read_body

event: open
data: {"cursor":"41"}

: keepalive

event: batch
data: {"cursor":"42","events":[{"id":"journal_...","workspace":"workspace_...","ts":"2026-01-02T15:04:05Z","seq":42,"type":"mail.received","mailbox":"ag_...","message":"message_...","thread":"thread_...","actor":{"kind":"system","agent":""},"data":{"from":"anna@example.net","subject":"Order #1234","aligned":true,"folder":"inbox"}}]}

event: batch
data: {"cursor":"43","events":[{"id":"journal_...","workspace":"workspace_...","ts":"2026-01-02T15:04:09Z","seq":43,"type":"mail.sent","mailbox":"ag_...","message":"message_...","thread":"thread_...","actor":{"kind":"agent","agent":"ag_..."},"data":{"state":"sent"}}]}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

Events

Stream events as they happen

Opens a Server-Sent Events stream of everything that happens in the mailboxes this credential can read: mail arriving, a send leaving, a delivery outcome returning.

Pass the cursor from the last frame you processed to resume exactly where you stopped. An empty cursor starts at the tail, which is what a fresh client wants: one cheap call for a usable cursor instead of replaying history.

Every frame carries a cursor, and each event carries seq, its position in its mailbox. Store a frame’s cursor only after you have acted on its events, or a crash between the two loses them.

The stream is three kinds of line. It always starts with an open frame carrying the cursor the stream starts from: yours, re-encoded for the mailboxes in scope, with the current tail for every mailbox it does not name. Store it, and a reconnect misses nothing even if no batch ever arrived. Each batch frame carries events and the cursor after them. A : keepalive comment arrives while nothing is happening, so a silent connection is distinguishable from a dead one.

The data of an open frame is a WatchOpenFrame, and of a batch frame a WatchBatchFrame.

A request that is wrong is refused before the stream opens, with an ordinary JSON error: a cursor that does not parse or an unknown event type is 400, a mailbox this credential cannot read is 403. An error after open is a failure in flight, arrives as a batch frame carrying error and the cursor the stream had reached, and ends the stream: store that cursor and reconnect with it.

It stays open until you disconnect or the server is replaced; reconnect with your last cursor and nothing is lost.

POST

watch

Stream events as they happen

curl --request POST \
  --url https://bud.noetive.io/v1/watch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cursor": "<string>",
  "mailbox": "ag_01j9x2v8k3e0080000000000",
  "timeout_s": 123,
  "types": [
    "mail.received",
    "mail.bounced"
  ],
  "agent_part": true
}
'

import requests

url = "https://bud.noetive.io/v1/watch"

payload = {
    "cursor": "<string>",
    "mailbox": "ag_01j9x2v8k3e0080000000000",
    "timeout_s": 123,
    "types": ["mail.received", "mail.bounced"],
    "agent_part": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cursor: '<string>',
    mailbox: 'ag_01j9x2v8k3e0080000000000',
    timeout_s: 123,
    types: ['mail.received', 'mail.bounced'],
    agent_part: true
  })
};

fetch('https://bud.noetive.io/v1/watch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bud.noetive.io/v1/watch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'cursor' => '<string>',
    'mailbox' => 'ag_01j9x2v8k3e0080000000000',
    'timeout_s' => 123,
    'types' => [
        'mail.received',
        'mail.bounced'
    ],
    'agent_part' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://bud.noetive.io/v1/watch"

	payload := strings.NewReader("{\n  \"cursor\": \"<string>\",\n  \"mailbox\": \"ag_01j9x2v8k3e0080000000000\",\n  \"timeout_s\": 123,\n  \"types\": [\n    \"mail.received\",\n    \"mail.bounced\"\n  ],\n  \"agent_part\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://bud.noetive.io/v1/watch")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cursor\": \"<string>\",\n  \"mailbox\": \"ag_01j9x2v8k3e0080000000000\",\n  \"timeout_s\": 123,\n  \"types\": [\n    \"mail.received\",\n    \"mail.bounced\"\n  ],\n  \"agent_part\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://bud.noetive.io/v1/watch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cursor\": \"<string>\",\n  \"mailbox\": \"ag_01j9x2v8k3e0080000000000\",\n  \"timeout_s\": 123,\n  \"types\": [\n    \"mail.received\",\n    \"mail.bounced\"\n  ],\n  \"agent_part\": true\n}"

response = http.request(request)
puts response.read_body

event: open
data: {"cursor":"41"}

: keepalive

event: batch
data: {"cursor":"42","events":[{"id":"journal_...","workspace":"workspace_...","ts":"2026-01-02T15:04:05Z","seq":42,"type":"mail.received","mailbox":"ag_...","message":"message_...","thread":"thread_...","actor":{"kind":"system","agent":""},"data":{"from":"anna@example.net","subject":"Order #1234","aligned":true,"folder":"inbox"}}]}

event: batch
data: {"cursor":"43","events":[{"id":"journal_...","workspace":"workspace_...","ts":"2026-01-02T15:04:09Z","seq":43,"type":"mail.sent","mailbox":"ag_...","message":"message_...","thread":"thread_...","actor":{"kind":"agent","agent":"ag_..."},"data":{"state":"sent"}}]}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer credential for one agent: an API key or an access token (a JWT). Pass as Authorization: Bearer <credential>.

A key is shown once when it is issued and is not recoverable afterwards; an access token lives five minutes and is fetched with the agent's own client key from the access service. Treat both as secrets: they reach one agent's mail, and anything a delegation has extended to it. An access token's scope is a ceiling on what the agent may do with it.

Body

application/json

cursor

string

Where to resume. Empty starts at the tail.

mailbox

string

Narrow to one mailbox. Empty means every mailbox this credential can read.

Example:

"ag_01j9x2v8k3e0080000000000"

timeout_s

integer

How long each quiet interval lasts before a keepalive is sent, in seconds, at most 25. It does not end the stream.

types

enum<string>[]

Only these event types. Empty matches everything; an unknown type is refused.

mail.received and mail.quarantined are mail arriving, the second filed in quarantine. mail.queued, mail.held, mail.approved, mail.rejected, mail.sent, mail.delivered, mail.bounced and mail.complained follow a send: accepted, held for a person, released by a person, refused or lapsed while held (the budget is given back), handed to the provider, accepted by the receiving side, refused for good, reported as unwanted. mail.read is a message marked read or unread. mail.moved is a message filed in another folder; its folder is where it went, while the folder on mail.received is where it arrived. Its actor is the agent that moved it, or the server when a removed folder sent the message back to inbox. render.failed means a rendering was withheld as unsafe and a degraded one shown instead.

Available options:

mail.received,

mail.quarantined,

mail.queued,

mail.held,

mail.approved,

mail.rejected,

mail.sent,

mail.delivered,

mail.bounced,

mail.complained,

mail.read,

mail.moved,

render.failed

Example:

["mail.received", "mail.bounced"]

agent_part

boolean

true for only messages carrying a machine-readable part, false for only messages without one. Absent matches both.

Response

An SSE stream of events.

The response is of type string.

Discovery

Mail

Send

Attachments

Events

Health

Stream events as they happen

Authorizations

Body

Response