Worked email lifecycle samples

Copy a request as written, substitute your own ids, and compare the response envelope. Errors follow Devotel Orbit’s { error, meta } envelope and carry a request_id in meta you quote when reporting. The sender chain: register a sender → publish the domain’s DNS records → run a test-send → keep suppressions clean.

1. Register a sender

POST /api/v1/email/senders

Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/email/senders" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "domain": "mail.acme.com",
  "default_from_email": "sales@acme.com",
  "default_from_name": "Acme Sales",
  "default_reply_to": "support@acme.com",
  "isDefault": true
}'

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/email/senders', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "domain": "mail.acme.com",
  "default_from_email": "sales@acme.com",
  "default_from_name": "Acme Sales",
  "default_reply_to": "support@acme.com",
  "isDefault": true
}),
})
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/email/senders", headers=headers, json={
  "domain": "mail.acme.com",
  "default_from_email": "sales@acme.com",
  "default_from_name": "Acme Sales",
  "default_reply_to": "support@acme.com",
  "isDefault": true
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/email/senders", bytes.NewBuffer([]byte(`{
  "domain": "mail.acme.com",
  "default_from_email": "sales@acme.com",
  "default_from_name": "Acme Sales",
  "default_reply_to": "support@acme.com",
  "isDefault": true
}`)))
	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/email/senders')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "domain": "mail.acme.com",
  "default_from_email": "sales@acme.com",
  "default_from_name": "Acme Sales",
  "default_reply_to": "support@acme.com",
  "isDefault": true
}.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/email/senders');
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
{
  "domain": "mail.acme.com",
  "default_from_email": "sales@acme.com",
  "default_from_name": "Acme Sales",
  "default_reply_to": "support@acme.com",
  "isDefault": true
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "esend_9f3ab2d61c4a",
    "domain": "mail.acme.com",
    "default_from_email": "sales@acme.com",
    "default_from_name": "Acme Sales",
    "default_reply_to": "support@acme.com",
    "isDefault": true,
    "streamId": null
  },
  "meta": {
    "request_id": "req_send_reg",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

The domain is registered with the sending provider, which issues real SPF/DKIM records — publish them with your DNS provider, then verify with the DNS-status read below before the sender can send. Omit default_from_email to send as noreply@<domain>.

2. Update the sender’s defaults

PUT /api/v1/email/senders/{senderId}

Request

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/email/senders/{senderId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "default_from_email": "offers@acme.com",
  "default_from_name": "Acme Offers",
  "default_reply_to": "support@acme.com"
}'

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/email/senders/{senderId}', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "default_from_email": "offers@acme.com",
  "default_from_name": "Acme Offers",
  "default_reply_to": "support@acme.com"
}),
})
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.put("https://api.orbit.devotel.io/api/v1/email/senders/{senderId}", headers=headers, json={
  "default_from_email": "offers@acme.com",
  "default_from_name": "Acme Offers",
  "default_reply_to": "support@acme.com"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/email/senders/{senderId}", bytes.NewBuffer([]byte(`{
  "default_from_email": "offers@acme.com",
  "default_from_name": "Acme Offers",
  "default_reply_to": "support@acme.com"
}`)))
	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/email/senders/{senderId}')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "default_from_email": "offers@acme.com",
  "default_from_name": "Acme Offers",
  "default_reply_to": "support@acme.com"
}.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/email/senders/{senderId}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "default_from_email": "offers@acme.com",
  "default_from_name": "Acme Offers",
  "default_reply_to": "support@acme.com"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "esend_9f3ab2d61c4a",
    "domain": "mail.acme.com",
    "default_from_email": "offers@acme.com",
    "default_from_name": "Acme Offers",
    "default_reply_to": "support@acme.com",
    "isDefault": true,
    "streamId": null
  },
  "meta": {
    "request_id": "req_send_upd",
    "timestamp": "2026-08-01T12:05:00.000Z"
  }
}

PUT replaces the From/Reply-To defaults — pass every field you want to keep. Promoting back to default uses the dedicated endpoint below (flipping isDefault: false here is a no-op).

3. Promote a sender to the org default

POST /api/v1/email/senders/{senderId}/set-default

{
  "data": {
    "id": "esend_9f3ab2d61c4a",
    "domain": "mail.acme.com",
    "default_from_email": "offers@acme.com",
    "default_from_name": "Acme Offers",
    "default_reply_to": "support@acme.com",
    "isDefault": true,
    "streamId": null
  },
  "meta": {
    "request_id": "req_send_default",
    "timestamp": "2026-08-01T12:06:00.000Z"
  }
}

The compose dropdown fills with this sender first; the previous default is demoted. Deleting a sender (DELETE /api/v1/email/senders/{senderId}) removes it from the dropdown and accepts no body.

4. Check the domain’s DNS records

GET /api/v1/email/domains/{domainId}/dns-status

Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/email/domains/{domainId}/dns-status" \
  -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/email/domains/{domainId}/dns-status', {
  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/email/domains/{domainId}/dns-status", 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/email/domains/{domainId}/dns-status", 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/email/domains/{domainId}/dns-status')
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/email/domains/{domainId}/dns-status');
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": {
    "domain": "acme.com",
    "punycode": "acme.com",
    "overallStatus": "valid",
    "checkedAt": "2026-08-01T12:15:00.000Z",
    "fromCache": false,
    "isDefault": false,
    "records": [
      {
        "kind": "spf",
        "status": "valid",
        "recordExpected": "v=spf1 include:_spf.send.devotel.io ~all",
        "recordActual": "v=spf1 include:_spf.send.devotel.io ~all",
        "issues": []
      },
      {
        "kind": "dkim",
        "selector": "resend",
        "status": "valid",
        "recordExpected": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA",
        "recordActual": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA",
        "issues": []
      },
      {
        "kind": "dmarc",
        "status": "valid",
        "recordExpected": "v=DMARC1",
        "recordActual": "v=DMARC1; p=none",
        "issues": []
      },
      {
        "kind": "mx",
        "status": "valid",
        "recordExpected": "9 inbound.devotel.io",
        "recordActual": "9 inbound.devotel.io",
        "issues": []
      }
    ]
  },
  "meta": {
    "request_id": "req_dns_status",
    "timestamp": "2026-08-01T12:15:00.000Z"
  }
}

Each record renders a traffic light (valid / warning / invalid / unknown); overallStatus is the worst of them. Compare recordExpected against recordActual to see what your DNS provider is missing. Pass ?refresh=true to re-verify at the provider, not just at DNS. GET /dns-history?days=30 returns the same id with an entries array of dated record snapshots so you can trace propagation.

5. Run a test-send and poll the result

POST /api/v1/email/domains/{domainId}/test-send

{
  "data": {
    "testId": "emailTestSend_53a1c0f9d2",
    "to": "emailTestSend_53a1c0f9d2@orbittest.devotel.io",
    "from": "noreply@orbit.devotel.io",
    "providerMessageId": "r_eml_4c2d1b8f9a",
    "status": "pending"
  },
  "meta": {
    "request_id": "req_test_send",
    "timestamp": "2026-08-01T12:17:00.000Z"
  }
}

Poll GET /api/v1/email/domains/{domainId}/test-send/{testId}/result with the returned testId:

{
  "data": {
    "testId": "emailTestSend_53a1c0f9d2",
    "domain": "acme.com",
    "status": "received",
    "spamScore": 0.4,
    "estimated": false,
    "authResults": {
      "spf": "pass",
      "dkim": "pass",
      "dmarc": "pass",
      "raw": ""
    },
    "verifierSummary": null,
    "placement": null,
    "headersRaw": null,
    "createdAt": "2026-08-01T12:17:00.000Z",
    "receivedAt": "2026-08-01T12:19:11.000Z"
  },
  "meta": {
    "request_id": "req_test_result",
    "timestamp": "2026-08-01T12:20:00.000Z"
  }
}

Until the proof lands the result endpoint returns 404 (retry — it usually settles within a minute). estimated: true means the spamScore is a provisional estimate from the domain’s DNS grid, not the measured receiver verdict. GET /inbox-placement?days=30 aggregates delivered proofs into an inbox/spam/promotions breakdown with an inboxRate percentage.

6. Validate recipient addresses

POST /api/v1/email/validate

Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/email/validate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "recipient@example.com"
}'

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/email/validate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "email": "recipient@example.com"
}),
})
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/email/validate", headers=headers, json={
  "email": "recipient@example.com"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/email/validate", bytes.NewBuffer([]byte(`{
  "email": "recipient@example.com"
}`)))
	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/email/validate')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "email": "recipient@example.com"
}.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/email/validate');
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
{
  "email": "recipient@example.com"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "email": "recipient@example.com",
    "valid": true,
    "suggestion": null,
    "reason": "deliverable"
  },
  "meta": {
    "request_id": "req_val",
    "timestamp": "2026-08-01T12:12:00.000Z"
  }
}

Check addresses before a campaign or import. suggestion carries the corrected domain on mistyped common domains (e.g. gamil.com → gmail.com). For batch checks, POST /api/v1/email/validate/bulk: Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/email/validate/bulk" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "alice@example.com",
    "bad.domain",
    "bob@example.com"
  ]
}'

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/email/validate/bulk', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "emails": [
    "alice@example.com",
    "bad.domain",
    "bob@example.com"
  ]
}),
})
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/email/validate/bulk", headers=headers, json={
  "emails": [
    "alice@example.com",
    "bad.domain",
    "bob@example.com"
  ]
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/email/validate/bulk", bytes.NewBuffer([]byte(`{
  "emails": [
    "alice@example.com",
    "bad.domain",
    "bob@example.com"
  ]
}`)))
	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/email/validate/bulk')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "emails": [
    "alice@example.com",
    "bad.domain",
    "bob@example.com"
  ]
}.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/email/validate/bulk');
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
{
  "emails": [
    "alice@example.com",
    "bad.domain",
    "bob@example.com"
  ]
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "total": 3,
    "valid": 2,
    "invalid": 1,
    "results": {
      "alice@example.com": {
        "valid": true,
        "reason": "deliverable"
      },
      "bad.domain": {
        "valid": false,
        "reason": "syntax_failure"
      }
    },
    "invalidAddresses": [
      "bad.domain"
    ]
  },
  "meta": {
    "request_id": "req_val_bulk",
    "timestamp": "2026-08-01T12:13:00.000Z"
  }
}

Each address reports deliverable, mailbox_full / undeliverable, mailbox_disabled, spamtrap, potential, invalid_mx, no_mx, or syntax_failure. The bulk form returns a results map plus the invalidAddresses list so you don’t have to cross-check every entry.

7. Manage the suppression list

POST /api/v1/email/suppressions

Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/email/suppressions" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "customer@example.com",
  "reason": "manual"
}'

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/email/suppressions', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "email": "customer@example.com",
  "reason": "manual"
}),
})
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/email/suppressions", headers=headers, json={
  "email": "customer@example.com",
  "reason": "manual"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/email/suppressions", bytes.NewBuffer([]byte(`{
  "email": "customer@example.com",
  "reason": "manual"
}`)))
	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/email/suppressions')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "email": "customer@example.com",
  "reason": "manual"
}.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/email/suppressions');
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
{
  "email": "customer@example.com",
  "reason": "manual"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "esuppression_2a9c5f1d",
    "email": "customer@example.com",
    "reason": "manual",
    "bounceType": null,
    "addedAt": "2026-07-20T09:14:00.000Z",
    "expiresAt": null
  },
  "meta": {
    "request_id": "req_supp_add",
    "timestamp": "2026-08-01T12:07:00.000Z"
  }
}

Suppressed addresses never receive sends — the send path rejects them before they reach the provider. Manual reason accepts manual, unsubscribe, complaint, or hard_bounce; bounce/automatic entries (collector handles them) carry the machine reasons. Repeat an add and it returns 200 with the existing entry rather than 201. Bulk-import (POST /api/v1/email/suppressions/bulk-import) accepts either CSV text (one address per line, optional email header row tolerated) or an emails array: Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/email/suppressions/bulk-import" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "csv": "email\nbounced@example.com\ncomplained@example.com",
  "reason": "hard_bounce"
}'

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/email/suppressions/bulk-import', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "csv": "email\nbounced@example.com\ncomplained@example.com",
  "reason": "hard_bounce"
}),
})
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/email/suppressions/bulk-import", headers=headers, json={
  "csv": "email\nbounced@example.com\ncomplained@example.com",
  "reason": "hard_bounce"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/email/suppressions/bulk-import", bytes.NewBuffer([]byte(`{
  "csv": "email\nbounced@example.com\ncomplained@example.com",
  "reason": "hard_bounce"
}`)))
	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/email/suppressions/bulk-import')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "csv": "email\nbounced@example.com\ncomplained@example.com",
  "reason": "hard_bounce"
}.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/email/suppressions/bulk-import');
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
{
  "csv": "email\nbounced@example.com\ncomplained@example.com",
  "reason": "hard_bounce"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "imported": 2,
    "skipped": 0,
    "invalid": 0
  },
  "meta": {
    "request_id": "req_supp_bulk",
    "timestamp": "2026-08-01T12:08:00.000Z"
  }
}

imported counts newly-added entries; skipped counts duplicates already on the list; invalid counts malformed addresses dropped. GET /api/v1/email/suppressions pages the list (?limit=&offset=&search=&reason=):

{
  "data": {
    "entries": [
      {
        "id": "esuppression_2a9c5f1d",
        "email": "customer@example.com",
        "reason": "manual",
        "bounceType": null,
        "addedAt": "2026-07-20T09:14:00.000Z",
        "expiresAt": null
      },
      {
        "id": "esuppression_7b21e03c",
        "email": "bounced@example.com",
        "reason": "hard_bounce",
        "bounceType": "hard",
        "addedAt": "2026-07-18T22:41:00.000Z",
        "expiresAt": "2026-08-17T22:41:00.000Z"
      }
    ],
    "total": 2
  },
  "meta": {
    "request_id": "req_supp_list",
    "timestamp": "2026-08-01T12:09:00.000Z"
  }
}

Remove an entry with DELETE /api/v1/email/suppressions/{id} (returns { "ok": true }). GET /api/v1/email/suppressions/reputation?days=30 reports a suppression-rate breakdown by reason over trailing send volume — the number a deliverability review quotes.

8. Poll readiness and DNS, then promote to default

Once the DNS records publish (step 4), poll until the records show valid and then promote the sender to the org default. The Node.js escape hatch — the SDK is generated from this same OpenAPI contract, so a typed client covers it; raw fetch is fine too:

curl -X GET "https://api.orbit.devotel.io/api/v1/email/domains/dome_2b8c1a4f9e/dns-status?refresh=true" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const domainId = 'dome_2b8c1a4f9e'
const senderId = 'esend_9f3ab2d61c4a'

const poll = async () => {
  const res = await fetch(`https://api.orbit.devotel.io/api/v1/email/domains/${domainId}/dns-status?refresh=true`, {
    headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
  })
  const { data } = await res.json()
  return data.overallStatus === 'valid' // or take `data.records` for the per-record traffic light
}

