​

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. Debug the common first-send errors
7. Hand off to the at-scale plan

​

1. Verify your sending domain

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

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

​

2. Create a sender profile

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

​

3. Send a templated message

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

1. 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.
2. 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.

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"])

​

4. Subscribe to delivery and bounce events

• 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"]
  }'

​

5. Handle the suppression list

​

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.

​

7. At scale