Send your first transactional email

This is the one-shot path to a first real send: verify your domain, create a sender, render a template, dispatch, and watch the result arrive on a webhook. Everything below is runnable — substitute your own API key, domain, and recipient. For the full day-one-to-at-scale plan (warm-up ramps, bulk patterns, deliverability posture), see the Email channel lifecycle guide. This page gets you to one delivered email; that one takes you to volume. You will:

Verify your sending domain
Create a sender profile
Send a templated message
Subscribe to delivery and bounce events
Handle the suppression list
Debug the common first-send errors
Hand off to the at-scale plan

Prefer to skip DNS work while you learn the API? Finish the round trip first against the sandbox — a test key (dv_test_sk_...) or the X-Test-Mode: true header runs the same request shapes with nothing delivered and no real recipient touched. The sandbox guide is Sandbox and test mode; register the real domain in step 1 before your first live send.

Every example below assumes a verified domain and a registered sender. If you draft them against a sandbox key (dv_test_sk_...), they short-circuit before delivery but still exercise validation, so the integration code you write in the sandbox runs unchanged on live keys. Do the domain verification in step 1 before you flip to live traffic. Every API step ships the same request in all six forms — cURL, Node.js (TypeScript), Python, Go, Ruby, and PHP — so you can copy the one that matches your stack. Every response carries the same envelope: a data payload plus meta.request_id to correlate with webhooks and support.

1. Verify your sending domain

Everything downstream — sender validation, tracking, deliverability — hangs off a verified domain. Add your domain under Channels → Email → Domains, which lists the exact DNS records (SPF, DKIM, DMARC, and the Return-Path CNAME) to publish at your DNS provider. Once the records propagate, run Verify DNS on the domain row and confirm the per-record traffic-light view grades green:

curl -X POST https://api.orbit.devotel.io/api/v1/settings/channels/email/verify-dns \
  -H "X-API-Key: dv_live_sk_..."

import { Orbit } from "@devotel-orbit/node";

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

// No typed helper for Verify DNS — the untyped request() is the
// documented form for routes below the typed modules.
await orbit.request("POST", "/settings/channels/email/verify-dns");

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/settings/channels/email/verify-dns",
    headers=headers,
)
print(resp.status_code, resp.json()["meta"]["request_id"])

client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
if err != nil {
    log.Fatal(err)
}

var out map[string]any
err = client.Request(context.Background(), "POST",
    "/settings/channels/email/verify-dns", nil, nil, &out, "")
if err != nil {
    log.Fatal(err)
}

require "orbit_sdk"

client = OrbitSdk::Client.from_env # reads ORBIT_API_KEY

client.request("POST", "/settings/channels/email/verify-dns")

<?php
$client = OrbitClient::fromEnv(); // reads ORBIT_API_KEY

$client->request('POST', '/settings/channels/email/verify-dns');

Then read the graded status for the domain:

curl https://api.orbit.devotel.io/api/v1/email/domains/default/dns-status \
  -H "X-API-Key: dv_live_sk_..."

const status = await orbit.request("GET", "/email/domains/default/dns-status");
console.log(status.data);

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/email/domains/default/dns-status",
    headers=headers,
)
print(resp.json()["data"])

var status map[string]any
err = client.Request(context.Background(), "GET",
    "/email/domains/default/dns-status", nil, nil, &status, "")
if err != nil {
    log.Fatal(err)
}
fmt.Println(status["data"])

status = client.request("GET", "/email/domains/default/dns-status")
puts status["data"]

<?php
$status = $client->request('GET', '/email/domains/default/dns-status');
print_r($status['data']);

Every record you intend to sign with must grade valid. If your DNS lives in a Cloudflare zone, the Cloudflare auto-configure guide can create the missing records for you from the same domain row; either way, re-run Verify DNS after any manual change.

2. Create a sender profile

Sends need a registered sender row so the platform can bind your from address to a verified domain. Register one under Channels → Email → Senders, or over the API:

