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

{
  "domain": "mail.acme.com",
  "default_from_email": "sales@acme.com",
  "default_from_name": "Acme Sales",
  "default_reply_to": "support@acme.com",
  "isDefault": true
}

{
  "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

{
  "default_from_email": "offers@acme.com",
  "default_from_name": "Acme Offers",
  "default_reply_to": "support@acme.com"
}

{
  "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

{
  "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

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

{
  "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

{
  "emails": [
    "alice@example.com",
    "bad.domain",
    "bob@example.com"
  ]
}

{
  "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

{
  "email": "customer@example.com",
  "reason": "manual"
}

{
  "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

{
  "csv": "email\nbounced@example.com\ncomplained@example.com",
  "reason": "hard_bounce"
}

{
  "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.

Warmup, dedicated IP, 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

{
  "pattern": "support/tickets-<tenant>",
  "destination": {
    "type": "webhook",
    "url": "https://your-app.example/inbound/email",
    "authHeader": "Bearer your-token"
  }
}

{
  "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. The dedicated-IP flow is three calls: GET /api/v1/email/dedicated-sending/eligibility (trailing-30-day volume ≥ 50 000/day), POST /api/v1/email/dedicated-sending/request with a free-text justification, and GET /api/v1/email/dedicated-sending to read eligibility plus request status (pending/approved/fulfilled/denied).

API Reference

All Endpoints

Worked email lifecycle samples