// Poll every minute; DNS propagation usually settles within 10 minutes.
const deadline = Date.now() + 10 * 60_000
while (Date.now() < deadline) {
  if (await poll()) break
  await new Promise((r) => setTimeout(r, 60_000))
}

await fetch(`https://api.orbit.devotel.io/api/v1/email/senders/${senderId}/set-default`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: '{}', // no body fields — the promotion is id-jointed
})

refresh=true re-verifies at the provider, not just at DNS — pass it when you just published the records. The promote call accepts no body; steps 3–5 above show the shapes.

Warmup, dedicated IP, TLS reports, and inbound routing (advanced)

These complete the sender’s onboard checklist; most tenants never need them. POST /api/v1/email/inbound-routes registers an inbound subdomain→destination mapping (webhook): Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/email/inbound-routes" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "pattern": "support/tickets-<tenant>",
  "destination": {
    "type": "webhook",
    "url": "https://your-app.example/inbound/email",
    "authHeader": "Bearer your-token"
  }
}'

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/email/inbound-routes', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "pattern": "support/tickets-<tenant>",
  "destination": {
    "type": "webhook",
    "url": "https://your-app.example/inbound/email",
    "authHeader": "Bearer your-token"
  }
}),
})
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/email/inbound-routes", headers=headers, json={
  "pattern": "support/tickets-<tenant>",
  "destination": {
    "type": "webhook",
    "url": "https://your-app.example/inbound/email",
    "authHeader": "Bearer your-token"
  }
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/email/inbound-routes", bytes.NewBuffer([]byte(`{
  "pattern": "support/tickets-<tenant>",
  "destination": {
    "type": "webhook",
    "url": "https://your-app.example/inbound/email",
    "authHeader": "Bearer your-token"
  }
}`)))
	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/email/inbound-routes')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "pattern": "support/tickets-<tenant>",
  "destination": {
    "type": "webhook",
    "url": "https://your-app.example/inbound/email",
    "authHeader": "Bearer your-token"
  }
}.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/email/inbound-routes');
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
{
  "pattern": "support/tickets-<tenant>",
  "destination": {
    "type": "webhook",
    "url": "https://your-app.example/inbound/email",
    "authHeader": "Bearer your-token"
  }
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "einrt_3b7f2a9d1c",
    "pattern": "support/tickets-<tenant>",
    "destination": {
      "type": "webhook",
      "url": "https://your-app.example/inbound/email"
    }
  },
  "meta": {
    "request_id": "req_inrt_cre",
    "timestamp": "2026-08-01T12:30:00.000Z"
  }
}

GET /api/v1/email/warmup-plan returns the day-by-day ramp for your ?targetDailyVolume=:

{
  "data": {
    "targetDailyVolume": 50000,
    "startingVolume": 750,
    "growthFactor": 2,
    "lookbackDays": 30,
    "days": [
      {
        "day": 1,
        "dailyVolume": 750
      },
      {
        "day": 3,
        "dailyVolume": 1500
      },
      {
        "day": 9,
        "dailyVolume": 3750
      },
      {
        "day": 25,
        "dailyVolume": 18750
      }
    ]
  },
  "meta": {
    "request_id": "req_warmup_plan",
    "timestamp": "2026-08-01T12:26:00.000Z"
  }
}

GET /api/v1/email/warmup-status adds what you have actually sent (sent.totalSent, the live-day current.maxAllowed, and reputation). GET /api/v1/email/warmup-enforcement answers “which batches get sent when the pattern doesn’t match a plan day” for a requested batch.

Dedicated sending — eligibility, request, status

Check eligibility (GET /api/v1/email/dedicated-sending/eligibility) against your actual trailing-30-day volume, submit a free-text request, then read back the server-authoritative status (GET /api/v1/email/dedicated-sending):

curl -X GET "https://api.orbit.devotel.io/api/v1/email/dedicated-sending/eligibility" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const headers = { 'X-API-Key': process.env.ORBIT_API_KEY! }

const readStatus = async () => {
  const res = await fetch('https://api.orbit.devotel.io/api/v1/email/dedicated-sending', { headers })
  const { data } = await res.json()
  // data.request.state — `none` | `pending_provisioning` | `active`
  // data.eligibility.monthlySendVolume / .thresholdPerMonth / .eligible
  return data
}

Eligibility read (eligibility is also nested inside GET /dedicated-sending):

{
  "data": {
    "monthlySendVolume": 61200,
    "thresholdPerMonth": 50000,
    "eligible": true,
    "status": "eligible",
    "averageDailyVolume": 2040,
    "warmupPlan": {
      "targetDailyVolume": 2040,
      "startingVolume": 750,
      "growthFactor": 2,
      "totalDays": 25,
      "days": [
        { "day": 1, "dailyVolume": 750 },
        { "day": 3, "dailyVolume": 1500 }
      ]
    },
    "message": "At 61200 emails/month this workspace clears the ~50000/month bar for a dedicated sending IP…"
  },
  "meta": {
    "request_id": "req_ded_eligible",
    "timestamp": "2026-08-01T12:32:00.000Z"
  }
}

Status read after submitting POST /dedicated-sending/request with a justification note:

{
  "data": {
    "request": {
      "state": "pending_provisioning",
      "requestedAt": "2026-08-01T12:33:00.000Z",
      "requestedByUserId": "user_2b8c1a4f9e0d",
      "monthlySendVolumeAtRequest": 61200,
      "note": "Bulk sender, outgrowing shared pool."
    },
    "eligibility": {
      "monthlySendVolume": 61200,
      "thresholdPerMonth": 50000,
      "eligible": true,
      "status": "eligible",
      "averageDailyVolume": 2040,
      "warmupPlan": null
    },
    "provisioningAvailable": true,
    "status": "pending_provisioning",
    "actionable": false
  },
  "meta": {
    "request_id": "req_ded_status",
    "timestamp": "2026-08-01T12:34:00.000Z"
  }
}

eligibility.monthlySendVolume comes from real send history, not a client estimate — the request is rejected 403 below the ~50k/month bar, and re-submitting a pending request returns the existing record.

TLS-report and Postmaster reputation reads

Two stateless analysis routes fold the aggregate reports mailbox providers mail (TLS-RPT) and the per-delivery reputation Google / feedback loops expose (Postmaster) into one tenant-side readout — no persistence, no quota to the provider. TLS-RPT — POST /api/v1/email/tls-rpt/reports/analyze (base64-encode the report body you receive, or publish the _smtp._tls.<domain> record providers attach as application/tlsrpt+gzip):

curl -X POST "https://api.orbit.devotel.io/api/v1/email/tls-rpt/reports/analyze" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "reports": [
    {
      "kind": "tlsrpt",
      "transport": "base64-json",
      "data": "eyJkb2N1bWVudCB9"
    }
  ],
  "topFailureTypes": 3
}'

const res = await fetch('https://api.orbit.devotel.io/api/v1/email/tls-rpt/reports/analyze', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reports: [
      { kind: 'tlsrpt', transport: 'base64-json', data: btoa(JSON.stringify(report)) },
    ],
    topFailureTypes: 3,
  }),
})
const { data } = await res.json()
// data.summary.successRate, data.summary.failuresByType, data.downgradeDetected

{
  "data": {
    "summary": {
      "domain": "acme.com",
      "reportCount": 2,
      "windowStart": 1786896000000,
      "windowEnd": 1787068800000,
      "totalSessions": 940,
      "successfulSessions": 897,
      "failedSessions": 43,
      "successRate": 0.9542553191489361,
      "failuresByType": [
        {
          "resultType": "starttls-not-supported",
          "downgradeSignal": true,
          "failedSessionCount": 31,
          "affectedMxHosts": ["mx.example.org"]
        }
      ]
    },
    "submittedReports": 2,
    "skippedReports": 0
  },
  "meta": {
    "request_id": "req_tls_analyze",
    "timestamp": "2026-08-01T12:35:00.000Z"
  }
}

Postmaster — POST /api/v1/email/postmaster/reputation/analyze (POST the payloads a tenant’s scheduled connector fetches from Google Postmaster Tools and your configured feedback loops — we deliberately do not pull from Google directly, so the route stays read-through):

curl -X POST "https://api.orbit.devotel.io/api/v1/email/postmaster/reputation/analyze" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "google": [
    {
      "name": "trafficStats/2026-08-01",
      "domainReputation": "HIGH",
      "userReportedSpamRatio": 0.0002,
      "authSuccessRatios": {
        "spf": 0.99,
        "dkim": 0.98,
        "dmarc": 0.98
      }
    }
  ],
  "feedback": []
}'

const { data } = await fetch('https://api.orbit.devotel.io/api/v1/email/postmaster/reputation/analyze', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ google, feedback }),
}).then((r) => r.json())
// data.domainReputation ("high" | "medium" | "low" | "bad" | "unknown"),
// data.spamRate, data.authSuccessRatios, data.deliveryErrors, data.recommendations

{
  "data": {
    "domainReputation": "high",
    "spamRate": 0.0002,
    "authSuccessRatios": {
      "spf": 0.99,
      "dkim": 0.98,
      "dmarc": 0.98
    },
    "ipReputation": {
      "high": 2,
      "medium": 0,
      "low": 0,
      "bad": 0,
      "unknown": 0,
      "totalIps": 2
    },
    "deliveryErrors": [],
    "recommendations": [],
    "submitted": { "google": 1, "feedback": 0 },
    "skipped": { "google": 0, "feedback": 0 }
  },
  "meta": {
    "request_id": "req_pst_analyze",
    "timestamp": "2026-08-01T12:36:00.000Z"
  }
}

Malformed records are skipped and counted in skipped, never thrown — a corrupt attachment or a single bad snapshot never sinks the batch.

API Reference

All Endpoints

Worked email lifecycle samples