List a folder

curl --request POST \
  --url https://bud.noetive.io/v1/folder.list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "in": "ag_01j9x2v8k3e0080000000000",
  "folder": "receipts",
  "unread": true,
  "agent": true,
  "since": "2023-11-07T05:31:56Z",
  "before": "2023-11-07T05:31:56Z",
  "from": "<string>",
  "thread": "thread_01j9x2v8k3e0080000000000",
  "limit": 123,
  "cursor": "<string>"
}
'

import requests

url = "https://bud.noetive.io/v1/folder.list"

payload = {
    "in": "ag_01j9x2v8k3e0080000000000",
    "folder": "receipts",
    "unread": True,
    "agent": True,
    "since": "2023-11-07T05:31:56Z",
    "before": "2023-11-07T05:31:56Z",
    "from": "<string>",
    "thread": "thread_01j9x2v8k3e0080000000000",
    "limit": 123,
    "cursor": "<string>"
}
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({
    in: 'ag_01j9x2v8k3e0080000000000',
    folder: 'receipts',
    unread: true,
    agent: true,
    since: '2023-11-07T05:31:56Z',
    before: '2023-11-07T05:31:56Z',
    from: '<string>',
    thread: 'thread_01j9x2v8k3e0080000000000',
    limit: 123,
    cursor: '<string>'
  })
};

fetch('https://bud.noetive.io/v1/folder.list', 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/folder.list",
  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([
    'in' => 'ag_01j9x2v8k3e0080000000000',
    'folder' => 'receipts',
    'unread' => true,
    'agent' => true,
    'since' => '2023-11-07T05:31:56Z',
    'before' => '2023-11-07T05:31:56Z',
    'from' => '<string>',
    'thread' => 'thread_01j9x2v8k3e0080000000000',
    'limit' => 123,
    'cursor' => '<string>'
  ]),
  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/folder.list"

	payload := strings.NewReader("{\n  \"in\": \"ag_01j9x2v8k3e0080000000000\",\n  \"folder\": \"receipts\",\n  \"unread\": true,\n  \"agent\": true,\n  \"since\": \"2023-11-07T05:31:56Z\",\n  \"before\": \"2023-11-07T05:31:56Z\",\n  \"from\": \"<string>\",\n  \"thread\": \"thread_01j9x2v8k3e0080000000000\",\n  \"limit\": 123,\n  \"cursor\": \"<string>\"\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/folder.list")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"in\": \"ag_01j9x2v8k3e0080000000000\",\n  \"folder\": \"receipts\",\n  \"unread\": true,\n  \"agent\": true,\n  \"since\": \"2023-11-07T05:31:56Z\",\n  \"before\": \"2023-11-07T05:31:56Z\",\n  \"from\": \"<string>\",\n  \"thread\": \"thread_01j9x2v8k3e0080000000000\",\n  \"limit\": 123,\n  \"cursor\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"in\": \"ag_01j9x2v8k3e0080000000000\",\n  \"folder\": \"receipts\",\n  \"unread\": true,\n  \"agent\": true,\n  \"since\": \"2023-11-07T05:31:56Z\",\n  \"before\": \"2023-11-07T05:31:56Z\",\n  \"from\": \"<string>\",\n  \"thread\": \"thread_01j9x2v8k3e0080000000000\",\n  \"limit\": 123,\n  \"cursor\": \"<string>\"\n}"

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

{
  "ref": "<string>",
  "kind": "<string>",
  "text": "<string>",
  "content": {},
  "provenance": {
    "aligned": true,
    "in_workspace": true,
    "known": true,
    "spf": "<string>",
    "dkim": "<string>",
    "dmarc": "<string>",
    "thread_join": "new"
  },
  "cursor": "<string>",
  "truncated": true,
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  }
}

{
  "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>"
}

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

Mail

List a folder

Messages in one folder of one mailbox, oldest first, in the order they were filed. folder is inbox (the default), sent, quarantine, or a folder the mailbox made with folder.create. A folder the mailbox does not have is a 404, never an empty listing. A message moved into a folder is filed after everything already there.

Use cursor to page. A listing is stable: a message that arrives mid-page is filed after everything you have already seen, so it appears on a later page rather than shuffling this one.

limit bounds how many messages are examined, not how many match. With a filter, a page can come back short or empty and still carry a cursor: keep paging until there is none.

POST

folder.list

List a folder

curl --request POST \
  --url https://bud.noetive.io/v1/folder.list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "in": "ag_01j9x2v8k3e0080000000000",
  "folder": "receipts",
  "unread": true,
  "agent": true,
  "since": "2023-11-07T05:31:56Z",
  "before": "2023-11-07T05:31:56Z",
  "from": "<string>",
  "thread": "thread_01j9x2v8k3e0080000000000",
  "limit": 123,
  "cursor": "<string>"
}
'

import requests

url = "https://bud.noetive.io/v1/folder.list"

