Send a message

curl --request POST \
  --url https://bud.noetive.io/v1/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": [
    "<string>"
  ],
  "cc": [
    "<string>"
  ],
  "bcc": [
    "<string>"
  ],
  "from": "<string>",
  "on_behalf_of": "<string>",
  "subject": "<string>",
  "text": "<string>",
  "html": "<string>",
  "in_reply_to": "message_01j9x2v8k3e0080000000000",
  "reply_all": true,
  "agent": {
    "bud": 123,
    "intent": "<string>",
    "corr": "<string>",
    "in_reply_to_corr": "<string>",
    "schema": "<string>",
    "hops": 123,
    "payload": "<unknown>",
    "expect": "<unknown>"
  },
  "idempotency_key": "<string>"
}
'

import requests

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

payload = {
    "to": ["<string>"],
    "cc": ["<string>"],
    "bcc": ["<string>"],
    "from": "<string>",
    "on_behalf_of": "<string>",
    "subject": "<string>",
    "text": "<string>",
    "html": "<string>",
    "in_reply_to": "message_01j9x2v8k3e0080000000000",
    "reply_all": True,
    "agent": {
        "bud": 123,
        "intent": "<string>",
        "corr": "<string>",
        "in_reply_to_corr": "<string>",
        "schema": "<string>",
        "hops": 123,
        "payload": "<unknown>",
        "expect": "<unknown>"
    },
    "idempotency_key": "<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({
    to: ['<string>'],
    cc: ['<string>'],
    bcc: ['<string>'],
    from: '<string>',
    on_behalf_of: '<string>',
    subject: '<string>',
    text: '<string>',
    html: '<string>',
    in_reply_to: 'message_01j9x2v8k3e0080000000000',
    reply_all: true,
    agent: {
      bud: 123,
      intent: '<string>',
      corr: '<string>',
      in_reply_to_corr: '<string>',
      schema: '<string>',
      hops: 123,
      payload: '<unknown>',
      expect: '<unknown>'
    },
    idempotency_key: '<string>'
  })
};

