Send, or propose a send

POST/api/v2/agent-mailboxes/:id/send

What happens depends on the mailbox's autonomy level.

Needs an API key with the send scope. Scopes

Parameters

Path

idstringrequired

The agent mailbox id, or me.

Body

toarrayrequired

Recipient addresses.

ccarray

Cc addresses.

subjectstringrequired

One line, up to 500 characters.

body_textstringrequired

Plain text body, up to 100 KB.

in_reply_tostring

The Message-ID being answered: no spaces, angle brackets or line breaks.

thread_idstring

The conversation to reply in.

Headers

Idempotency-Keystring

Makes a retry return the first result. Up to 200 characters.

Notes

suggest saves a draft for a person and returns 202 with status: saved_as_suggestion.
approve puts the message in the Action center for a person to approve and returns 202 with status: pending_approval and an item_id.
auto sends right away (200, status: sent) only when every rule passes: each recipient is in the mailbox's allowed recipients or already known from the thread (never someone new), the daily cap is not reached, it is outside quiet hours, the kill switch is off, and no message in the thread is rated risky by the injection shield.
If any rule fails the message is held for approval (202) and held_because says why.
auto also needs a thread_id (it only replies inside a conversation), needs every recipient to be on the mailbox's allowed recipients AND someone already in the conversation, and is switched off on the server unless the workspace operator turned it on (held_because: auto_disabled).
thread_id must be a conversation the mailbox has received mail in.
Up to 20 recipients; bcc is never sent automatically.
Pass an Idempotency-Key header so a retry returns the first result instead of acting twice.
The workspace's billing state and plan send quota apply: an expired or suspended workspace gets 402, a workspace over its quota gets 429.

curl -X POST "https://api.koltrix.com/api/v2/agent-mailboxes/me/send" \
  -H "Authorization: Bearer $KOLTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": [
    "[email protected]"
  ],
  "subject": "Re: Opening hours?",
  "body_text": "We are open 9 to 5, Monday to Friday.",
  "thread_id": "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9"
}'

const res = await fetch("https://api.koltrix.com/api/v2/agent-mailboxes/me/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOLTRIX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "to": [
      "[email protected]"
    ],
    "subject": "Re: Opening hours?",
    "body_text": "We are open 9 to 5, Monday to Friday.",
    "thread_id": "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9"
  }),
});

console.log(res.status, await res.json());

import os, requests

res = requests.post(
    "https://api.koltrix.com/api/v2/agent-mailboxes/me/send",
    headers={
        "Authorization": f"Bearer {os.environ['KOLTRIX_API_KEY']}",
    },
    json={
        "to": [
            "[email protected]"
        ],
        "subject": "Re: Opening hours?",
        "body_text": "We are open 9 to 5, Monday to Friday.",
        "thread_id": "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9"
    },
)
print(res.status_code, res.json())

package main

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

func main() {
	body := strings.NewReader(`{
  "to": [
    "[email protected]"
  ],
  "subject": "Re: Opening hours?",
  "body_text": "We are open 9 to 5, Monday to Friday.",
  "thread_id": "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9"
}`)
	req, _ := http.NewRequest("POST", "https://api.koltrix.com/api/v2/agent-mailboxes/me/send", body)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KOLTRIX_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out))
}

<?php

$ch = curl_init("https://api.koltrix.com/api/v2/agent-mailboxes/me/send");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("KOLTRIX_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "to" => [
            "[email protected]",
        ],
        "subject" => "Re: Opening hours?",
        "body_text" => "We are open 9 to 5, Monday to Friday.",
        "thread_id" => "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
    ]),
]);

$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $response;

Success.

{
  "status": "pending_approval",
  "item_id": "5c4b3a29-1807-4e6d-9c8b-7a6958473625",
  "sent": false,
  "held_because": ""
}

The body is not valid JSON, or a field has the wrong type.

{
  "error": "invalid body"
}

The API key is missing, malformed, unknown or revoked.

{
  "error": "invalid or revoked api key"
}

The key is valid but does not have the send scope.

{
  "error": "missing permission: send"
}

No such record in this workspace.

{
  "error": "thread not found"
}

More than 60 requests a minute on this key. Wait Retry-After seconds. No code field.

Retry-After: 60

{
  "error": "rate limit exceeded — 60 requests per minute per API key"
}

Try it below with your own key. Every sample reads the key from KOLTRIX_API_KEY.

Try it

Send this request from your browser.

Input

What you send

API key

Stays in this browser tab (sessionStorage) and goes only to api.koltrix.com. Create one under Settings → API keys.

Requests are real and this one changes data in your workspace. Koltrix has no test mode, so use a dedicated key with only the permissions you need and revoke it when you are done.

idstringrequired

toarrayrequired

ccarray

subjectstringrequired

body_textstringrequired

in_reply_tostring

thread_idstring

Request body · JSON

Valid JSON. The fields above and this editor stay in sync.

POSThttps://api.koltrix.com/api/v2/agent-mailboxes/me/send

Output

What comes back

The response appears here.
Press Send request.