API Reference

30-second quickstart

Get your API key from the dashboard → API Keys tab. Then send your first email.

curl https://api.senddio.com/v1/send \
  -H "Authorization: Bearer sdo_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "from": "you@yourdomain.com",
    "to": "recipient@example.com",
    "subject": "Hello from Senddio",
    "html": "<p>It works.</p>"
  }'

{ "id": "sdo_msg_abc123", "status": "queued" }

A successful immediate send returns HTTP 202. Delivery happens asynchronously — use GET /v1/messages/:id to check status, or configure a webhook to receive delivery events.

Authentication

Pass your API key in the Authorization header on every request.

Authorization: Bearer sdo_live_<32 chars>

API key types

Key scopes

Auth errors

POST /v1/send

The universal send endpoint. Set the required channel field to select the delivery provider. Validation is synchronous; delivery is queued asynchronously.

Legacy alias: POST /v1/emails accepts the same email body without a channel field. Prefer /v1/send for new integrations.

{ "id": "sdo_msg_<cuid2>", "status": "queued" }

Email

{
  "channel": "email",
  "from": "hello@yourdomain.com",
  "fromName": "Your Company",
  "to": "user@example.com",
  "subject": "Welcome",
  "html": "<p>Hello!</p>",
  "text": "Hello!",
  "replyTo": "support@yourdomain.com",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "tag": "onboarding",
  "messageType": "transactional",
  "trackOpens": true,
  "trackClicks": true,
  "headers": { "X-Custom-Header": "value" }
}

Delivery isolation: transactional and broadcast email use separate sending IP pools, so bulk-mail IP reputation spillover is reduced for password resets, receipts and account notifications. Shared domain reputation and recipient policies still affect delivery. Existing integrations that omit messageType remain transactional. The legacy send_broadcast tag is recognized as broadcast for compatibility, but new integrations should classify mail explicitly.

Node.js example

const res = await fetch('https://api.senddio.com/v1/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sdo_live_<your_key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    channel: 'email',
    from: 'hello@yourdomain.com',
    to: 'user@example.com',
    subject: 'Welcome',
    html: '<p>Hello!</p>',
  }),
});
const { id, status } = await res.json();
// { id: 'sdo_msg_abc123', status: 'queued' }

SMS

Requires an SMS sender number provisioned in dashboard → Channels. Numbers must be in E.164 format.

{
  "channel": "sms",
  "from": "+14155552671",
  "to": "+447911123456",
  "body": "Your verification code is 482912",
  "tag": "otp"
}

WhatsApp

Requires WhatsApp Business API configured via Channels. Sender must be your WhatsApp Business number.

{
  "channel": "whatsapp",
  "from": "+14155552671",
  "to": "+447911123456",
  "body": "Hello from WhatsApp",
  "tag": "support"
}

Push (FCM)

Requires Firebase Cloud Messaging configured in Channels. Pass the device FCM registration token as to.

{
  "channel": "push",
  "to": "<FCM_registration_token>",
  "title": "New message",
  "body": "You have a new message from Alex",
  "data": { "messageId": "msg_123", "type": "chat" },
  "tag": "chat"
}

Slack

Requires a Slack app token configured in Channels. Pass a channel ID (C01234567) or user ID (U01234567) as to.

{
  "channel": "slack",
  "to": "C01234ABCDE",
  "body": "Deployment to production succeeded",
  "tag": "ops"
}

Telegram

Requires a Telegram Bot token configured in Channels. Pass the chat ID as to.

{
  "channel": "telegram",
  "to": "123456789",
  "body": "Your order #4821 has shipped",
  "tag": "fulfillment"
}

GET /v1/messages

List sent messages for your organisation with optional filters. Cursor-paginated.

curl "https://api.senddio.com/v1/messages?channel=email&status=delivered&limit=25" \
  -H "Authorization: Bearer sdo_live_<your_key>"

Query parameters

GET /v1/messages/:id

Retrieve a single message with its full delivery event timeline. The id is the sdo_msg_-prefixed value returned by POST /v1/send.

curl "https://api.senddio.com/v1/messages/sdo_msg_abc123" \
  -H "Authorization: Bearer sdo_live_<your_key>"

Errors

Every error response uses the same JSON shape. message is a human-readable instruction. code is a stable machine string you can switch on. issues appears on 422 responses with field-level detail.

{
  "error": "validation_error",
  "message": "Request body failed validation. See issues for field-level detail.",
  "code": "VALIDATION_FAILED",
  "issues": [
    { "path": ["from"], "message": "Invalid email" }
  ]
}

HTTP status codes

Machine error codes

Rate limits

Every response includes rate-limit headers. The daily limit resets at midnight UTC — not a rolling 24-hour window — so you can predict exactly when capacity returns.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1727913600

Plan limits

SMS, WhatsApp, and push channels have separate per-plan safety caps. Check your dashboard for current channel quotas.