fetch('https://bud.noetive.io/v1/send', 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/send",
  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([
    'to' => [
        '<string>'
    ],
    'cc' => [
        '<string>'
    ],
    'bcc' => [
        '<string>'
    ],
    'from' => '<string>',
    'on_behalf_of' => '<string>',
    'subject' => '<string>',
    'text' => '<string>',
    'html' => '<string>',
    'in_reply_to' => 'message_01j9x2v8k3e0080000000000',
    'reply_all' => true,
    'agent' => [
        'bud' => 123,
        'intent' => '<string>',
        'corr' => '<string>',
        'in_reply_to_corr' => '<string>',
        'schema' => '<string>',
        'hops' => 123,
        'payload' => '<unknown>',
        'expect' => '<unknown>'
    ],
    'idempotency_key' => '<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/send"

	payload := strings.NewReader("{\n  \"to\": [\n    \"<string>\"\n  ],\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"from\": \"<string>\",\n  \"on_behalf_of\": \"<string>\",\n  \"subject\": \"<string>\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"in_reply_to\": \"message_01j9x2v8k3e0080000000000\",\n  \"reply_all\": true,\n  \"agent\": {\n    \"bud\": 123,\n    \"intent\": \"<string>\",\n    \"corr\": \"<string>\",\n    \"in_reply_to_corr\": \"<string>\",\n    \"schema\": \"<string>\",\n    \"hops\": 123,\n    \"payload\": \"<unknown>\",\n    \"expect\": \"<unknown>\"\n  },\n  \"idempotency_key\": \"<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/send")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"to\": [\n    \"<string>\"\n  ],\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"from\": \"<string>\",\n  \"on_behalf_of\": \"<string>\",\n  \"subject\": \"<string>\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"in_reply_to\": \"message_01j9x2v8k3e0080000000000\",\n  \"reply_all\": true,\n  \"agent\": {\n    \"bud\": 123,\n    \"intent\": \"<string>\",\n    \"corr\": \"<string>\",\n    \"in_reply_to_corr\": \"<string>\",\n    \"schema\": \"<string>\",\n    \"hops\": 123,\n    \"payload\": \"<unknown>\",\n    \"expect\": \"<unknown>\"\n  },\n  \"idempotency_key\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"to\": [\n    \"<string>\"\n  ],\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"from\": \"<string>\",\n  \"on_behalf_of\": \"<string>\",\n  \"subject\": \"<string>\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"in_reply_to\": \"message_01j9x2v8k3e0080000000000\",\n  \"reply_all\": true,\n  \"agent\": {\n    \"bud\": 123,\n    \"intent\": \"<string>\",\n    \"corr\": \"<string>\",\n    \"in_reply_to_corr\": \"<string>\",\n    \"schema\": \"<string>\",\n    \"hops\": 123,\n    \"payload\": \"<unknown>\",\n    \"expect\": \"<unknown>\"\n  },\n  \"idempotency_key\": \"<string>\"\n}"

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

{
  "state": "queued",
  "approval_id": "<string>",
  "message": "<string>",
  "thread": "<string>",
  "reason": "<string>",
  "remaining": {},
  "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>"
}

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

Send

Send a message

Compose and send, or reply. The reply form computes recipients from the message being replied to rather than making the caller reconstruct them from a rendering: a rendering is partly what a sender chose.

A send is subject to the mailbox’s limits and policy. Three outcomes are normal and distinguishable: it is queued; it is held, because a rule of the workspace’s policy needs a person to approve it first (the result carries approval_id, and the message goes out when a person approves it and never otherwise); or it is refused with 422 policy_refused and guard naming the rule that fired. A held message has spent its sending budget; the budget is given back if it is rejected or lapses. Nothing you can send releases a held message: only a person the workspace named can, so do not resend it. If the policy that governs the sender cannot be applied the send is refused with 503 policy_unavailable and nothing is done. A refusal is not worth retrying unchanged.

Pass idempotency_key on every send. Without one, a timeout you retry is a second message.

remaining in the result is what is left of each sending limit, so an agent can pace itself rather than discover a limit by reaching it.

POST

send

Send a message

curl --request POST \
  --url https://bud.noetive.io/v1/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": [
    "<string>"
  ],
  "cc": [
    "<string>"
  ],
  "bcc": [
    "<string>"
  ],
  "from": "<string>",
  "on_behalf_of": "<string>",
  "subject": "<string>",
  "text": "<string>",
  "html": "<string>",
  "in_reply_to": "message_01j9x2v8k3e0080000000000",
  "reply_all": true,
  "agent": {
    "bud": 123,
    "intent": "<string>",
    "corr": "<string>",
    "in_reply_to_corr": "<string>",
    "schema": "<string>",
    "hops": 123,
    "payload": "<unknown>",
    "expect": "<unknown>"
  },
  "idempotency_key": "<string>"
}
'

import requests

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

payload = {
    "to": ["<string>"],
    "cc": ["<string>"],
    "bcc": ["<string>"],
    "from": "<string>",
    "on_behalf_of": "<string>",
    "subject": "<string>",
    "text": "<string>",
    "html": "<string>",
    "in_reply_to": "message_01j9x2v8k3e0080000000000",
    "reply_all": True,
    "agent": {
        "bud": 123,
        "intent": "<string>",
        "corr": "<string>",
        "in_reply_to_corr": "<string>",
        "schema": "<string>",
        "hops": 123,
        "payload": "<unknown>",
        "expect": "<unknown>"
    },
    "idempotency_key": "<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({
    to: ['<string>'],
    cc: ['<string>'],
    bcc: ['<string>'],
    from: '<string>',
    on_behalf_of: '<string>',
    subject: '<string>',
    text: '<string>',
    html: '<string>',
    in_reply_to: 'message_01j9x2v8k3e0080000000000',
    reply_all: true,
    agent: {
      bud: 123,
      intent: '<string>',
      corr: '<string>',
      in_reply_to_corr: '<string>',
      schema: '<string>',
      hops: 123,
      payload: '<unknown>',
      expect: '<unknown>'
    },
    idempotency_key: '<string>'
  })
};

