Transactional email API reference

Endpoint and authentication

• POST https://viesti.email/v1/send, over HTTPS only. Any method other than POST gets 405.
• Authorization: Bearer <API key>, using the same keys as SMTP, created on the Credentials page.
• Content-Type: application/json; a charset parameter is allowed.

Request body

One JSON object. Fields not listed here are rejected with 400.

With subject, text and html, Viesti builds the message: From, To with every address in to, Subject, Date, Message-ID and a UTF-8 quoted-printable body. Every recipient sees the others in To; to send individually, make one request per recipient.

For headers the built message does not have, such as Reply-To, Cc, custom headers or attachments, send raw. Then to is the delivery list: every address in it receives the message, whether or not it appears in the headers. The From header must use the same domain as from, and the SMTP header rules apply, including the added Date and Message-ID when they are missing.

The message, built or raw, may be up to 10 MB. The JSON body may be up to six times that plus 64 KiB, to leave room for escaping.

Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{"id":"b695f8a9-369b-4bff-9aff-92ba07a414ca","status":"accepted"}

accepted means Viesti stored and queued the message; it is not yet delivered. The id is the Message ID in Activity, where the delivery timeline and each recipient's result appear. A message the content screen holds for review is also accepted, and Activity shows it as quarantined.

Errors

Errors return a JSON body with an error field, {"error":"…"}, and the message is not sent.

Retries and duplicates

Retry 429 submission quota exceeded and 503 after the Retry-After seconds; other errors fail again until you change the request. A 429 without a JSON body comes from the request rate limit in front of the API; see limits. The API has no idempotency key: if a request times out without a response, the message may already be accepted. When a duplicate would matter, look for it in Activity before you resend.

Examples

Each example reads the key from VIESTI_API_KEY. Replace [email protected] with an address at your verified domain.

curl

curl https://viesti.email/v1/send \
  -H "Authorization: Bearer $VIESTI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Your receipt",
    "text": "Thanks for your order.",
    "html": "<p>Thanks for your order.</p>"
  }'

Node.js

With the built-in fetch, available without a flag since Node.js 18 (Node.js documentation; checked 26 September 2026), in an ES module such as send.mjs:

const res = await fetch("https://viesti.email/v1/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIESTI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "Acme <[email protected]>",
    to: ["[email protected]"],
    subject: "Your receipt",
    text: "Thanks for your order.",
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`Viesti ${res.status}: ${body.error}`);
console.log(body.id);

Python

With requests:

import os

import requests

response = requests.post(
    "https://viesti.email/v1/send",
    headers={"Authorization": f"Bearer {os.environ['VIESTI_API_KEY']}"},
    json={
        "from": "Acme <[email protected]>",
        "to": ["[email protected]"],
        "subject": "Your receipt",
        "text": "Thanks for your order.",
    },
    timeout=30,
)
if response.status_code != 202:
    raise RuntimeError(f"Viesti {response.status_code}: {response.json()['error']}")
print(response.json()["id"])

A raw message

The same send with a Reply-To header. JSON strings spell CRLF as \r\n:

curl https://viesti.email/v1/send \
  -H "Authorization: Bearer $VIESTI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "raw": "From: Acme <[email protected]>\r\nTo: [email protected]\r\nReply-To: [email protected]\r\nSubject: Your receipt\r\nContent-Type: text/plain; charset=utf-8\r\n\r\nThanks for your order.\r\n"
  }'

The HTTP API has one endpoint. There are no webhooks and no endpoint for message status or suppressions; both are in the dashboard. To send from an existing SMTP mailer instead, see SMTP settings.