Email API

Endpoints under the /api/v1/email base path. This page covers the public one-click unsubscribe handler, the authenticated recipient validation (list-hygiene) endpoints, and the IP warm-up ramp endpoints. Sending email goes through the unified Messaging API. Base path: /api/v1/email

Using the SDKs

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

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

const res = await orbit.email.listDomains();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/email")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Sending email

Send runs through the Messaging API, not the /api/v1/email base path — this page is where email API users land, so here is the round-trip in full. Two shapes, same pipeline: the unified send with an explicit channel, and the email-native route. Unified send (POST /api/v1/messages) with channel: "email":

curl -X POST "https://api.orbit.devotel.io/api/v1/messages" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "to": "alice@example.com",
    "from": "Orbit by Devotel <noreply@orbit.devotel.io>",
    "subject": "Your receipt",
    "body": "Thanks for your purchase."
  }'

Response 202:

{
  "data": {
    "id": "msg_9f2c1ab4d8e54702",
    "status": "queued",
    "channel": "email",
    "to": "alice@example.com",
    "created_at": "2026-08-25T04:12:00.000Z"
  },
  "meta": { "requestId": "req_01K3Z2…" }
}

The email-native route (POST /api/v1/messages/email) carries the email-specific fields directly — subject plus html/text, reply_to, cc, bcc, and attachments:

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/email" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "alice@example.com",
    "from": "Orbit by Devotel <noreply@orbit.devotel.io>",
    "subject": "Your receipt",
    "html": "<p>Thanks for your purchase.</p>"
  }'

Either shape returns the same accepted-for-delivery envelope shown above (id, status, channel). Delivery status then moves through the sent → delivered lifecycle; any volume above a warm-up cap waits as queued. On the unified send the email subject travels in subject; on the bulk send (POST /api/v1/messages/bulk) it travels in each row’s metadata.subject. Full field reference for every messaging route: Messaging API.

Unsubscribe

The public one-click unsubscribe surface that the List-Unsubscribe and List-Unsubscribe-Post headers in outbound email reference. RFC 8058 compliant. Authentication: HMAC-token (embedded in URL). Not Clerk-authenticated — these URLs are designed to be opened by the recipient’s mail client without any session.

Method	Path	Purpose
`GET`	`/api/v1/email/unsubscribe/{token}`	Render the unsubscribe page
`POST`	`/api/v1/email/unsubscribe/{token}`	Process one-click unsubscribe (RFC 8058)

You don’t typically call these endpoints from your own application — Orbit injects the URLs into outbound email automatically.

Recipient validation

Real-time recipient list-hygiene checks (SendGrid Email Validation API parity). Score an address before you send to it: syntax, disposable-domain and role-account detection, MX presence, a likely-typo correction, and an aggregate 0–1 risk score with a coarse low/medium/high band. Pure DNS + heuristics — no SMTP mailbox probing and no third-party feed. Addresses are not persisted (transient validation only). Authentication: standard workspace auth (X-API-Key or dashboard session). Both endpoints require an authenticated workspace, but the auth level differs: single-address POST /email/validate additionally requires an owner or admin role, while POST /email/validate/bulk is open to any authenticated workspace member. A non-admin caller hitting POST /email/validate gets a 403.

Method	Path	Auth	Purpose
`POST`	`/api/v1/email/validate`	`owner` / `admin` role	Validate a single recipient address
`POST`	`/api/v1/email/validate/bulk`	Any workspace member	Validate a list of addresses in one call (max 1000)

POST /api/v1/email/validate

Requires an owner or admin role. A workspace member without one of these roles receives a 403. Request body:

{ "email": "user@example.com" }

Response data:

Field	Type	Description
`email`	string	The input, lower-cased + trimmed
`valid`	boolean	Syntactically sound and able to receive mail (a definitive no-MX flips this `false`)
`disposable`	boolean	Known disposable / throwaway provider
`role_based`	boolean	Role/group mailbox (`info@`, `support@`, …) rather than a person
`mx_found`	boolean \| null	Domain publishes a usable MX. `null` = lookup timed out (unknown, not a verdict)
`risk_score`	number	Aggregate `0`–`1` deliverability-risk score (higher = riskier)
`risk_band`	string	`low` \| `medium` \| `high`, derived from `risk_score`
`suggested_correction`	string \| null	A corrected address for a likely typo (e.g. `user@gmial.con` → `user@gmail.com`)
`reasons`	string[]	Short, human-readable notes explaining the verdict

POST /api/v1/email/validate/bulk

Available to any authenticated workspace member — no owner/admin role required. Validate up to 1000 addresses in one call. Input is de-duplicated case-insensitively before scoring. Request body:

{ "emails": ["alice@example.com", "support@example.com"] }

Response data:

