Email Builder API

Drag-and-drop email template builder and asset management Base path: /api/v1/messages/email-builder Endpoint count: 5

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

These five failures cover the template save (POST /api/v1/messages/email-builder/save), which the visual editor autosaves against. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same five classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_emailbuia1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_emailbuia1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "blocks[0].content", "value": "...", "expected": "the correct MJML block shape for this block type" }
    },
    "meta": {
      "request_id": "req_emailbuib2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resave against the head version after re-fetching the template instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_emailbuic3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

409 — Conflict

  {
    "error": {
      "code": "EMAIL_TEMPLATE_VERSION_CONFLICT",
      "message": "The template version you saved against has been superseded.",
      "status": 409,
      "details": { "base_version": 12, "head_version": 14 }
    },
    "meta": {
      "request_id": "req_emailbuid4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Fetch the current template, re-apply the delta, and re-save — a plain retry loops on the same 409.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`EMAIL_TEMPLATE_VERSION_CONFLICT` (409 conflict)	Fetch the current template, re-apply the delta, and re-save	Branch on `error.code`. A plain retry loops on the same 409.

List saved email-builder templates for the tenant

GET /api/v1/messages/email-builder/list

Returns the tenant’s saved email-builder templates (channel email), freshest-first, each with its editable blocks array, rendered plain-text body, previewText, and metadata — the shape the dashboard’s ‘Load template’ picker re-hydrates the builder canvas from. Cursor-paginated via the opaque cursor value returned in pagination.cursor; limit defaults to 50 (max 50). An empty tenant returns an empty data list.

string

—

any

—

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/messages/email-builder/list" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/email-builder/list', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/messages/email-builder/list", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/messages/email-builder/list", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/email-builder/list')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/email-builder/list');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "name": "string",
      "blocks": [
        {}
      ],
      "previewText": "string",
      "metadata": {},
      "updated_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z",
    "pagination": {
      "cursor": null,
      "has_more": false,
      "total": 0
    }
  }
}

Transpile MJML to HTML email

POST /api/v1/messages/email-builder/mjml/render

Transpiles an MJML (mjml.io) source document into the same table-based, inline-styled HTML the block renderer produces, so teams can author templates in MJML instead of the drag-and-drop block model. The response returns best-effort html plus an errors list that reports unsupported components or structural problems without failing the request, and the extracted previewText. Nothing is persisted and no email is sent.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

string

required

The MJML source document to transpile, as a complete <mjml>…</mjml> markup string (1–262,144 characters / 256 KiB). Unsupported components and structural problems are reported in the response errors array without failing the request, so you still receive best-effort HTML.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/email-builder/mjml/render" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "mjml": "<mjml><mj-head><mj-title>Welcome to Orbit</mj-title><mj-preview>Your account is ready</mj-preview></mj-head><mj-body><mj-section><mj-column><mj-text>Welcome aboard! Tap below to finish setting up your account.</mj-text><mj-button href=\"https://app.orbit.devotel.io/get-started\">Get started</mj-button></mj-column></mj-section></mj-body></mjml>"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/email-builder/mjml/render', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "mjml": "<mjml><mj-head><mj-title>Welcome to Orbit</mj-title><mj-preview>Your account is ready</mj-preview></mj-head><mj-body><mj-section><mj-column><mj-text>Welcome aboard! Tap below to finish setting up your account.</mj-text><mj-button href=\"https://app.orbit.devotel.io/get-started\">Get started</mj-button></mj-column></mj-section></mj-body></mjml>"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/messages/email-builder/mjml/render", headers=headers, json={
  "mjml": "<mjml><mj-head><mj-title>Welcome to Orbit</mj-title><mj-preview>Your account is ready</mj-preview></mj-head><mj-body><mj-section><mj-column><mj-text>Welcome aboard! Tap below to finish setting up your account.</mj-text><mj-button href=\"https://app.orbit.devotel.io/get-started\">Get started</mj-button></mj-column></mj-section></mj-body></mjml>"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/email-builder/mjml/render", bytes.NewBuffer([]byte(`{
  "mjml": "<mjml><mj-head><mj-title>Welcome to Orbit</mj-title><mj-preview>Your account is ready</mj-preview></mj-head><mj-body><mj-section><mj-column><mj-text>Welcome aboard! Tap below to finish setting up your account.</mj-text><mj-button href=\"https://app.orbit.devotel.io/get-started\">Get started</mj-button></mj-column></mj-section></mj-body></mjml>"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/email-builder/mjml/render')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "mjml": "<mjml><mj-head><mj-title>Welcome to Orbit</mj-title><mj-preview>Your account is ready</mj-preview></mj-head><mj-body><mj-section><mj-column><mj-text>Welcome aboard! Tap below to finish setting up your account.</mj-text><mj-button href=\"https://app.orbit.devotel.io/get-started\">Get started</mj-button></mj-column></mj-section></mj-body></mjml>"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/email-builder/mjml/render');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "mjml": "<mjml><mj-head><mj-title>Welcome to Orbit</mj-title><mj-preview>Your account is ready</mj-preview></mj-head><mj-body><mj-section><mj-column><mj-text>Welcome aboard! Tap below to finish setting up your account.</mj-text><mj-button href=\"https://app.orbit.devotel.io/get-started\">Get started</mj-button></mj-column></mj-section></mj-body></mjml>"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "html": "string",
    "errors": [
      "string"
    ],
    "previewText": "string"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Render email template to HTML