curl -X POST https://api.orbit.devotel.io/api/v1/email/senders \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "yourdomain.com",
    "default_from_email": "hello@yourdomain.com",
    "default_from_name": "Acme"
  }'

const sender = await orbit.request("POST", "/email/senders", {
  domain: "yourdomain.com",
  default_from_email: "hello@yourdomain.com",
  default_from_name: "Acme",
});
console.log(sender.data.id); // esend_…

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/email/senders",
    headers={**headers, "Content-Type": "application/json"},
    json={"domain": "yourdomain.com",
          "default_from_email": "hello@yourdomain.com",
          "default_from_name": "Acme"},
)
print(resp.json()["data"]["id"])  # esend_…

payload := map[string]any{
    "domain":             "yourdomain.com",
    "default_from_email": "hello@yourdomain.com",
    "default_from_name":  "Acme",
}
var sender map[string]any
err = client.Request(context.Background(), "POST",
    "/email/senders", nil, payload, &sender, "")
if err != nil {
    log.Fatal(err)
}
fmt.Println(sender["data"].(map[string]any)["id"]) // esend_…

sender = client.request("POST", "/email/senders", json_body: {
  domain: "yourdomain.com",
  default_from_email: "hello@yourdomain.com",
  default_from_name: "Acme",
})
puts sender.dig("data", "id") # esend_…

<?php
$sender = $client->request('POST', '/email/senders', null, [
    'domain' => 'yourdomain.com',
    'default_from_email' => 'hello@yourdomain.com',
    'default_from_name' => 'Acme',
]);
echo $sender['data']['id'] . PHP_EOL; // esend_…

The response carries your sender id (esend_...):

{
  "data": {
    "id": "esend_01J9Z8ABCDEF",
    "domain": "yourdomain.com",
    "default_from_email": "hello@yourdomain.com",
    "isDefault": false
  },
  "meta": { "request_id": "req_01J9Z8ABCDEF", "timestamp": "2026-10-27T09:00:00Z" }
}

When you later omit from on a send, the sender marked isDefault resolves the address; set that flag on the one you want as the fallback. One sender row is enough for a first send — add aliases later.

3. Send a templated message

The send endpoint takes a finished html (or text) body — it does not accept a template_id. Either html or text must be non-empty, or the request is rejected before anything is queued. The one-shot send — inline body, done in your stack’s form:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/email \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "hello@yourdomain.com",
    "subject": "Your Acme code",
    "html": "<p>Your one-time code: 123456</p>"
  }'
# First-send failures: 403 domain unverified, 503 CHANNEL_NOT_CONFIGURED,
# 422 NO_SENDER_CONFIGURED / RECIPIENT_OPTED_OUT / VALIDATION_ERROR,
# 429 RATE_LIMITED — see step 6.

const { data: message } = await orbit.messages.sendEmail({
  to: "user@example.com",
  from: "hello@yourdomain.com",
  subject: "Your Acme code",
  html: "<p>Your one-time code: 123456</p>",
});
console.log(message.id); // msg_…
// First-send failures: 403 domain unverified, 503 CHANNEL_NOT_CONFIGURED,
// 422 NO_SENDER_CONFIGURED / RECIPIENT_OPTED_OUT / VALIDATION_ERROR,
// 429 RATE_LIMITED — see step 6.

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/messages/email",
    headers={**headers, "Content-Type": "application/json"},
    json={"to": "user@example.com",
          "from": "hello@yourdomain.com",
          "subject": "Your Acme code",
          "html": "<p>Your one-time code: 123456</p>"},
)
print(resp.status_code, resp.json()["data"]["succeeded"])
# First-send failures: 403 domain unverified, 503 CHANNEL_NOT_CONFIGURED,
# 422 NO_SENDER_CONFIGURED / RECIPIENT_OPTED_OUT / VALIDATION_ERROR,
# 429 RATE_LIMITED — see step 6.