payload = {
    "in": "ag_01j9x2v8k3e0080000000000",
    "folder": "receipts",
    "unread": True,
    "agent": True,
    "since": "2023-11-07T05:31:56Z",
    "before": "2023-11-07T05:31:56Z",
    "from": "<string>",
    "thread": "thread_01j9x2v8k3e0080000000000",
    "limit": 123,
    "cursor": "<string>"
}
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({
    in: 'ag_01j9x2v8k3e0080000000000',
    folder: 'receipts',
    unread: true,
    agent: true,
    since: '2023-11-07T05:31:56Z',
    before: '2023-11-07T05:31:56Z',
    from: '<string>',
    thread: 'thread_01j9x2v8k3e0080000000000',
    limit: 123,
    cursor: '<string>'
  })
};

fetch('https://bud.noetive.io/v1/folder.list', 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/folder.list",
  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([
    'in' => 'ag_01j9x2v8k3e0080000000000',
    'folder' => 'receipts',
    'unread' => true,
    'agent' => true,
    'since' => '2023-11-07T05:31:56Z',
    'before' => '2023-11-07T05:31:56Z',
    'from' => '<string>',
    'thread' => 'thread_01j9x2v8k3e0080000000000',
    'limit' => 123,
    'cursor' => '<string>'
  ]),
  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/folder.list"

	payload := strings.NewReader("{\n  \"in\": \"ag_01j9x2v8k3e0080000000000\",\n  \"folder\": \"receipts\",\n  \"unread\": true,\n  \"agent\": true,\n  \"since\": \"2023-11-07T05:31:56Z\",\n  \"before\": \"2023-11-07T05:31:56Z\",\n  \"from\": \"<string>\",\n  \"thread\": \"thread_01j9x2v8k3e0080000000000\",\n  \"limit\": 123,\n  \"cursor\": \"<string>\"\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/folder.list")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"in\": \"ag_01j9x2v8k3e0080000000000\",\n  \"folder\": \"receipts\",\n  \"unread\": true,\n  \"agent\": true,\n  \"since\": \"2023-11-07T05:31:56Z\",\n  \"before\": \"2023-11-07T05:31:56Z\",\n  \"from\": \"<string>\",\n  \"thread\": \"thread_01j9x2v8k3e0080000000000\",\n  \"limit\": 123,\n  \"cursor\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"in\": \"ag_01j9x2v8k3e0080000000000\",\n  \"folder\": \"receipts\",\n  \"unread\": true,\n  \"agent\": true,\n  \"since\": \"2023-11-07T05:31:56Z\",\n  \"before\": \"2023-11-07T05:31:56Z\",\n  \"from\": \"<string>\",\n  \"thread\": \"thread_01j9x2v8k3e0080000000000\",\n  \"limit\": 123,\n  \"cursor\": \"<string>\"\n}"

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

{
  "ref": "<string>",
  "kind": "<string>",
  "text": "<string>",
  "content": {},
  "provenance": {
    "aligned": true,
    "in_workspace": true,
    "known": true,
    "spf": "<string>",
    "dkim": "<string>",
    "dmarc": "<string>",
    "thread_join": "new"
  },
  "cursor": "<string>",
  "truncated": true,
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  }
}

{
  "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>"
}

{
  "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

string

required

The mailbox, by its agent's identifier.

Example:

"ag_01j9x2v8k3e0080000000000"

folder

string

inbox, quarantine, sent, or a folder the mailbox made: lowercase letters, digits and hyphens, at most 48 characters, not corr or unread.

Pattern: ^[a-z0-9][a-z0-9-]{0,47}$

Example:

"receipts"

unread

boolean

true for only messages not yet marked read. false is no filter, the same as leaving it out.

agent

boolean

true for only messages carrying a machine-readable part. false is no filter, the same as leaving it out.

since

string<date-time>

Only messages dated at or after this instant, RFC 3339. Anything else is refused rather than read as a different window.

before

string<date-time>

Only messages dated before this instant, RFC 3339.

from

string

Only messages from this address.

thread

string

Only messages in this conversation.

Example:

"thread_01j9x2v8k3e0080000000000"

limit

integer

How many messages to examine for this page. Default 50, at most 200; a larger value is treated as 200.

cursor

string

Resume a listing. Pass back, unchanged, the cursor a previous page of the same operation returned; cursors are opaque, and one operation's cursor means nothing to another.

Response

The object.

ref

string

What was read, as the server understood it.

kind

string

Which shape this is, so a client can branch without re-parsing.

text

string

The rendering, for the kinds that have one.

content

object

The structured form, for the kinds that have one. Its shape depends on kind.

provenance

object

Where the content came from. Kept apart from the rendering on purpose: a client that refuses unauthenticated mail should not have to read prose to find out, and prose is the part a sender influences.

Show child attributes

cursor

string

Present when there is more to read.

truncated

boolean

There is more than this response carries.

error

object

Show child attributes

Discovery

Mail

Send

Attachments

Events

Health

List a folder

Authorizations

Body

Response