fetch('https://bud.noetive.io/v1/send', 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/send",
  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([
    'to' => [
        '<string>'
    ],
    'cc' => [
        '<string>'
    ],
    'bcc' => [
        '<string>'
    ],
    'from' => '<string>',
    'on_behalf_of' => '<string>',
    'subject' => '<string>',
    'text' => '<string>',
    'html' => '<string>',
    'in_reply_to' => 'message_01j9x2v8k3e0080000000000',
    'reply_all' => true,
    'agent' => [
        'bud' => 123,
        'intent' => '<string>',
        'corr' => '<string>',
        'in_reply_to_corr' => '<string>',
        'schema' => '<string>',
        'hops' => 123,
        'payload' => '<unknown>',
        'expect' => '<unknown>'
    ],
    'idempotency_key' => '<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/send"

	payload := strings.NewReader("{\n  \"to\": [\n    \"<string>\"\n  ],\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"from\": \"<string>\",\n  \"on_behalf_of\": \"<string>\",\n  \"subject\": \"<string>\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"in_reply_to\": \"message_01j9x2v8k3e0080000000000\",\n  \"reply_all\": true,\n  \"agent\": {\n    \"bud\": 123,\n    \"intent\": \"<string>\",\n    \"corr\": \"<string>\",\n    \"in_reply_to_corr\": \"<string>\",\n    \"schema\": \"<string>\",\n    \"hops\": 123,\n    \"payload\": \"<unknown>\",\n    \"expect\": \"<unknown>\"\n  },\n  \"idempotency_key\": \"<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/send")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"to\": [\n    \"<string>\"\n  ],\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"from\": \"<string>\",\n  \"on_behalf_of\": \"<string>\",\n  \"subject\": \"<string>\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"in_reply_to\": \"message_01j9x2v8k3e0080000000000\",\n  \"reply_all\": true,\n  \"agent\": {\n    \"bud\": 123,\n    \"intent\": \"<string>\",\n    \"corr\": \"<string>\",\n    \"in_reply_to_corr\": \"<string>\",\n    \"schema\": \"<string>\",\n    \"hops\": 123,\n    \"payload\": \"<unknown>\",\n    \"expect\": \"<unknown>\"\n  },\n  \"idempotency_key\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"to\": [\n    \"<string>\"\n  ],\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"from\": \"<string>\",\n  \"on_behalf_of\": \"<string>\",\n  \"subject\": \"<string>\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"in_reply_to\": \"message_01j9x2v8k3e0080000000000\",\n  \"reply_all\": true,\n  \"agent\": {\n    \"bud\": 123,\n    \"intent\": \"<string>\",\n    \"corr\": \"<string>\",\n    \"in_reply_to_corr\": \"<string>\",\n    \"schema\": \"<string>\",\n    \"hops\": 123,\n    \"payload\": \"<unknown>\",\n    \"expect\": \"<unknown>\"\n  },\n  \"idempotency_key\": \"<string>\"\n}"

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

{
  "state": "queued",
  "approval_id": "<string>",
  "message": "<string>",
  "thread": "<string>",
  "reason": "<string>",
  "remaining": {},
  "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>"
}

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

Recipients. May be omitted on a reply, which takes them from the message being replied to. A send with no recipients at all is refused.

string[]

bcc

string[]

from

string

Which of the agent's addresses to send as. Empty takes its primary address.

on_behalf_of

string

Send as another agent, which needs a send-on-behalf grant from that agent's owner, the organization's permission for sending on behalf, and a From domain verified for the workspace. Without all three the send is refused with 422 policy_refused. The message then names both, with the sending agent in Sender, so a recipient can see who wrote it and who it is from.

subject

string

text

string

The plain-text body.

html

string

An alternative to text, not a replacement for it. A message with no plain part is one the reader on the other side has to render before it can read it.

in_reply_to

string

The message this replies to. It is what puts the reply in a conversation.

Example:

"message_01j9x2v8k3e0080000000000"

reply_all

boolean

Compute recipients from the message being replied to, minus the caller's own addresses.

agent

object

A machine-readable part, for an exchange between two agents. It travels with the message beside the text, and the receiving side can filter on it. Keys outside this shape are dropped, not carried.

Show child attributes

idempotency_key

string

Strongly recommended. A repeat with the same key returns the first attempt's result rather than sending a second message.

Response

The send was accepted for delivery. A 200 here does not mean the message left — a guard that would refuse it does so as an error response instead, before this result is ever built.

state

enum<string>

A new send is queued: accepted for delivery, returned as soon as the message is durably queued and before it is handed on. A repeat with the same idempotency_key reports the message's state now, which may be any later one. held is a message waiting for a person to approve it, with approval_id; it becomes queued when approved and rejected when a person refuses it or the wait lapses. A send that a guard refuses comes back as an error instead of a result.

Available options:

queued,

sending,

sent,

delivered,

bounced,

failed,

held,

rejected

approval_id

string

The approval a held message is waiting on. Absent until the request for approval has been filed, which is retried in the background; the message is held either way.

message

string

The message's identifier.

thread

string

The conversation it belongs to.

reason

string

On a queued message, why it waits instead of going now: provisioning while the sender's domain is being verified (it goes out once it is), or paused. On a repeat for a message that failed, why it failed. Absent when nothing is in the way.

remaining

object

What is left of each sending limit this send counted against, by limit name.

Show child attributes

error

object

Show child attributes

Discovery

Mail

Send

Attachments

Events

Health

Send a message

Authorizations

Body

Response