SMTP relay recipes: send email over HTTP

The SMTP relay capability is a second ingress path for the email channel: your client submits an RFC 5322 message over the authenticated SMTP edge described on Channels → SMTP relay, and the relay maps the session onto the same HTTP payload POST /api/v1/messages/email produces. This guide walks the equivalent HTTP flow end to end — the request body with an attachment, the response a happy path returns, the error branches worth coding against, and each SDK’s call — so you can model or verify client behaviour without touching an SMTP socket. Use this flow before writing SMTP client code, or when you want the SMTP relay’s pipeline guarantees (suppression, verified-sender enforcement, shared rate pool) while keeping payloads and error codes fully visible.

1. Send with an attachment

POST /api/v1/messages/email accepts either html or text (at least one is required) plus an optional attachments array — each entry carries filename, content_type, and either a url (an Orbit Files API URL) or inline base64 content.

curl -X POST https://api.orbit.devotel.io/api/v1/messages/email \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt-v1" \
  -d '{
    "to": "customer@example.com",
    "from": "Devotel Orbit <receipts@mail.example.com>",
    "subject": "Your receipt",
    "html": "<p>Thanks for your order — receipt attached.</p>",
    "text": "Thanks for your order — receipt attached.",
    "attachments": [
      {
        "filename": "receipt-1042.pdf",
        "content_type": "application/pdf",
        "content": "JVBERi0xLjQKJ2NhbXBsaW5nIGJ5dGVzJwo="
      }
    ],
    "metadata": { "order_id": "1042" }
  }'

Two limits to design around: attachments cap at 10 MB per file, 25 MB per email, 20 files per send, and content_type must be on the MIME allowlist — see Email attachments for the full list and for when to use a Files URL instead of inline base64. The Idempotency-Key header makes client retries safe: the same key replays the original response instead of double-sending. The same body shape is exactly what the SMTP relay produces after mapping an RFC 5322 submission — envelope RCPT TO recipients become to, the From: header becomes from, and the HTML part (preferred over plain text) becomes html.

2. The 202 response envelope

A successful send returns 202 with the message record under data plus a meta block that also carries the request id you saw in the X-Request-Id response header:

HTTP/1.1 202 Accepted
X-Request-Id: req_9f3d2c7b1a54
Idempotency-Replay: false

{
  "data": {
    "id": "msg_01J8ZK4M6BQRF3WT6XH2QM2Pkm",
    "status": "queued",
    "channel": "email",
    "from": "receipts@mail.example.com",
    "to": "customer@example.com",
    "body": "Thanks for your order — receipt attached.",
    "price": "0.0012",
    "currency": "USD",
    "external_id": null,
    "created_at": "2026-09-06T14:22:07.000Z"
  },
  "meta": {
    "request_id": "req_9f3d2c7b1a54",
    "timestamp": "2026-09-06T14:22:07.104Z"
  }
}

status at acceptance time is queued (or scheduled when you pass scheduled_at); poll GET /api/v1/messages/{id} or consume the message-status webhooks to follow it to sent/delivered. price is the credits cost of the send.

3. Error branches to handle

Every error returns the standard envelope { "error": { "code", "message", "status" }, "meta": { ... } }. Three code values account for most production failures on this path:

INVALID_RECIPIENT — 422

The recipient address failed the per-recipient gate (malformed mailbox, list-hygiene check, or suppression). The message is refused before queueing and you are not charged.

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Recipient address failed validation: user@@example",
    "status": 422,
    "details": { "to": "user@@example" }
  },
  "meta": {
    "request_id": "req_2e8d1c",
    "timestamp": "2026-09-06T14:23:01.337Z"
  }
}

Fix: validate recipient addresses before sending, or scrub the list with the address-validation endpoint. A suppressed address (hard bounce, complaint, or unsubscribe) is deliberately refused — re-engage it only after removing the suppression entry (see Bounce and Complaint Handling).

CHANNEL_NOT_CONFIGURED — 503

The tenant has no working email provider: a sender domain was never verified, the provider credentials were revoked, or the channel bootstrap skipped the lane. Nothing is queued.

{
  "error": {
    "code": "CHANNEL_NOT_CONFIGURED",
    "message": "Email channel has no provider configured for this tenant",
    "status": 503,
    "details": { "channel": "email" }
  },
  "meta": {
    "request_id": "req_4ad0bb",
    "timestamp": "2026-09-06T14:24:10.009Z"
  }
}

Fix: complete sender and domain setup under Channels → Email (the same verified domain governs the SMTP relay — a relayed 554 after DATA is the SMTP-session equivalent of this branch). Surface details.provider_message if present for the provider-side detail.

RATE_LIMITED — 429

The shared email rate pool (default 200 messages per minute per tenant, shared with SMTP-relay ingress and burst fanout) is exhausted. The response usually carries a retry_after hint in details.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Email rate pool exceeded for this tenant",
    "status": 429,
    "details": { "retry_after": 12, "pool": "200/min" }
  },
  "meta": {
    "request_id": "req_78cd01",
    "timestamp": "2026-09-06T14:25:33.811Z"
  }
}

Fix: back off using the returned retry_after window, then retry. Because HTTP and SMTP relay traffic draw from one pool, moving sends between the two paths does not dodge the limit — see Rate limits. Other codes you may see on this path: VALIDATION_ERROR (bad payload shape or attachment limit), QUOTA_EXCEEDED (billing cap), and MESSAGE_SEND_FAILED (provider-side failure — retry once, then alert). The full catalog lives on the Email channel page.