payload := map[string]any{
    "to":      "user@example.com",
    "from":    "hello@yourdomain.com",
    "subject": "Your Acme code",
    "html":    "<p>Your one-time code: 123456</p>",
}
var sent map[string]any
err = client.Request(context.Background(), "POST",
    "/messages/email", nil, payload, &sent, "")
if err != nil {
    log.Fatal(err)
}
fmt.Println(sent["data"].(map[string]any)["succeeded"])
// First-send failures: 403 domain unverified, 503 CHANNEL_NOT_CONFIGURED,
// 422 NO_SENDER_CONFIGURED / RECIPIENT_OPTED_OUT / VALIDATION_ERROR,
// 429 RATE_LIMITED — see step 6.

sent = client.request("POST", "/messages/email", json_body: {
  to: "user@example.com",
  from: "hello@yourdomain.com",
  subject: "Your Acme code",
  html: "<p>Your one-time code: 123456</p>",
})
puts sent.dig("data", "succeeded")
# First-send failures: 403 domain unverified, 503 CHANNEL_NOT_CONFIGURED,
# 422 NO_SENDER_CONFIGURED / RECIPIENT_OPTED_OUT / VALIDATION_ERROR,
# 429 RATE_LIMITED — see step 6.

<?php
$sent = $client->request('POST', '/messages/email', null, [
    'to'      => 'user@example.com',
    'from'    => 'hello@yourdomain.com',
    'subject' => 'Your Acme code',
    'html'    => '<p>Your one-time code: 123456</p>',
]);
print_r($sent['data']['succeeded']);
// First-send failures: 403 domain unverified, 503 CHANNEL_NOT_CONFIGURED,
// 422 NO_SENDER_CONFIGURED / RECIPIENT_OPTED_OUT / VALIDATION_ERROR,
// 429 RATE_LIMITED — see step 6.

A clean dispatch returns 202 with data.succeeded carrying one row per recipient, and the envelope meta.request_id to correlate with the webhook events below:

{
  "data": {
    "succeeded": [
      { "to": "user@example.com", "id": "msg_01J9Z8ABCDEF" }
    ]
  },
  "meta": { "request_id": "req_01J9Z8ABCDEF", "timestamp": "2026-10-27T09:00:00Z" }
}

For template variables ({{...}} merge tags in a saved block layout) you render first, then send the rendered HTML — two passes:

Render with POST /api/v1/messages/email-builder/render. The response carries the rendered html, an AMP-for-Email alternative, and a templateId to correlate with a later save.
Resolve every {{...}} tag in the rendered HTML, then dispatch it through the same send endpoint. An unresolved tag lands on the wire as the literal string, so resolve them all before sending.

# 1. Render the saved layout
curl -X POST https://api.orbit.devotel.io/api/v1/messages/email-builder/render \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_email",
    "blocks": [{"type": "text", "content": {"text": "Your one-time code: {{code}}"}}]
  }'

# 2. Resolve {{code}} in the returned html, then dispatch it
curl -X POST https://api.orbit.devotel.io/api/v1/messages/email \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type": "application/json" \
  -d '{
    "to": "user@example.com",
    "from": "hello@yourdomain.com",
    "subject": "Your Acme code",
    "html": "<p>Your one-time code: 123456</p>"
  }'
# Empty-body guard: 422 VALIDATION_ERROR if neither html nor text is set.

// 1. Render the saved layout — render has no typed helper, use request()
const rendered = await orbit.request<{ data: { html: string } }>(
  "POST",
  "/messages/email-builder/render",
  {
    name: "welcome_email",
    blocks: [{ type: "text", content: { text: "Your one-time code: {{code}}" } }],
  },
);

// 2. Resolve every {{…}} tag, then dispatch through the typed send
const html = rendered.data.html.replaceAll("{{code}}", "123456");
const { data: message } = await orbit.messages.sendEmail({
  to: "user@example.com",
  from: "hello@yourdomain.com",
  subject: "Your Acme code",
  html,
});
console.log(message.id); // msg_…
// Empty-body guard: 422 VALIDATION_ERROR if neither html nor text is set.