{
  "summary": { "total": 2, "valid": 2, "invalid": 0, "risky": 1 },
  "results": [
    {
      "email": "alice@example.com",
      "valid": true,
      "reason": "deliverable",
      "mx_verified": true,
      "risk": "low",
      "risk_score": 0,
      "disposable": false,
      "role_based": false,
      "suggested_correction": null
    }
  ]
}

Each row carries a single machine-readable reason code — one of deliverable, invalid_syntax, no_mx_record, disposable_domain, role_account, possible_typo, or mx_unknown — so importers can branch deterministically. The summary.risky count is the number of deliverable but flagged rows (disposable / role / typo / non-low band) a sender should review before importing.

IP warm-up

Endpoints that plan, report, and gate an IP-warm-up ramp. When you send from a fresh IP or sender reputation, Orbit caps your daily outbound volume along a ramp that grows from a conservative day-1 seed (default 50/day) toward your target steady-state volume, so a high-volume sender ramps deliberately instead of spiking a cold IP. Volume above today’s cap is queued server-side until the cap resets — it is never authorised above the ceiling. All three endpoints are read-only, tenant-isolated, and require an operator role (owner / admin / developer).

Method	Path	Purpose
`GET`	`/api/v1/email/warmup-plan`	Compute the day-by-day ramp schedule (pure computation — nothing is persisted or sent)
`GET`	`/api/v1/email/warmup-status`	Where your account sits on the ramp today: current day, today’s reputation-adjusted cap, volume sent, and remaining headroom
`GET`	`/api/v1/email/warmup-enforcement`	Batch verdict for the volume you want to send now — `allow`, `partial`, or `block` — with how much fits today and when headroom reopens

All three accept the same query parameters: targetDailyVolume (required), plus optional startingVolume (day-1 seed, default 50/day) and growthFactor (per-day multiplier between 1.05 and 4, default 1.5). warmup-enforcement takes one additional required parameter: requested (the batch size you want to send).

GET /api/v1/email/warmup-plan

Compose the ramp before you commit to a send cadence. To reach a steady 5,000 emails/day from a 50/day seed at the default 1.5x growth:

curl "https://api.orbit.devotel.io/api/v1/email/warmup-plan?targetDailyVolume=5000&startingVolume=50&growthFactor=1.5" \
  -H "X-API-Key: $ORBIT_API_KEY"

Response data:

{
  "targetDailyVolume": 5000,
  "startingVolume": 50,
  "growthFactor": 1.5,
  "totalDays": 13,
  "truncated": false,
  "schedule": [
    { "day": 1, "maxVolume": 50, "cumulative": 50 },
    { "day": 2, "maxVolume": 75, "cumulative": 125 },
    { "day": 3, "maxVolume": 113, "cumulative": 238 },
    { "day": 4, "maxVolume": 170, "cumulative": 408 },
    { "day": 5, "maxVolume": 255, "cumulative": 663 },
    { "day": 6, "maxVolume": 383, "cumulative": 1046 },
    { "day": 7, "maxVolume": 575, "cumulative": 1621 },
    { "day": 8, "maxVolume": 863, "cumulative": 2484 },
    { "day": 9, "maxVolume": 1295, "cumulative": 3779 },
    { "day": 10, "maxVolume": 1943, "cumulative": 5722 },
    { "day": 11, "maxVolume": 2915, "cumulative": 8637 },
    { "day": 12, "maxVolume": 4373, "cumulative": 13010 },
    { "day": 13, "maxVolume": 5000, "cumulative": 18010 }
  ]
}

Each day’s maxVolume is that day’s send ceiling; cumulative is the running total across the ramp. truncated is false when the ramp reaches its target within 60 days — a true value means the inputs (high target, shallow growth) need a growth factor closer to 4, not a longer schedule.

GET /api/v1/email/warmup-status

Track the live position on that same ramp:

curl "https://api.orbit.devotel.io/api/v1/email/warmup-status?targetDailyVolume=5000&startingVolume=50&growthFactor=1.5" \
  -H "X-API-Key: $ORBIT_API_KEY"

Response data:

{
  "plan": { "targetDailyVolume": 5000, "totalDays": 13, "truncated": false, "schedule": [ … ] },
  "startedAt": "2026-08-22T09:14:00.000Z",
  "currentDay": 4,
  "baseCap": 170,
  "todayCap": 170,
  "sentToday": 140,
  "remaining": 30,
  "withinCap": true,
  "rampComplete": false,
  "rampState": "ramping",
  "feedbackReason": "reputation 'good' is healthy — full ramp"
}

rampState is the verdict to branch on: ramping (reputation healthy or not yet scored — today’s cap matches the plan), holding (reputation poor — cap halved), or throttled (reputation critical — cap quartered). When the state is holding or throttled, todayCap is below baseCap and feedbackReason explains why. Response data field reference:

