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": "<string>",
  "timeout_s": 123,
  "types": [
    "mail.received",
    "mail.bounced"
  ],
  "agent_part": true
}
'

import requests

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

payload = {
    "cursor": "<string>",
    "mailbox": "<string>",
    "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: '<string>',
    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' => '<string>',
    '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\": \"<string>\",\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\": \"<string>\",\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\": \"<string>\",\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\ndata: {\"cursor\":\"41\"}\n\n: keepalive\n\nevent: batch\ndata: {\"cursor\":\"42\",\"events\":[{\"type\":\"mail.received\",\"mailbox\":\"ag_...\",\"message\":\"message_...\"}]}\n\nevent: batch\ndata: {\"cursor\":\"43\",\"events\":[{\"type\":\"mail.sent\",\"mailbox\":\"ag_...\",\"message\":\"message_...\"}]}\n"

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "request_id": "<string>",
    "retry_after_ms": 123,
    "version": "<string>",
    "current": {}
  }
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "request_id": "<string>",
    "retry_after_ms": 123,
    "version": "<string>",
    "current": {}
  }
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "request_id": "<string>",
    "retry_after_ms": 123,
    "version": "<string>",
    "current": {}
  }
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "request_id": "<string>",
    "retry_after_ms": 123,
    "version": "<string>",
    "current": {}
  }
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "request_id": "<string>",
    "retry_after_ms": 123,
    "version": "<string>",
    "current": {}
  }
}

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 hold waiting on somebody, a delivery outcome returning.

Pass the cursor from the last event 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 event carries a cursor. Store it only after you have acted on the event, or a crash between the two loses the event.

The stream is three kinds of line. It always starts with an open frame carrying the cursor you supplied. Without one, the stream starts at the latest event and you have no resumable position until the first batch; to resume without a gap, call wait first and stream from its cursor. 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.

A request that is wrong is refused before the stream opens, with an ordinary JSON error: a cursor that does not parse is 400, a credential that reaches no mailbox is 403. An error after open is a failure in flight, arrives as a batch frame carrying error, and ends the stream.

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": "<string>",
  "timeout_s": 123,
  "types": [
    "mail.received",
    "mail.bounced"
  ],
  "agent_part": true
}
'

import requests

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

payload = {
    "cursor": "<string>",
    "mailbox": "<string>",
    "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: '<string>',
    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' => '<string>',
    '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\": \"<string>\",\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\": \"<string>\",\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\": \"<string>\",\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\ndata: {\"cursor\":\"41\"}\n\n: keepalive\n\nevent: batch\ndata: {\"cursor\":\"42\",\"events\":[{\"type\":\"mail.received\",\"mailbox\":\"ag_...\",\"message\":\"message_...\"}]}\n\nevent: batch\ndata: {\"cursor\":\"43\",\"events\":[{\"type\":\"mail.sent\",\"mailbox\":\"ag_...\",\"message\":\"message_...\"}]}\n"

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "request_id": "<string>",
    "retry_after_ms": 123,
    "version": "<string>",
    "current": {}
  }
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "request_id": "<string>",
    "retry_after_ms": 123,
    "version": "<string>",
    "current": {}
  }
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "request_id": "<string>",
    "retry_after_ms": 123,
    "version": "<string>",
    "current": {}
  }
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "request_id": "<string>",
    "retry_after_ms": 123,
    "version": "<string>",
    "current": {}
  }
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "request_id": "<string>",
    "retry_after_ms": 123,
    "version": "<string>",
    "current": {}
  }
}

Authorizations

Authorization

string

header

required

Bearer token for one agent. Pass as Authorization: Bearer <token>.

A token is shown once when it is issued and is not recoverable afterwards. Treat it as a secret: it reaches one agent's mail, calendar and contacts, and anything a grant has extended to 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.

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

string[]

Only these event types. Empty matches everything.

Example:

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

agent_part

boolean

Only messages carrying a machine-readable part.

Response

An SSE stream of events.

The response is of type string.

Discovery

Mail

Send

Calendar

Contacts

Attachments

Events

Health

Stream events as they happen

Authorizations

Body

Response