4. SDK snippets

Each SDK wraps POST /api/v1/messages/email; the examples below send the same attachment email and read the same code branches. Attachments with URL url fields are supported on all four SDKs; inline base64 content follows the same body shape shown in the curl above.

Node.js — `@devotel-orbit/node`

import { Devotel } from '@devotel-orbit/node';

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

try {
  const res = await orbit.messages.sendEmail({
    to: 'customer@example.com',
    from: 'Devotel Orbit <receipts@mail.example.com>',
    subject: 'Your receipt',
    html: '<p>Thanks for your order — receipt attached.</p>',
    attachments: [
      {
        filename: 'receipt-1042.pdf',
        content_type: 'application/pdf',
        content: 'JVBERi0xLjQKJ2NhbXBsaW5nIGJ5dGVzJwo=',
      },
    ],
  });
  console.log(res.data.id, res.data.status); // msg_…, 'queued'
} catch (err: any) {
  const code = err?.code ?? err?.error?.code;
  if (code === 'INVALID_RECIPIENT') {
    // scrub the address before resending
  } else if (code === 'CHANNEL_NOT_CONFIGURED') {
    // finish sender/domain setup under Channels → Email
  } else if (code === 'RATE_LIMITED') {
    // back off and retry using err.error.details.retry_after
  }
  throw err;
}

Python — `orbit_sdk`

from orbit_sdk import OrbitClient

client = OrbitClient.from_api_key("dv_live_sk_...")
try:
    res = client.messages.send_email(
        to="customer@example.com",
        subject="Your receipt",
        body="<p>Thanks for your order — receipt attached.</p>",
    )
    print(res["data"]["id"], res["data"]["status"])
except Exception as err:
    payload = getattr(err, "response", {}) or getattr(err, "args", [{}])[0]
    code = (payload.get("error") or {}).get("code") if isinstance(payload, dict) else None
    if code == "INVALID_RECIPIENT":
        pass  # scrub the address
    elif code == "CHANNEL_NOT_CONFIGURED":
        pass  # finish email setup under Channels → Email
    elif code == "RATE_LIMITED":
        pass  # back off and retry
    raise

Go — `devotel/orbit`

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

res, err := client.Messages().SendEmail(context.Background(),
    orbit.SendEmailInput{
        To:      "customer@example.com",
        Subject: "Your receipt",
        Body:    "<p>Thanks for your order — receipt attached.</p>",
    })
if err != nil {
    var apiErr *orbit.APIError
    if errors.As(err, &apiErr) {
        switch apiErr.Code {
        case "INVALID_RECIPIENT":
            // scrub the address before resending
        case "CHANNEL_NOT_CONFIGURED":
            // finish email setup under Channels → Email
        case "RATE_LIMITED":
            // back off and retry
        }
    }
    return
}
fmt.Println(res.Data.ID, res.Data.Status) // msg_…, queued

PHP — `devotel/orbit`

$client = OrbitClient::fromApiKey('dv_live_sk_...');

try {
    $res = $client->messages->sendEmail(
        'customer@example.com',
        'Your receipt',
        '<p>Thanks for your order — receipt attached.</p>',
    );
    echo $res['data']['id'] . ' ' . $res['data']['status'];
} catch (\Exception $err) {
    $code = $err->code ?? null;
    match ($code) {
        'INVALID_RECIPIENT' => null,       // scrub the address
        'CHANNEL_NOT_CONFIGURED' => null,  // finish email setup
        'RATE_LIMITED' => null,            // back off and retry
        default => null,
    };
    throw $err;
}

The retry_after value in details is your best backoff hint — use it rather than a fixed sleep.

Where it connects back to SMTP

Once the client works over HTTP, point it at the SMTP edge only if HTTP is not practical — see Connection profile on the SMTP relay channel page for ports and the apikey sentinel. The same API key gates both paths, the same sender domain gates them both, and suppression drawn from either path applies to the other.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

SMTP relay recipes: full request–response–error loop

SMTP relay recipes: send email over HTTP

1. Send with an attachment

2. The 202 response envelope

3. Error branches to handle

INVALID_RECIPIENT — 422

CHANNEL_NOT_CONFIGURED — 503

RATE_LIMITED — 429

4. SDK snippets

Node.js — `@devotel-orbit/node`

Python — `orbit_sdk`

Go — `devotel/orbit`

PHP — `devotel/orbit`

Where it connects back to SMTP

​SMTP relay recipes: send email over HTTP

​1. Send with an attachment

​2. The 202 response envelope

​3. Error branches to handle

​INVALID_RECIPIENT — 422

​CHANNEL_NOT_CONFIGURED — 503

​RATE_LIMITED — 429

​4. SDK snippets

​Node.js — @devotel-orbit/node

​Python — orbit_sdk

​Go — devotel/orbit

​PHP — devotel/orbit

​Where it connects back to SMTP

SMTP relay recipes: send email over HTTP

1. Send with an attachment

2. The 202 response envelope

3. Error branches to handle

INVALID_RECIPIENT — 422

CHANNEL_NOT_CONFIGURED — 503

RATE_LIMITED — 429

4. SDK snippets

Node.js — `@devotel-orbit/node`

Python — `orbit_sdk`

Go — `devotel/orbit`

PHP — `devotel/orbit`

Where it connects back to SMTP