Developer docs

curl -sS https://api.sendoka.com/api/v1/emails \
  -H "Authorization: Bearer $SENDOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@sandbox.sendoka.com",
    "to": ["user@example.com"],
    "subject": "Hello from Sendoka",
    "html": "<p>It works.</p>"
  }'

const res = await fetch("https://api.sendoka.com/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SENDOKA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "you@sandbox.sendoka.com",
    to: ["user@example.com"],
    subject: "Hello from Sendoka",
    html: "<p>It works.</p>",
  }),
});

const msg = await res.json();
console.log(msg.id);

import os, httpx

r = httpx.post(
    "https://api.sendoka.com/api/v1/emails",
    headers={"Authorization": f"Bearer {os.environ['SENDOKA_API_KEY']}"},
    json={
        "from": "you@sandbox.sendoka.com",
        "to": ["user@example.com"],
        "subject": "Hello from Sendoka",
        "html": "<p>It works.</p>",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json()["id"])

Authorization: Bearer sok_live_your_api_key_here

{
  "error": {
    "type": "validation_error",
    "code": "VALIDATION_ERROR",
    "message": "Subject is required",
    "request_id": "req_Hg8JpNvKXWg4f",
    "errors": [
      { "path": ["subject"], "code": "invalid_type", "message": "Required" }
    ]
  }
}

curl -X POST https://api.sendoka.com/api/v1/emails \
  -H "Authorization: Bearer $SENDOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Welcome",
    "html": "<h1>Welcome</h1>"
  }'

await fetch("https://api.sendoka.com/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SENDOKA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "hello@yourdomain.com",
    to: ["user@example.com"],
    subject: "Welcome",
    html: "<h1>Welcome</h1>",
  }),
});

httpx.post(
    "https://api.sendoka.com/api/v1/emails",
    headers={
        "Authorization": f"Bearer {KEY}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "from": "hello@yourdomain.com",
        "to": ["user@example.com"],
        "subject": "Welcome",
        "html": "<h1>Welcome</h1>",
    },
)

{
  "from":    "hello@yourdomain.com",
  "to":      ["user@example.com"],
  "subject": "Welcome",
  "html":    "<h1>Welcome</h1>"
}

{
  "from": "hello@yourdomain.com",
  "to":   ["user@example.com"],
  "template": "order_shipped",
  "variables": {
    "order_id":     "ord_abc123",
    "tracking_url": "https://track.example.com/ord_abc123"
  }
}

{
  "from":    "hello@yourdomain.com",
  "to":      ["user@example.com"],
  "subject": "Reminder: appointment tomorrow at 9am",
  "html":    "<p>...</p>",
  "scheduled_local": "2026-05-19 09:00",
  "scheduled_at_tz": "America/New_York"
}

{
  "from":     "hello@yourdomain.com",
  "to":       ["user@example.com"],
  "cc":       ["manager@example.com"],
  "bcc":      ["audit@example.com"],
  "reply_to": ["support@yourdomain.com"],
  "subject":  "Welcome",
  "html":     "<h1>Welcome</h1>"
}

{
  "from":    "hello@yourdomain.com",
  "to":      ["user@example.com"],
  "subject": "Your invoice",
  "html":    "<p>See attached.</p>",
  "attachments": [
    {
      "filename":     "invoice.pdf",
      "content":      "<base64-encoded bytes>",
      "content_type": "application/pdf"
    },
    {
      "filename":     "receipt.png",
      "url":          "https://example.com/receipt.png",
      "content_type": "image/png"
    }
  ]
}

{
  "from":         "hello@yourdomain.com",
  "to":           ["user@example.com"],
  "subject":      "Newsletter",
  "html":         "<p>Visit our <a href=\"https://example.com\">site</a></p>",
  "track_opens":  true,
  "track_clicks": true,
  "tags":         ["newsletter"]
}

{
  "id": "msg_01HN...",
  "channel": "email",
  "status": "sent",
  "created_at": "2026-04-22T10:14:22.113Z"
}

curl -X POST https://api.sendoka.com/api/v1/sms \
  -H "Authorization: Bearer $SENDOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "body": "Your code is 1234"
  }'

await fetch("https://api.sendoka.com/api/v1/sms", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SENDOKA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    from: "+15551234567",
    to: "+15559876543",
    body: "Your code is 1234",
  }),
});

httpx.post(
    "https://api.sendoka.com/api/v1/sms",
    headers={
        "Authorization": f"Bearer {KEY}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "from": "+15551234567",
        "to":   "+15559876543",
        "body": "Your code is 1234",
    },
)

{
  "from": "+15551234567",
  "to":   "+15559876543",
  "body": "Your code is 1234"
}

