Skip to main content

Documentation Index

Fetch the complete documentation index at: https://orbit-docs.devotel.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Email attachments

Email sends through POST /api/v1/messages/email accept up to 20 attachments per email, totalling 25 MB across all attachments (RFC 5322 ceiling), with a per-file cap of 10 MB. Each attachment is referenced either by url (preferred — pre-uploaded to your file store or to Orbit’s /v1/files) or as inline base64 content. URL-based attachments are fetched server-side, base64-encoded, and forwarded to the upstream provider. Orbit applies an SSRF allowlist so an attacker who controls a url field can’t pivot Orbit’s outbound network into your private network.

​
Limits

ConstraintValue
Per-attachment size10 MB
Total per-email size25 MB (across all attachments combined)
Max attachments per email20

​
MIME allowlist

The content_type field must be one of: 
application/pdf
application/msword
application/vnd.openxmlformats-officedocument.wordprocessingml.document  (.docx)
application/vnd.ms-excel
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet         (.xlsx)
application/vnd.ms-powerpoint
application/vnd.openxmlformats-officedocument.presentationml.presentation (.pptx)
text/csv
text/plain
application/zip
image/jpeg
image/png
image/gif
image/webp
Anything else is rejected with 422 VALIDATION_ERROR. We block executables and unknown types so a customer can’t accidentally hand their domain reputation to a malware payload. image/svg+xml is intentionally NOT on the list — SVG files are XML and can embed <script> elements, event handlers, or <foreignObject> HTML. If we accepted SVG attachments, a forwarded SVG could turn into stored XSS the moment a downstream client rendered it inline.

​
Filename rules

  • Required, max 255 chars.
  • May not contain /, \\, or .. — guards against path traversal in downstream tools that re-emit the filename.
  • The filename surfaces verbatim in the recipient’s mail client.

​
URL vs content

ApproachWhen to use
urlFiles already hosted on your CDN, S3, or /v1/files. Preferred — keeps the request small and lets the platform stream the bytes server-side.
contentSmall files generated inline (signed PDFs, dynamic CSVs) where the round-trip to upload first isn’t worth it. Always base64-encoded.
Each attachment object MUST include either url or content — not both, not neither.

​
Send with curl

​
URL-based attachment

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": "billing@yourdomain.com",
    "subject": "Your invoice for May 2026",
    "html": "<p>Your invoice is attached.</p>",
    "attachments": [
      {
        "filename": "invoice-may-2026.pdf",
        "content_type": "application/pdf",
        "url": "https://files.yourdomain.com/invoices/may-2026.pdf",
        "size": 348112
      }
    ]
  }'

​
Inline base64 attachment

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": "billing@yourdomain.com",
    "subject": "Receipt",
    "html": "<p>Receipt attached.</p>",
    "attachments": [
      {
        "filename": "receipt.pdf",
        "content_type": "application/pdf",
        "content": "JVBERi0xLjQKJeLjz9MK..."
      }
    ]
  }'

​
Send with the Node.js SDK

import { Devotel } from "@devotel/orbit-sdk";
import { readFileSync } from "node:fs";

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

await orbit.messages.send({
  channel: "email",
  to: "user@example.com",
  from: "billing@yourdomain.com",
  subject: "Your invoice for May 2026",
  html: "<p>Your invoice is attached.</p>",
  attachments: [
    {
      filename: "invoice-may-2026.pdf",
      content_type: "application/pdf",
      content: readFileSync("./invoice-may-2026.pdf").toString("base64"),
    },
  ],
});

​
Other languages

Only the Node.js SDK (@devotel/orbit-sdk) and the browser SDK (@devotel/orbit-web-sdk) are GA today. Python / Go / Java / PHP / Ruby / .NET SDKs are on the roadmap but not yet shipped — call the REST endpoint above with any HTTP client until they’re published.

​
Validation errors

CodeHTTPCause
VALIDATION_ERROR422Filename contains /, \\, or ..; MIME type not on the allowlist; total size exceeds 25 MB; more than 20 attachments; neither url nor content supplied.
EMAIL_ATTACHMENT_FETCH_FAILED422Orbit could not fetch a url-style attachment (timeout, 404, host outside the SSRF allowlist). Re-host the file or use the /v1/files upload endpoint.
EMAIL_ATTACHMENT_TOO_LARGE413The fetched bytes exceed the per-file 10 MB cap.

​
See also