import os, requests

key = os.environ["ORBIT_API_KEY"]
base = "https://api.orbit.devotel.io"
headers = {"X-API-Key": key, "Content-Type": "application/json"}

rendered = requests.post(
    f"{base}/api/v1/messages/email-builder/render",
    headers=headers,
    json={"name": "welcome_email",
          "blocks": [{"type": "text", "content": {"text": "Your one-time code: {{code}}"}}]},
).json()["data"]["html"]

html = rendered.replace("{{code}}", "123456")

resp = requests.post(
    f"{base}/api/v1/messages/email",
    headers=headers,
    json={"to": "user@example.com", "subject": "Your Acme code", "html": html},
)
print(resp.status_code, resp.json()["data"]["succeeded"])
# Empty-body guard: 422 VALIDATION_ERROR if neither html nor text is set.

// 1. Render the saved layout
renderBody := map[string]any{
    "name": "welcome_email",
    "blocks": []map[string]any{{
        "type":    "text",
        "content": map[string]any{"text": "Your one-time code: {{code}}"},
    }},
}
var rendered map[string]any
err = client.Request(context.Background(), "POST",
    "/messages/email-builder/render", nil, renderBody, &rendered, "")
if err != nil {
    log.Fatal(err)
}

// 2. Resolve every {{…}} tag, then dispatch
html := strings.ReplaceAll(
    rendered["data"].(map[string]any)["html"].(string), "{{code}}", "123456")
sendBody := map[string]any{
    "to":      "user@example.com",
    "from":    "hello@yourdomain.com",
    "subject": "Your Acme code",
    "html":    html,
}
var sent map[string]any
err = client.Request(context.Background(), "POST",
    "/messages/email", nil, sendBody, &sent, "")
if err != nil {
    log.Fatal(err)
}
// Empty-body guard: 422 VALIDATION_ERROR if neither html nor text is set.

# 1. Render the saved layout
rendered = client.request("POST", "/messages/email-builder/render", json_body: {
  name: "welcome_email",
  blocks: [{ type: "text", content: { text: "Your one-time code: {{code}}" } }],
})

# 2. Resolve every {{…}} tag, then dispatch
html = rendered.dig("data", "html").gsub("{{code}}", "123456")
sent = client.request("POST", "/messages/email", json_body: {
  to: "user@example.com",
  from: "hello@yourdomain.com",
  subject: "Your Acme code",
  html: html,
})
puts sent.dig("data", "succeeded")
# Empty-body guard: 422 VALIDATION_ERROR if neither html nor text is set.

<?php
// 1. Render the saved layout
$rendered = $client->request('POST', '/messages/email-builder/render', null, [
    'name' => 'welcome_email',
    'blocks' => [['type' => 'text', 'content' => ['text' => 'Your one-time code: {{code}}']]],
]);

// 2. Resolve every {{…}} tag, then dispatch
$html = str_replace('{{code}}', '123456', $rendered['data']['html']);
$sent = $client->request('POST', '/messages/email', null, [
    'to'      => 'user@example.com',
    'from'    => 'hello@yourdomain.com',
    'subject' => 'Your Acme code',
    'html'    => $html,
]);
print_r($sent['data']['succeeded']);
// Empty-body guard: 422 VALIDATION_ERROR if neither html nor text is set.

Save the template for reuse with POST /api/v1/messages/email-builder/save — the full mechanics are in Using Templates. Register one endpoint that subscribes the delivery family and the engagement pair, and filter on channel: "email":

message.delivered — accepted by the recipient server
message.failed — bounced (hard or soft) or marked as spam
email.opened / email.clicked — engagement (first-open deduped; clicks fire on every distinct click)

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.example.com/webhooks/orbit",
    "events": ["message.delivered", "message.failed", "email.opened", "email.clicked"]
  }'