// Register an alphanumeric sender (UK / AU / EU)
POST /api/v1/phone-numbers
{
  "kind": "alphanumeric",
  "sender_id": "Acme",
  "iso_country": "GB"
}

{
  "from": "+15551234567",
  "to":   "+15559876543",
  "template": "order_shipped",
  "variables": {
    "order_id":     "ord_abc123",
    "tracking_url": "https://track.example.com/ord_abc123"
  }
}

{
  "from": "+15551234567",
  "to":   "+15559876543",
  "body": "Reminder: appointment tomorrow at 9am",
  "scheduled_local": "2026-05-18 09:00",
  "scheduled_at_tz": "America/New_York"
}

{
  "from_pool": "support",
  "to":        "+15559876543",
  "body":      "Your support ticket has an update."
}

{
  "from": "+15551234567",
  "to":   "+15559876543",
  "body": "Receipt attached. Reply STOP to opt out.",
  "media_url": ["https://example.com/receipt.png"],
  "tags": ["transactional", "receipt"],
  "metadata": {
    "order_id": "ord_abc123",
    "user_id":  "usr_42"
  }
}

{
  "id": "msg_01HN...",
  "channel": "sms",
  "status": "sent",
  "created_at": "2026-04-22T10:14:22.113Z"
}

[
  { "from": "+15555550100", "to": "+15555550199", "body": "Personalized 1", "tags": ["promo"] },
  { "from": "+15555550100", "to": "+15555550200", "body": "Personalized 2", "tags": ["promo"] }
]

{
  "from": "Ezzeefy",
  "to":   ["+61470594555", "+61470594556", "+61470594557"],
  "body": "Sale ends tonight",
  "tags": ["promo"],
  "metadata": { "campaign": "sale_q2" }
}

[
  { "from": "hello@yourdomain.com", "to": ["a@example.com"], "subject": "Personalized 1", "html": "<p>hi 1</p>" },
  { "from": "hello@yourdomain.com", "to": ["b@example.com"], "subject": "Personalized 2", "html": "<p>hi 2</p>" }
]

{
  "from": "hello@yourdomain.com",
  "to":   ["a@example.com", "b@example.com", "c@example.com"],
  "subject": "Newsletter",
  "html":    "<h1>This month's update</h1>",
  "reply_to": ["support@yourdomain.com"],
  "tags": ["newsletter"],
  "metadata": { "campaign": "may_2026" }
}

{
  "data": [
    { "index": 0, "id": "msg_...", "status": "sent", "error": null },
    { "index": 1, "id": null, "status": "failed",
      "error": { "code": "VALIDATION_ERROR", "message": "..." } }
  ],
  "total": 2,
  "succeeded": 1,
  "failed": 1
}

{
  "from": "hello@yourdomain.com",
  "to": ["user@example.com"],
  "subject": "Launch day",
  "html": "<p>...</p>",
  "scheduled_at": "2026-05-01T12:00:00Z"
}

{
  "scheduled_local": "09:00",
  "scheduled_at_tz": "America/New_York"
}

{
  "from": "hello@yourdomain.com",
  "to": ["user@example.com"],
  "template": "welcome-v2",
  "variables": { "name": "Fareed", "plan": "Pro" }
}

// POST /audiences/:id/send
{
  "from": "news@yourdomain.com",
  "template": "newsletter",
  "channel": "email"
}

// → 200
{ "audience_id": "aud_...", "queued": 23417, "skipped_suppressed": 112, "status": "queued" }

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyIyMDI2..."
}

X-Sendoka-Event: message.delivered
X-Sendoka-Delivery-Id: whd_01HN...
X-Sendoka-Signature: t=1713820800,v1=<hex>

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(rawBody: string, signature: string, secret: string) {
  const [tPart, vPart] = signature.split(",");
  const t = tPart.split("=")[1];
  const v = vPart.split("=")[1];
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) throw new Error("stale");
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  if (!timingSafeEqual(Buffer.from(v, "hex"), Buffer.from(expected, "hex"))) {
    throw new Error("bad signature");
  }
  return JSON.parse(rawBody);
}

{
  "event": "message.delivered",
  "data": {
    "message_id": "msg_01HN...",
    "channel": "email",
    "status": "delivered"
  },
  "timestamp": "2026-04-22T10:14:22.113Z"
}

curl -X POST https://api.sendoka.com/api/v1/emails \
  -H "Authorization: Bearer $SENDOKA_API_KEY" \
  -H "Idempotency-Key: welcome:user_12345:signup" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1713820800
X-RateLimit-Plan: pro
X-RateLimit-Scope: org | key

// Create tenant
{
  "name": "Acme Corp",
  "slug": "acme",
  "external_ref": "cust_12345"
}