Send an email

POST/api/v2/emails

Queues the message and returns 202 with the id of the first recipient's message record (one record is kept per recipient).

Needs an API key with the send scope. Scopes

Parameters

Body

fromstringrequired

[email protected] or Acme <[email protected]>. Must be an active address on a verified domain in this workspace.

toarrayrequired

Array of recipient addresses. Must be an array, even for one recipient.

ccarray

Array of additional recipients.

bccarray

Array of additional recipients. They receive the message but never appear in any header.

subjectstringrequired

Subject line.

body_htmlstring

HTML body. Send this, body_text, or both.

body_textstring

Plain-text body. Generated from body_html when omitted.

Headers

Idempotency-Keystring

Any string identifying this logical send; reuse it on retries. Remembered for 24 hours. The Try it panel generates one per run.

Notes

The From address must be an active address on a verified domain in your workspace.
Fields not listed here, such as reply_to or attachments, are ignored.
to recipients appear in the To header and cc recipients in Cc; bcc recipients receive the message but never appear in any header, and a message with only bcc recipients is sent with To: undisclosed-recipients:;.
A retry with the same Idempotency-Key within 24 hours returns the original response with status 200 and the header Idempotent-Replayed: true.

curl -X POST "https://api.koltrix.com/api/v2/emails" \
  -H "Authorization: Bearer $KOLTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "from": "[email protected]",
  "to": [
    "[email protected]"
  ],
  "subject": "Your receipt for order 1042",
  "body_html": "<p>Thanks for your order.</p>",
  "body_text": "Thanks for your order."
}'

import { randomUUID } from "node:crypto";

const res = await fetch("https://api.koltrix.com/api/v2/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOLTRIX_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    "from": "[email protected]",
    "to": [
      "[email protected]"
    ],
    "subject": "Your receipt for order 1042",
    "body_html": "<p>Thanks for your order.</p>",
    "body_text": "Thanks for your order."
  }),
});

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

import os, uuid, requests

res = requests.post(
    "https://api.koltrix.com/api/v2/emails",
    headers={
        "Authorization": f"Bearer {os.environ['KOLTRIX_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "from": "[email protected]",
        "to": [
            "[email protected]"
        ],
        "subject": "Your receipt for order 1042",
        "body_html": "<p>Thanks for your order.</p>",
        "body_text": "Thanks for your order."
    },
)
print(res.status_code, res.json())

package main

import (
	"strings"
	"fmt"
	"io"
	"net/http"
	"os"
	"github.com/google/uuid"
)

func main() {
	body := strings.NewReader(`{
  "from": "[email protected]",
  "to": [
    "[email protected]"
  ],
  "subject": "Your receipt for order 1042",
  "body_html": "<p>Thanks for your order.</p>",
  "body_text": "Thanks for your order."
}`)
	req, _ := http.NewRequest("POST", "https://api.koltrix.com/api/v2/emails", body)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KOLTRIX_API_KEY"))
	req.Header.Set("Idempotency-Key", uuid.NewString())

	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/emails");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("KOLTRIX_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "from" => "[email protected]",
        "to" => [
            "[email protected]",
        ],
        "subject" => "Your receipt for order 1042",
        "body_html" => "<p>Thanks for your order.</p>",
        "body_text" => "Thanks for your order.",
    ]),
]);

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

Accepted and queued.

{
  "id": "6f1c2a9e-3b7d-4e41-9a52-0c8d1f3e7b20",
  "status": "queued",
  "queued": true,
  "tracking_url": "/api/v2/messages/6f1c2a9e-3b7d-4e41-9a52-0c8d1f3e7b20",
  "recipient_count": 1
}

A retry with the same Idempotency-Key after the first request finished. The original response, not a second send.

Idempotent-Replayed: true

{
  "id": "6f1c2a9e-3b7d-4e41-9a52-0c8d1f3e7b20",
  "status": "queued",
  "queued": true,
  "tracking_url": "/api/v2/messages/6f1c2a9e-3b7d-4e41-9a52-0c8d1f3e7b20",
  "recipient_count": 1
}

A required field is missing or invalid. The text names the problem.

{
  "error": "from, to, subject are required"
}

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

The From address is not an active address in this workspace. The message says whether the domain is verified.

{
  "error": "from address '[email protected]' is not registered for this account. The domain is verified — add this exact address in Dashboard → Domains."
}

A retry arrived while the first request with this Idempotency-Key was still running. Wait a moment and retry with the same key.

{
  "error": "a request with this Idempotency-Key is still in progress"
}

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

Your plan's send quota is used up. Retrying will not help until resets_at; tell a person.

{
  "code": "quota_exceeded",
  "error": "You've hit today's API sending limit. It resets at midnight UTC, or upgrade to send more now.",
  "kind": "api_sends",
  "limit": 200,
  "used": 200,
  "window": "day",
  "resets_at": "2026-10-03T00:00:00Z",
  "upgrade_url": "https://app.koltrix.com/settings/billing"
}

Koltrix could not check the Idempotency-Key, so it sent nothing. Retry with the same key.

{
  "error": "idempotency store unavailable, please retry"
}

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.

Idempotency-Key is added for you: a new UUID for each send, and the same one if you retry after a network failure.

fromstringrequired

toarrayrequired

ccarray

bccarray

subjectstringrequired

body_htmlstring

body_textstring

Request body · JSON

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

POSThttps://api.koltrix.com/api/v2/emails

Output

What comes back

The response appears here.
Press Send request.