const { data: endpoint } = await orbit.webhooks.create({
  url: "https://yourapp.example.com/webhooks/orbit",
  events: ["message.delivered", "message.failed", "email.opened", "email.clicked"],
});
console.log(endpoint.signing_secret); // store it — every delivery signs with it

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/webhooks",
    headers={**headers, "Content-Type": "application/json"},
    json={"url": "https://yourapp.example.com/webhooks/orbit",
          "events": ["message.delivered", "message.failed",
                     "email.opened", "email.clicked"]},
)
print(resp.json()["data"]["signing_secret"])

payload := map[string]any{
    "url": "https://yourapp.example.com/webhooks/orbit",
    "events": []string{
        "message.delivered", "message.failed",
        "email.opened", "email.clicked",
    },
}
var endpoint map[string]any
err = client.Request(context.Background(), "POST",
    "/webhooks", nil, payload, &endpoint, "")
if err != nil {
    log.Fatal(err)
}
fmt.Println(endpoint["data"].(map[string]any)["signing_secret"])

endpoint = client.request("POST", "/webhooks", json_body: {
  url: "https://yourapp.example.com/webhooks/orbit",
  events: ["message.delivered", "message.failed",
           "email.opened", "email.clicked"],
})
puts endpoint.dig("data", "signing_secret")

<?php
$endpoint = $client->request('POST', '/webhooks', null, [
    'url' => 'https://yourapp.example.com/webhooks/orbit',
    'events' => ['message.delivered', 'message.failed', 'email.opened', 'email.clicked'],
]);
echo $endpoint['data']['signing_secret'] . PHP_EOL;

The created endpoint returns the {data, meta} envelope with a generated signing_secret inside data — store it; you verify every inbound POST against it:

{
  "data": {
    "url": "https://yourapp.example.com/webhooks/orbit",
    "events": ["message.delivered", "message.failed", "email.opened", "email.clicked"],
    "signing_secret": "whsec_01J9Z8ABCDEF"
  },
  "meta": { "request_id": "req_01J9Z8ABCDEF", "timestamp": "2026-10-27T09:00:00Z" }
}

Verify the X-Orbit-Signature header on every delivery and return 2xx within the delivery window — the walkthrough is in Receive your first webhook. In sandbox mode the send is short-circuited, so you can exercise your verification and retry handling without a live recipient; the sandbox guide covers the canned outcomes.

5. Handle the suppression list

Hard bounces, exhausted soft bounces, complaints, and unsubscribes are held out of future sends automatically, and the served quota slot is refunded at the pre-send gate. Manage the list yourself under Channels → Email → Suppressions — search it, export, add manual entries, or bulk-import from a previous ESP. Add a manual entry — reason is one of manual, unsubscribe, complaint, or hard_bounce:

curl -X POST https://api.orbit.devotel.io/api/v1/email/suppressions \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "reason": "manual"
  }'
# 201 when newly created, 200 when the address was already listed.

const added = await orbit.request("POST", "/email/suppressions", {
  email: "user@example.com",
  reason: "manual",
});
console.log(added.data.email);
// 201 when newly created, 200 when the address was already listed.

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/email/suppressions",
    headers={**headers, "Content-Type": "application/json"},
    json={"email": "user@example.com", "reason": "manual"},
)
print(resp.status_code, resp.json()["data"]["email"])
# 201 when newly created, 200 when the address was already listed.

payload := map[string]any{
    "email":  "user@example.com",
    "reason": "manual",
}
var added map[string]any
err = client.Request(context.Background(), "POST",
    "/email/suppressions", nil, payload, &added, "")
if err != nil {
    log.Fatal(err)
}
fmt.Println(added["data"].(map[string]any)["email"])
// 201 when newly created, 200 when the address was already listed.

added = client.request("POST", "/email/suppressions", json_body: {
  email: "user@example.com",
  reason: "manual",
})
puts added.dig("data", "email")
# 201 when newly created, 200 when the address was already listed.