POST /api/v1/messages/email-builder/render

Renders a drag-and-drop email template — a name plus an ordered blocks array — into a complete, cross-client HTML email document. The response carries both the static HTML and an AMP-for-Email (text/x-amp-html) alternative built from the same blocks, plus the template id (templateId) so the caller can correlate a render with a later save. Nothing is persisted and no email is sent; pair with /api/v1/messages/email-builder/save to store the definition or /api/v1/messages/email-builder/send-test to deliver a proof.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/email-builder/render" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/email-builder/render', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/messages/email-builder/render", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/email-builder/render", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/email-builder/render')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/email-builder/render');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "html": "string",
    "amp": "string",
    "templateId": "string"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Save email template

POST /api/v1/messages/email-builder/save

Persists an email-builder template definition — name, ordered blocks, optional previewText / metadata, and optional id — for later editing in the drag-and-drop builder. The content is stored as a { body, blocks } envelope: the plain-text body serves list snippets and send-time fallbacks, and blocks re-hydrates the builder canvas. Re-saving the same name without an id updates the existing template in place; passing an id that collides with a different template’s name returns 409 TEMPLATE_NAME_ALREADY_EXISTS. Rendering is not part of this call — use /api/v1/messages/email-builder/render for HTML.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/email-builder/save" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/email-builder/save', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/messages/email-builder/save", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/email-builder/save", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/email-builder/save')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/email-builder/save');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "templateId": "string",
    "name": "string",
    "blockCount": 0,
    "saved": false
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Send test email

POST /api/v1/messages/email-builder/send-test

Renders the supplied blocks and sends a test email to to with the subject [Test] <templateName>, and records the send in the tenant’s message history (visible in the dashboard Messages tab) with a test-sent status. The send is BILLED at the channel rate (debited before the provider send — a real paid MT through the shared Resend account), rate-limited per tenant (5/minute), and tenants on the platform’s shared email account must pass the same gates as production sends: the recipient must be a verified org member, the email feature must not be suspended, and a daily test-send cap applies. Requires an explicit, valid to address.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/email-builder/send-test" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/email-builder/send-test', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/messages/email-builder/send-test", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/email-builder/send-test", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/email-builder/send-test')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/email-builder/send-test');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "sent": false,
    "to": "+14155552671",
    "html": "string",
    "message_id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "status": "test_sent"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

API Reference

All Endpoints

Email Builder API

Email Builder API

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

409 — Conflict

60-second retry matrix

List saved email-builder templates for the tenant

Transpile MJML to HTML email

Render email template to HTML

Save email template

Send test email

​Email Builder API

​title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​409 — Conflict

​60-second retry matrix

​List saved email-builder templates for the tenant

​Transpile MJML to HTML email

​Render email template to HTML

​Save email template

​Send test email

Email Builder API

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

409 — Conflict

60-second retry matrix

List saved email-builder templates for the tenant

Transpile MJML to HTML email

Render email template to HTML

Save email template

Send test email