Field	Type	Description
`startedAt`	string \| null	Timestamp of the first recorded outbound send the ramp is measured from; `null` before any send
`currentDay`	number	1-based ramp day for now
`baseCap`	number	Time-curve ceiling for today before reputation feedback
`todayCap`	number	Effective cap for today after live sending-reputation feedback is applied
`sentToday`	number	Outbound emails already sent today
`remaining`	number	Headroom left under today’s cap
`withinCap`	boolean	`false` once today’s volume reaches the cap
`rampComplete`	boolean	`true` once the ramp is finished (steady state)
`rampState`	string	`ramping`, `holding` (reputation poor), or `throttled` (reputation critical)
`feedbackReason`	string	Human-readable explanation of the feedback decision

GET /api/v1/email/warmup-enforcement

Pre-flight a batch against today’s headroom before dispatching it. If today is on the plan above with 40 already sent, a 2,000-email batch gets split:

curl "https://api.orbit.devotel.io/api/v1/email/warmup-enforcement?targetDailyVolume=5000&startingVolume=50&growthFactor=1.5&requested=2000" \
  -H "X-API-Key: $ORBIT_API_KEY"

Response data:

{
  "decision": "partial",
  "requested": 2000,
  "accepted": 130,
  "deferred": 1870,
  "todayCap": 170,
  "remaining": 130,
  "retryAfter": "2026-08-26T00:00:00.000Z",
  "rampState": "ramping",
  "reason": "1870 emails deferred until today's warm-up ceiling resets"
}

A whole-batch-fit answers decision: "allow" with deferred: 0 and retryAfter: null; a spent cap answers "block" with accepted: 0 and retryAfter pointing at the next UTC day boundary. Response data field reference:

Field	Type	Description
`decision`	string	`allow`, `partial`, or `block`
`requested`	number	The requested batch size
`accepted`	number	How many of the requested emails fit today
`deferred`	number	How many are deferred to a later ramp day
`todayCap`	number	Today’s effective (reputation-adjusted) send ceiling
`remaining`	number	Headroom before this batch is counted
`retryAfter`	string \| null	When headroom resets (next UTC day boundary); `null` when the whole batch was accepted
`rampState`	string	`ramping`, `holding`, or `throttled`
`reason`	string	Human-readable explanation of the verdict

A partial or block verdict is the same gate that holds email rows at queued in the Delivery Log once the day’s cap is spent — see Troubleshooting: message stuck in queued.

Integration recipe: validate, then send only the clean rows

Pair POST /api/v1/email/validate/bulk with the unified send so an importer never burns wallet credit or sender reputation on dead addresses:

# 1. Validate the imported list in one call
curl -X POST "https://api.orbit.devotel.io/api/v1/email/validate/bulk" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["alice@example.com", "support@example.com", "user@gmial.con"]}' \
  > validation-response.json

# 2. Keep only the rows the verdict marks deliverable, and send to those only
jq -c '.data.results[]
  | select(.valid == true)
  | { channel: "email", to: .email, subject: "Your receipt", body: "Thanks for your purchase." }' \
  validation-response.json | \
  while read -r payload; do
    curl -X POST "https://api.orbit.devotel.io/api/v1/messages" \
      -H "X-API-Key: $ORBIT_API_KEY" \
      -H "Content-Type: application/json" \
      -d "$payload"
  done

Rows the bulk verdict flags (disposable_domain, role_account, possible_typo, non-low risk) land in summary.risky — review those per your sending policy before importing; rows with valid: false (invalid_syntax, no_mx_record) are dropped outright. During an active warm-up ramp, gate step 3 on warmup-enforcement so the batch does not outpace today’s cap.

API Reference

All Endpoints

Email API: list-unsubscribe and address validation

Email API

Using the SDKs

Sending email

Unsubscribe

Recipient validation

POST /api/v1/email/validate

POST /api/v1/email/validate/bulk

IP warm-up

GET /api/v1/email/warmup-plan

GET /api/v1/email/warmup-status

GET /api/v1/email/warmup-enforcement

Integration recipe: validate, then send only the clean rows

See also

​Email API

​Using the SDKs

​Sending email

​Unsubscribe

​Recipient validation

​POST /api/v1/email/validate

​POST /api/v1/email/validate/bulk

​IP warm-up

​GET /api/v1/email/warmup-plan

​GET /api/v1/email/warmup-status

​GET /api/v1/email/warmup-enforcement

​Integration recipe: validate, then send only the clean rows

​See also

Email API

Using the SDKs

Sending email

Unsubscribe

Recipient validation

POST /api/v1/email/validate

POST /api/v1/email/validate/bulk

IP warm-up

GET /api/v1/email/warmup-plan

GET /api/v1/email/warmup-status

GET /api/v1/email/warmup-enforcement

Integration recipe: validate, then send only the clean rows

See also