<?php
$added = $client->request('POST', '/email/suppressions', null, [
    'email' => 'user@example.com',
    'reason' => 'manual',
]);
echo $added['data']['email'] . PHP_EOL;
// 201 when newly created, 200 when the address was already listed.

Check whether an address is held before you route a send to it — page the list with search:

curl "https://api.orbit.devotel.io/api/v1/email/suppressions?search=user@example.com" \
  -H "X-API-Key: dv_live_sk_..."
# A non-empty data array means the address is held out of sends.

const list = await orbit.request(
  "GET",
  "/email/suppressions?search=user@example.com",
);
console.log(list.data.length > 0 ? "suppressed" : "clear");

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/email/suppressions",
    headers=headers,
    params={"search": "user@example.com"},
)
rows = resp.json()["data"]
print("suppressed" if rows else "clear")

q := url.Values{"search": []string{"user@example.com"}}
var list map[string]any
err = client.Request(context.Background(), "GET",
    "/email/suppressions", q, nil, &list, "")
if err != nil {
    log.Fatal(err)
}
held := len(list["data"].([]any)) > 0
fmt.Println(held)

list = client.request("GET", "/email/suppressions",
                      query: { "search" => "user@example.com" })
puts list["data"].any? ? "suppressed" : "clear"

<?php
$list = $client->request('GET', '/email/suppressions', ['search' => 'user@example.com']);
echo (count($list['data']) > 0 ? 'suppressed' : 'clear') . PHP_EOL;

Removal is a deliberate action: a re-bounce or a re-complaint re-suppresses the address. For a per-contact reachability check before you route a send, use the contact deliverability health guide.

6. Common first-send errors

Domain unverified (403). A provider-side 403 returns as 403 VALIDATION_ERROR with details.provider_message. Most often this is a sending domain whose verification regressed or never completed. Re-run Verify DNS, then check GET /api/v1/email/domains/:domainId/dns-status until every record grades valid.
CHANNEL_NOT_CONFIGURED (503). The email provider was never set up for the tenant. Finish step 1, then your sender in step 2.
Suppressed recipient (RECIPIENT_OPTED_OUT, 422). The recipient is on your suppression list and the quota slot is refunded. Route the flow to an alternate channel instead of un-suppressing by reflex.
Invalid from (NO_SENDER_CONFIGURED, 422). No sender resolved — either no row owns the address and no default applies, or the defaulted address never got registered. Re-check step 2.
VALIDATION_ERROR (422) on the body. Malformed addresses, an empty body, or a disallowed attachment. Either html or text must be non-empty; unresolved merge tags would ship the literal {{...}} string to the recipient, so resolve them all before dispatch.
RATE_LIMITED (429). You crossed the per-tenant channel pool (roughly 200 sends per minute). Back off and retry.

The send and suppression snippets above carry these codes as inline comments in every language tab, so the expectation travels with the code you copy. The full catalog with remediations is in Error Catalog.

7. At scale

This guide got you one clean send. The Email channel lifecycle guide is the day-one-to-at-scale plan — warm-up ramps before dedicated-IP volume, bulk sends up to 10,000 recipients per call, per-domain open and click tracking, and per-contact deliverability health. If you will also send campaigns or newsletters, split them into separate sending streams so bulk volume can never drag your receipts’ deliverability down with it. The Channels → Email reference indexes the full channel surface.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Send your first transactional email

Send your first transactional email

1. Verify your sending domain

2. Create a sender profile

3. Send a templated message

5. Handle the suppression list

6. Common first-send errors

7. At scale

​Send your first transactional email

​1. Verify your sending domain

​2. Create a sender profile

​3. Send a templated message

​4. Subscribe to delivery and bounce events

​5. Handle the suppression list

​6. Common first-send errors

​7. At scale

Send your first transactional email

1. Verify your sending domain

2. Create a sender profile

3. Send a templated message

4. Subscribe to delivery and bounce events

5. Handle the suppression list

6. Common first-send errors

7. At scale